From 64b2925aa1d86462dad9a1391c6b9cd32fc12738 Mon Sep 17 00:00:00 2001 From: renzp94 <1074720760@qq.com> Date: Thu, 16 May 2024 13:14:38 +0800 Subject: [PATCH] docs: init --- .github/workflows/docs-deploy.yml | 42 + .gitignore | 20 + docs/.vitepress/config.ts | 93 + docs/package.json | 3 + docs/pages/configs.md | 207 + docs/pages/features.md | 91 + docs/pages/guide/cli.md | 71 + docs/pages/guide/getting-started.md | 72 + docs/pages/guide/project-structure.md | 37 + docs/pages/guide/what-is.md | 3 + docs/pages/problems.md | 137 + docs/public/logo.png | Bin 0 -> 887379 bytes package.json | 6 +- pnpm-lock.yaml | 16284 ++++++++++++++---------- 14 files changed, 10487 insertions(+), 6579 deletions(-) create mode 100644 .github/workflows/docs-deploy.yml create mode 100644 docs/.vitepress/config.ts create mode 100644 docs/package.json create mode 100644 docs/pages/configs.md create mode 100644 docs/pages/features.md create mode 100644 docs/pages/guide/cli.md create mode 100644 docs/pages/guide/getting-started.md create mode 100644 docs/pages/guide/project-structure.md create mode 100644 docs/pages/guide/what-is.md create mode 100644 docs/pages/problems.md create mode 100644 docs/public/logo.png diff --git a/.github/workflows/docs-deploy.yml b/.github/workflows/docs-deploy.yml new file mode 100644 index 0000000..3673de4 --- /dev/null +++ b/.github/workflows/docs-deploy.yml @@ -0,0 +1,42 @@ +name: Docs Deploy +on: + push: + branches: main + pull_request: + branches: main + +jobs: + deploy: + name: Docs Deploy + runs-on: ubuntu-latest + + permissions: + id-token: write # Needed for auth with Deno Deploy + contents: read # Needed to clone the repository + + steps: + - name: Clone repository + uses: actions/checkout@v4 + + - name: Install Deno + uses: denoland/setup-deno@v1 + with: + deno-version: v1.x + + - name: Install Node.js + uses: actions/setup-node@v4 + with: + node-version: lts/* + + - name: Install step + run: "npm install" + + - name: Build step + run: "npm run docs:build" + + - name: Upload to Deno Deploy + uses: denoland/deployctl@v1 + with: + project: "rzpack" + entrypoint: "https://deno.land/std/http/file_server.ts" + root: "docs/.vitepress/dist" diff --git a/.gitignore b/.gitignore index 294e9e1..0006fe3 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,23 @@ package-lock.json index.d.ts .DS_Store dist +docs/.vitepress/cache/deps/_metadata.json +docs/.vitepress/cache/deps/@theme_index.js +docs/.vitepress/cache/deps/@theme_index.js.map +docs/.vitepress/cache/deps/chunk-HWKKPLDN.js +docs/.vitepress/cache/deps/chunk-HWKKPLDN.js.map +docs/.vitepress/cache/deps/chunk-VDV77W7A.js +docs/.vitepress/cache/deps/chunk-VDV77W7A.js.map +docs/.vitepress/cache/deps/package.json +docs/.vitepress/cache/deps/vitepress___@vue_devtools-api.js +docs/.vitepress/cache/deps/vitepress___@vue_devtools-api.js.map +docs/.vitepress/cache/deps/vitepress___@vueuse_core.js +docs/.vitepress/cache/deps/vitepress___@vueuse_core.js.map +docs/.vitepress/cache/deps/vitepress___@vueuse_integrations_useFocusTrap.js +docs/.vitepress/cache/deps/vitepress___@vueuse_integrations_useFocusTrap.js.map +docs/.vitepress/cache/deps/vitepress___mark__js_src_vanilla__js.js +docs/.vitepress/cache/deps/vitepress___mark__js_src_vanilla__js.js.map +docs/.vitepress/cache/deps/vitepress___minisearch.js +docs/.vitepress/cache/deps/vitepress___minisearch.js.map +docs/.vitepress/cache/deps/vue.js +docs/.vitepress/cache/deps/vue.js.map diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts new file mode 100644 index 0000000..175a37b --- /dev/null +++ b/docs/.vitepress/config.ts @@ -0,0 +1,93 @@ +import { defineConfig } from 'vitepress' +import pkg from '../../packages/rzpack/package.json' + +export default defineConfig({ + title: 'rzpack', + description: '一款基于Webpack5开发的React打包工具', + lastUpdated: true, + metaChunk: true, + rewrites: { + 'pages/guide/getting-started.md': 'index.md', + 'pages/features.md': 'features.md', + 'pages/problems.md': 'problems.md', + 'pages/configs.md': 'configs.md', + 'pages/:category/:page.md': ':category/:page.md', + }, + head: [['link', { rel: 'icon', type: 'image/png', href: '/logo.png' }]], + themeConfig: { + logo: { + src: '/logo.png', + style: 'border-radius: 50%;height: 32px;width: 32px;', + }, + siteTitle: 'rzpack', + search: { + provider: 'local', + options: { + translations: { + button: { + buttonText: '搜索文档', + buttonAriaLabel: '搜索文档', + }, + modal: { + noResultsText: '无法找到相关结果', + resetButtonTitle: '清除查询条件', + footer: { + selectText: '选择', + navigateText: '切换', + }, + }, + }, + }, + }, + nav: [ + { + text: pkg.version, + link: '/', + }, + ], + socialLinks: [ + { icon: 'github', link: 'https://github.com/renzp94/rzpack' }, + ], + sidebar: [ + { + text: '简介', + items: [ + { text: '什么是rzpack?', link: '/guide/what-is' }, + { text: '快速开始', link: '/' }, + { text: '命令行界面', link: '/guide/cli' }, + { text: '项目结构', link: '/guide/project-structure' }, + ], + }, + { + text: '功能', + link: '/features', + }, + { + text: '配置', + link: '/configs', + }, + { + text: '常见问题', + link: '/problems', + }, + ], + editLink: { + pattern: 'https://github.com/renzp94/rzpack/edit/main/docs/:path', + text: '在 GitHub 上编辑此页面', + }, + lastUpdated: { + text: '最后更新于', + formatOptions: { + dateStyle: 'short', + timeStyle: 'medium', + }, + }, + docFooter: { + prev: '上一页', + next: '下一页', + }, + outline: { + label: '页面导航', + }, + }, +}) diff --git a/docs/package.json b/docs/package.json new file mode 100644 index 0000000..3dbc1ca --- /dev/null +++ b/docs/package.json @@ -0,0 +1,3 @@ +{ + "type": "module" +} diff --git a/docs/pages/configs.md b/docs/pages/configs.md new file mode 100644 index 0000000..9d08ece --- /dev/null +++ b/docs/pages/configs.md @@ -0,0 +1,207 @@ +# 配置 + +## antdTheme 主题配置 + +- 类型：`LessVars` + +```ts +export interface LessVars { + // 全局变量(直接定义的变量优先级高于变量文件) + vars?: Record + // 全局变量文件 + file?: string +} +``` + +设置`antd`主题变量，可通过`file`属性直接设置配置文件路径，配置文件中需要默认导出一个配置对象。也可通过`vars`直接设置变量。 + +```ts +antdTheme: { + file: './src/theme/index.ts', + vars: { + colorPrimary: 'blue', + }, +} +``` + +## lessVars 变量注入 + +- 类型：`LessVars` + +```ts +export interface LessVars { + // 全局变量(直接定义的变量优先级高于变量文件) + vars?: Record + // 全局变量文件 + file?: string +} +``` + +注入`less`全局变量，可通过`file`属性直接设置配置文件路径，配置文件中需要默认导出一个配置对象。也可通过`vars`直接设置变量。 + +```ts +antdTheme: { + file: './src/theme/globalVars.ts', + vars: { + testColor: 'red', + }, +} +``` + +## assets 资源处理 + +- 类型：`RzpackAssets` + +```ts +export interface RzpackAssets { + // jsx编译处理器 + jsxTools?: JSX_TOOLS + // 是否使用cssScoped(类似Vue的scoped功能) + cssScoped?: boolean + // 是否压缩图片 + imageMini?: boolean +} +``` + +配置资源文件处理方式 + +### jsxTools + +- 类型：`JSX_TOOLS` +- 默认：`JSX_TOOLS.ESBUILD` + +```ts +export enum JSX_TOOLS { + ESBUILD = 'esbuild', + SWC = 'swc', +} +``` + +`jsx`文件编译处理器。 + +### imageMini + +- 类型：`boolean` + +是否压缩图片。 + +> 注意：在打包过程中压缩图片，会拖慢打包速度，建议手动压缩。 + +## buildInfo 编译信息 + +- 类型：`boolean | BuildInfoWebpackPluginOptions` + +是否在控制台打印编译信息。更多配置参考：[@renzp/build-info-webpack-plugin](https://github.com/renzp94/build-info-webpack-plugin) + +## cache 缓存 + +- 类型：`boolean` +- 默认 ：`true` + +是否使用webpack5缓存。 + +## entry 入口 + +- 类型：`string\|string[]\|Record` +- 默认 ：`./src/main.tsx` + +打包入口。 + +## gzip 压缩 + +- 类型：`boolean` + +是否启用gzip。 + +## html + +- 类型：`HtmlWebpackPlugin.Options` +- 默认：`index.html` + +htmlPlugin插件设置。配置参考: [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin)。 + +## output 输出 + +- 类型：`Output` +- 默认 ：`dist` + +输出目录。配置参考：[Output](https://webpack.js.org/concepts/#output) + +## publicPath + +- 类型：`string` +- 默认 ：`public` + +静态资源目录。 + +## server 开发服务 + +- 类型：`WebpackDevServerConfiguration` + +开发服务器配置，当开启可视化配置时此处配置的接口代理无效。配置参考：[dev-server](https://webpack.js.org/configuration/dev-server/) + +## lazyCompilation 懒编译 + +- 类型：`LazyCompilationOptions` + +懒编译。配置参考：[lazycompilation](https://webpack.js.org/configuration/experiments/#experimentslazycompilation) + +## moduleFederation 模块联邦 + +- 类型：`ModuleFederationPluginOptions` + +```ts +export interface ModuleFederationShared { + name: string + requiredVersion: string +} + +export interface ModuleFederationSharedAuto { + deps: string[] + depsPackagePath: string +} + +export interface ModuleFederationPluginOptions { + // 模块名称 + name: string + // 模块导出名称 + filename?: string + // 要共享的依赖 + shared?: ModuleFederationShared[] | ModuleFederationSharedAuto + // 模块暴露的内容 + exposes?: boolean | Record + // 模块引入的内容 + remotes?: Record +} +``` + +模块联邦。 + +## webpackChain 自定义配置 + +- 类型：`RzpackWebpackChain` + +```ts +export type RzpackWebpackChain = (w: WebpackChain) => WebpackChain +``` + +使用webpackChain重写webpack配置。webpackChain用法参考：[webpackChain](https://github.com/neutrinojs/webpack-chain?tab=readme-ov-file) + +## proxyFile + +- 类型：`string` +- 默认：`./proxy.config.json` + +可视化配置的代理，仅在开启可视化配置时才生效。 + +## reactRefresh React热更新 + +- 类型：`string` + +是否开启React代码热更新。 + +## million React性能优化 + +- 类型：`boolean\|MillionOptions` + +是否使用Million.js。配置参考：[Million.js](https://million.dev/zh-CN) diff --git a/docs/pages/features.md b/docs/pages/features.md new file mode 100644 index 0000000..48238f3 --- /dev/null +++ b/docs/pages/features.md @@ -0,0 +1,91 @@ +# 功能 + +## 模块热更新 + +Rzpack使用的Webpack，所以使用的是`webpack-dev-server`的热更新。React的热更新使用的是`@pmmmwh/react-refresh-webpack-plugin`插件实现的。React的热更新默认是不开启的，如果需要开启可指定`reactRefresh: true`开启。 + +## Typescript + +Rzpack默认支持`.ts`和`.tsx`文件。默认使用的打包工具是`esbuild`，也可通过`assets.jsxTools`指定使用`swc`或者`esbuild`。 + +```ts +export enum JSX_TOOLS { + ESBUILD = 'esbuild', + SWC = 'swc', +} +``` + +## Css + +导入`.css`文件将会把内容开发环境插入到`