diff --git a/README.md b/README.md
index 7e198cc..db7ecbb 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,42 @@
# html-render-webpack-plugin
-webpack plugin for rendering static HTML in a multi-config webpack build
+webpack plugin for rendering static HTML in a multi-config webpack build.
+
+`html-render-webpack-plugin` is applied to a webpack [MultiCompiler](https://webpack.js.org/configuration/configuration-types/#exporting-multiple-configurations) to enable rendering based on all resulting webpack outputs.
+
+The render build's code is used to generate the HTML, often using values from other builds such as asset names.
+
+For example, you may wish to add a script tag where the name includes a hash:
+**src/render.js**
+
+```js
+export default ({ assetsByChunkName }) => {
+ return `
+
+
+
+`;
+};
+```
+
+**dist/index.html**
+
+```html
+
+
+
+
+
+```
+
+See [the full example below](#example-client-assets).
# Setup
**Note:** Requires Node v10.12 or greater.
+Install the plugin.
+
```bash
$ npm install webpack html-render-webpack-plugin
# OR
@@ -18,15 +49,12 @@ Export [multiple webpack configurations](https://webpack.js.org/configuration/co
// webpack.config.js
module.exports = [
{
- name: "client",
- target: "web"
- // Creates files that run on the browser
+ name: "render",
+ target: "node" // Creates assets that render HTML that runs well in node
},
{
- name: "render",
- target: "node"
- // Creates assets that render HTML that runs well in node
- dependencies: ["client"], // Requires client files to be ready before render
+ name: "client",
+ target: "web" // Creates files that run on the browser
}
];
```
@@ -70,46 +98,20 @@ server.listen(8080, "localhost", () => {});
See [examples](#examples) for more details.
-## Why two configurations? It's all just JavaScript
-
-For some builds you may be able to avoid needing two configurations. If that is the case you don't need this tool and can avoid the complexity.
-Here are some reasons I've needed to use two configurations:
-
-##### Complex loaders
-
-Some projects use webpack only to generate the client assets. For the render they then use tools such as babel directly.
-This can become a complex when the project has webpack loaders that affect the behaviour of the code such as [CSS Modules](https://github.com/css-modules/css-modules). This can result in differences between rendered HTML and client code.
-
-##### Async chunks
-
-webpack's `target` field helps webpack decide how to handle async chunks.
-For example:
-
-- A web build may try to create `` tags to load in the new file.
-- A node build may try to `require()` the new file.
-
-Code compiled for one target may not work for in the other environment, especially when encountering async chunks.
-
-## Why not just use existing static generation tools?
-
-There are lots of other [great options for statically rendering your HTML](https://github.com/markdalgleish/static-site-generator-webpack-plugin) but they typically work on a single webpack build.
-
-However when rendering your HTML you may need access to information about all your assets.
-For example, when using content hash based file names you need to render with the node/render assets, but you need to know the names of the static assets generated.
-
# Options
-## routes Array
+## Option: routes _Array_
-**default:** [""]
-To render multiple pages pass a routes array. Each route will create a seperate `.html` file.
-A route can be a string showing the folder or file to render. `index.html` is automatically appended for paths.
+**default:** `[""]`
+
+Renders a HTML page for each value in the array.
+A route can be a string showing the folder or file to render, or an object containing a route parameter. `index.html` is automatically appended for paths.
```js
const routes = ["", "contact", "about"];
```
-A route can be an object, containing a `route` parameter. Additional values will be passed to `mapStatsToParams`.
+A route can be an object, containing a `route` parameter.
```js
const routes = [
@@ -118,21 +120,32 @@ const routes = [
language: "en-us"
},
{
- route: "en-us/about"
+ route: "en-us/about",
language: "en-us"
},
{
- route: "en-au/contact"
+ route: "en-au/contact",
language: "en-au"
},
{
- route: "/en-au/about"
+ route: "/en-au/about",
language: "en-au"
}
];
```
-## transformFilePath
+## Option: mapStatsToParams _Function_
+
+**default:** `({webpackStats, ...route}) => ({})`
+
+mapStatsToParams should accept webpackStats and [route](#option-routes-arrayobjectstring) information and returns values to be passed into render.
+The function is called individually for each render.
+
+**Recommendation:** mapStatsToParams is an opportunity to limit what information is provided to your render function. Keeping the boundary between your build code and application code simple. Avoid passing all webpackStats into your render function, pull out only the information needed.
+
+## Option: transformFilePath _Function_
+
+**default:** `(route) => route.route ? route.route : route`
By default a file will be created using the `route` value.
For example the value `{route: '/about/us'}` would create **about/us/index.html**
@@ -158,7 +171,7 @@ In this example, the resulting files will be
# Examples
-## Basic
+## Example: Basic
**build.js**
@@ -176,6 +189,10 @@ compiler.apply(
renderDirectory: path.join(process.cwd(), "dist")
})
);
+
+compiler.run((error, stats) => {
+ console.log("Build complete");
+});
```
**webpack.config.js**
@@ -191,7 +208,73 @@ module.exports = [
entry: { client: path.resolve("src", "client.js") }
},
{
- dependencies: ["client"],
+ name: "render",
+ target: "node",
+ output: {
+ libraryExport: "default",
+ libraryTarget: "umd2",
+ filename: "render-[name]-[contenthash].js",
+ },
+ entry: { render: path.resolve("src", "render.js") },
+ }),
+]
+```
+
+## Example: Client assets
+
+An example of using `mapStatsToParams` to create `
+
+