docs: jugg

.juggrc.doc.ts

@@ -1,4 +1,13 @@
 import { extendConfig } from '@axew/jugg';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const packagesMds = fs
+  .readdirSync(path.resolve(__dirname, 'packages'))
+  .reduce<any>((result, pkg) => {
+    result[pkg] = [`packages/${pkg}/*.md`];
+    return result;
+  }, {});
 
 export default extendConfig({
   publicPath: process.env.NODE_ENV === 'development' ? '/' : './',
@@ -9,8 +18,7 @@ export default extendConfig({
       {
         source: {
           docs: ['README.md'],
-          jugg: ['packages/jugg/**/*.md'],
-          'jugg-plugin-doc': ['packages/jugg-plugin-doc/*.md'],
+          ...packagesMds,
         },
         title: 'Jugg',
         description: 'A naive front-end scaffold.',

README.md

@@ -2,4 +2,4 @@
 
 Learn to build a front-end scaffold 🛠️ base on Webpack.
 
-Modules here are jugg-cli and jugg plugins.
+学习编写一款基于 Webpack 的前端脚手架 `jugg`，同时在这里维护一些插件。

packages/jugg/CHANGELOG.md

@@ -1,4 +1,4 @@
-## 0.2.1-alpha.2
+## 0.2.1-alpha.2 - 2020-01-10
 
 - feat: 插件可以扩展用户配置
 - refactor: `quiet` of `webpack-dev-server` always true

packages/jugg/README.md

@@ -1,17 +1,41 @@
 # Jugg
 
-What is Jugg？
+A front-end scaffold 🛠️ works with Webpack.
 
-A front-end scaffold 🛠️ work with Webpack.
-
-# basic command
+# basic commands
 
 ```bash
-# start a webpack-dev-server
+# start a webpack-dev-server / 启动 dev 服务
 $ jugg dev
 
-# build with webpack
+# build with webpack / 启动打包命令
 $ jugg build
+
+# inspect webpack config / 检查 webpack 配置
+$ jugg inspect
+
+# help / 查看帮助
+$ jugg -h
+```
+
+## options
+
+### -C, --config
+
+指定特定的配置文件，默认会读取 `.juggrc.ts`、`.juggrc.js` 等。
+
+```bash
+# 加载 .myconfig.ts 配置文件
+$ jugg dev --config=.myconfig.ts
+```
+
+### -M, --mode
+
+指定 `process.env.NODE_ENV`
+
+```bash
+# 查看 production 环境的 webpack 配置
+$ jugg inspect --mode=production
 ```
 
 ## jugg dev
@@ -29,7 +53,9 @@ Options:
 
 ```
 
-> [Since webpack-dev-server v3.2.0](https://github.com/webpack/webpack-dev-server/releases/tag/v3.2.0), automatically add the HMR plugin when hot or hotOnly is enabled. Can set `noDevClients` to disable built-in config to entry.
+> ~~[Since webpack-dev-server v3.2.0](https://github.com/webpack/webpack-dev-server/releases/tag/v3.2.0), automatically add the HMR plugin when hot or hotOnly is enabled. Can set `noDevClients` to disable built-in config to entry.~~
+>
+> 现在可以不用顾及 `noDevClients` 的设置了，未来也会进行移除。
 
 ## jugg build
 
@@ -43,9 +69,22 @@ Options:
   -h, --help  output usage information
 ```
 
-# directory
+## jugg inspect
+
+```bash
+$ jugg inspect -h
+Usage: inspect [options]
+
+inspect webpack config
+
+Options:
+  -P, --path [path]  a path file to write result
+  -h, --help         output usage information
+```
+
+# getting started
 
-Simple directory can be something like this, default entry can be `src/index.{tsx?|jsx?}`. `tsconfig.json` is necessary only when you use TypeScript.
+只要创建满足如下结构的目录，就可以开始使用了，入口文件会是 `src/index`，可以是 JS 或 TS。只有当使用 TypeScript 时才需要创建 `tsconfig.json`。
 
 ```bash
 .
@@ -55,9 +94,11 @@ Simple directory can be something like this, default entry can be `src/index.{ts
 
 ```
 
-# config
+# config file
 
-Create a file named `.juggrc.js`, `.juggrc.ts`, `jugg.config.js`, etc. Or write config object in `package.json`.
+Create a file named `.juggrc.js`, `.juggrc.ts`, `jugg.config.js`, etc. Export default a object.
+
+创建名为 `.juggrc.js`、`.juggrc.ts` 或 `jugg.config.js` 的文件，默认导出一个对象，配置对象的类型描述如下。
 
 ```ts
 interface JuggConfig {
@@ -69,7 +110,13 @@ interface JuggConfig {
    * output path of webpack, default 'dist'
    */
   outputDir?: string;
+  /**
+   * 配置插件
+   */
   plugins?: PluginCfgSchema[];
+  /**
+   * webpack DefinePluin
+   */
   define?: { [k: string]: any };
   /**
    * open chunks config? default true
@@ -79,9 +126,12 @@ interface JuggConfig {
    * sourceMap, default true
    */
   sourceMap?: boolean;
+  /**
+   * webpack 配置扩展
+   */
   webpack?: JuggWebpack;
   /**
-   * ts-loader custom transformers, only work when ts-loader is enabled
+   * ts-loader custom transformers, only works when ts-loader is enabled
    */
   tsCustomTransformers?: {
     before?: PluginCfgSchema[];
@@ -141,14 +191,19 @@ type JuggWebpack = webpack.Configuration | (
   param: {
     config: webpackChain.Config;
     webpack: webpack.Configuration;
+    jugg: Jugg;
   }
 ) => void | webpack.Configuration;
 
 type PluginCfgSchema = string | [string, { [k: string]: any }?];
 ```
 
+一份可行的配置可参考：[jugg/examples/ts-lib](https://github.com/daief/jugg/blob/master/examples/ts-lib/.juggrc.ts)。
+
 # env
 
+支持的环境变量。
+
 - ANALYZE
   - enable webpack-bundle-analyzer
 - ANALYZE_PORT
@@ -162,26 +217,26 @@ type PluginCfgSchema = string | [string, { [k: string]: any }?];
 - NO_WEBPACKBAR
   - when opened, remove webpackbar plugin
 - JUGG_TS_PROJECT
-  - set a value to assign a specific tsconfig.json
+  - set a value to assign a specific tsconfig.json / 指定自定义的 TS 配置文件
 
 # `TS` or `JS`
 
 Both `TS` and `JS` can be used together in a project with `jugg`. There are several situations with handleing TS and JS:
 
-- **Default & Recommended**: create a `tsconfig.json`, then jugg will open ts-loader and use it to compile ts, tsx, js, tsx. `babel` is needless here.
+- **Default & Recommended**: create a `tsconfig.json`, then jugg will load ts-loader and use it to compile `ts`, `tsx`, `js`, `tsx`. `babel` is needless here.
   - ts-loader: ts, tsx, js, jsx
   - babel: needless
-- Set config in `.juggrc.js` with `jugg-plugin-babel`. Babel plugin will rewrite built-in config of ts-loader for js and jsx and handle then with itself.
+- Set config in `.juggrc.js` with `jugg-plugin-babel`. Babel plugin will rewrite built-in config of ts-loader for `js` and `jsx` and handle them with itself.
   - ts-loader: ts, tsx
   - babel: js, jsx
-- Set `compileTs: true` in `jugg-plugin-babel` config will clean all built-in ts-loader options. Babel handles all the file.
+- Set `compileTs: true` in `jugg-plugin-babel` config will clean all built-in ts-loader options. Babel handles all the files.
   - ts-loader: cleaned
   - babel: ts, tsx, js, jsx
 
 # Notice
 
 - `import()` works with `"module": "esnext"` in `tsconfig.json`, [detail](https://github.com/webpack/webpack/issues/5703#issuecomment-357512412).
-- - Use `.browserslistrc` config or `browserslist` key in package.json to share target browsers with Babel, ESLint and Stylelint. See [Browserslist docs](https://github.com/browserslist/browserslist#queries) for available queries and default value.
+- Use `.browserslistrc` config or `browserslist` key in package.json to share target browsers with Babel, ESLint and Stylelint. See [Browserslist docs](https://github.com/browserslist/browserslist#queries) for available queries and default value.
   ```json
   {
     // previous built-in config
@@ -195,3 +250,4 @@ Both `TS` and `JS` can be used together in a project with `jugg`. There are seve
     ]
   }
   ```
+- `jugg` 默认不进行 `polyfill`