tweaks

docs/.vuepress/config.js

@@ -16,7 +16,8 @@ module.exports = {
           '/guide/transforms',
           '/guide/frameworks',
           '/guide/environment-variables',
-          '/guide/custom-html-template'
+          '/guide/custom-html-template',
+          '/guide/using-plugins'
         ]
       },
       {
@@ -64,12 +65,16 @@ module.exports = {
           {
             text: 'Reason',
             link: '/guide/plugin-reason'
+          },
+          {
+            text: 'PWA',
+            link: '/guide/plugin-pwa'
           }
         ]
       },
       {
-        text: 'Plugin Dev Guide',
-        link: '/plugin-dev'
+        text: 'API',
+        link: '/api'
       }
     ],
     editLinks: true,

docs/api.md

@@ -0,0 +1,113 @@
+---
+sidebar: auto
+---
+
+# API
+
+::: warning
+This page is still work-in-progress
+:::
+
+Creating a Poi instance:
+
+```js
+const poi = new Poi()
+
+console.log(poi.mode)
+```
+
+## `constructor(argv?)`
+
+- `argv`: `string[]` Default to `process.argv`
+
+## `mode`
+
+- Type: `string`
+- Default: `test`
+- Values: `production` `development` `test`
+
+Get the mode that the bundler is running under.
+
+## `cli`
+
+- Type: `CAC`
+
+The CLI instance, created from [CAC](https://github.com/cacjs/cac).
+
+## `config`
+
+- Type: `object`
+
+Poi config.
+
+## `resolveCwd(...args: string[])`
+
+Like `path.resolve`.
+
+## `localResolve(pkg)`
+
+- Type: `(pkg: string) => string | null`
+
+Resolve a package from current working directory.
+
+## `localRequire(pkg)`
+
+- Type: `(pkg: string) => string | null`
+
+Require a package from current working directory.
+
+## `getCacheConfig(dir, keys, files?)`
+
+- Type: `(dir: string, keys: {[k: string]: string}, files: string[])`
+
+Get the config for `cache-loader`. `keys` and the contents of `files` are used to generate cache identifier.
+
+## `createWebpackChain(opts?)`
+
+- Type: `(opts: {[k:string]:any}) => WebpackChain`
+
+Create a webpack-chain instance.
+
+`opts` will be available as the second argument of `chainWebpack` in the config file.
+
+## `createWebpackCompiler(config)`
+
+- Type: `(config: WebpackConfig)`
+
+Create a webpack compiler from raw webpack config.
+
+## `hook('createCLI', handler: Handler)`
+
+```ts
+type Handler = (opts: Opts) => void
+
+interface Opts {
+  /** The default Poi command */
+  command: Command
+  /** CLI args */
+  args: Args
+}
+
+interface Args {
+  has: (arg: string) => boolean
+  get: (arg: string) => any
+}
+```
+
+## `hook('createWebpackChain', handler: Handler)`
+
+```ts
+type Handler = (config: WebpackChain, opts: Opts) => void
+
+interface Opts {
+  type: string
+  mode: 'production' | 'development' | 'test'
+  [k: string]: any
+}
+```
+
+## `run()`
+
+- Type: `() => Promise<void>`
+
+Parse CLI args and run commands.

docs/config.md

@@ -275,3 +275,14 @@ interface Opts {
 // Some plugin might supply custom opts for creating customized webpack config
 // e.g. creating one for client bundle and the other one for server bundle
 ```
+
+## devServer
+
+All options in [webpack-dev-server](https://webpack.js.org/configuration/dev-server/#devserver) are supported, plus some Poi-specific options:
+
+### devServer.hotEntries
+
+- Type: `string[]`
+- Default: `index`
+
+Make specific webpack entries hot-reloadable.

docs/guide/proxying-api-requests.md

@@ -1,21 +1,57 @@
 # Proxying API Requests
 
-If you want to serve your API at the same host and port as your front-end app, you may want to use the `devServer.proxy` option:
+> This option is inspired by [create-react-app](https://facebook.github.io/create-react-app/docs/proxying-api-requests-in-development).
+
+People often serve the front-end app from the same host and port as their backend implementation.
+For example, a production setup might look like this after the app is deployed:
+
+```
+/             - static server returns index.html with client app
+/todos        - static server returns index.html with client app
+/api/todos    - server handles any `/api/*` requests using the backend implementation
+```
+
+Such setup is not required. However, if you do have a setup like this, it is convenient to write requests like `fetch('/api/todos')` without worrying about redirecting them to another host or port during development.
+
+To tell the development server to proxy any unknown requests to your API server in development, use `devServer.proxy` option in your config file, for example:
 
 ```js
 // poi.config.js
 module.exports = {
-  //...
   devServer: {
-    proxy: {
-      '/api': 'http://localhost:3000'
-    }
+    proxy: 'http://localhost:4000'
   }
 }
 ```
 
-The rule above tells the dev server to proxy any requests under `/api` to your API server in development, now you can simply call `window.fetch('/api/users')` which in turns calls `http://localhost:3000/api/users`.
+This way, when you `fetch('/api/todos')` in development, the development server will recognize that it’s not a static asset, and will proxy your request to `http://localhost:4000/api/todos` as a fallback. The development server will __only__ attempt to send requests without `text/html` in its `Accept` header to the proxy.
+
+Conveniently, this avoids [CORS](http://stackoverflow.com/questions/21854516/understanding-ajax-cors-and-security-considerations) issues and error messages like this in development:
+
+```
+Fetch API cannot load http://localhost:4000/api/todos. No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin 'http://localhost:3000' is therefore not allowed access. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.
+```
+
+Keep in mind that proxy only has effect in development (with `--serve` flag), and it is up to you to ensure that URLs like `/api/todos` point to the right thing in production. You don’t have to use the `/api` prefix. Any unrecognized request without a `text/html` accept header will be redirected to the specified proxy.
+
+The `devServer.proxy` option supports HTTP, HTTPS and WebSocket connections.
 
-## Advanced 
+If you want to have more control over the proxy behavior, you can also use an object with `path: options` pairs. Consult [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware#proxycontext-config) for full options:
 
-[TODO]
+```js
+// poi.config.js
+module.exports = {
+  devServer: {
+    proxy: {
+      '^/api': {
+        target: '<url>',
+        ws: true,
+        changeOrigin: true
+      },
+      '^/foo': {
+        target: '<other_url>'
+      }
+    }
+  }
+}
+```

docs/guide/using-plugins.md

@@ -0,0 +1,88 @@
+# Using Plugins
+
+To use a plugin, you can configure it in the config file:
+
+```js
+// poi.config.js
+module.exports = {
+  plugins: [
+    {
+      resolve: '@poi/plugin-typescript',
+      options: {}
+    }
+  ]
+}
+```
+
+- `resolve`: A plugin package name or the path to it.
+- `options`: Optionally pass options to this plugin.
+
+## Naming Convention
+
+Official plugins are published under `@poi` org on npm, like the `@poi/plugin-typescript` plugin.
+
+Community plugins must follow the `poi-plugin-xxx` or `@org/poi-plugin-xxx` naming convention.
+
+## Plugin Short-hand
+
+For official plugins, i.e. published under `@poi` org on npm:
+
+```js
+module.exports = {
+  plugins: [
+    {
+      // equivalent to`@poi/plugin-typescript`
+      resolve: '@poi/typescript'
+    }
+  ]
+}
+```
+
+For community plugins, i.e. the name starts with `poi-plugin-`:
+
+```js
+module.exports = {
+  plugins: [
+    {
+      // equivalent to`poi-plugin-foo`
+      resolve: 'foo'
+    }
+  ]
+}
+```
+
+This also works with community scoped packages:
+
+```js
+module.exports = {
+  plugins: [
+    {
+      // equivalent to`@org/poi-plugin-foo`
+      resolve: '@org/foo'
+    }
+  ]
+}
+```
+
+## Creating A Plugin
+
+A plugin for Poi is an object which consists of following properties:
+
+- `name`: Plugin name.
+- `apply`: __Optional__. A method that is used to extend core API.
+- `filterPlugins`: __Optional__. A method that is used to remove exiting plugins or add new plugins.
+
+`apply` method accepts two arguments:
+
+- `api`: The [Poi instance](../api.md).
+- `options`: The `options` that is passed to this plugin from config file.
+
+```js
+exports.name = 'my-plugin'
+
+exports.apply = (api, options = {}) => {
+  api.hook('createWebpackChain', config => {
+    config.resolve.alias.add('.mdx')
+  })
+}
+```