{"id":15391737,"url":"https://github.com/jahredhope/html-render-webpack-plugin","last_synced_at":"2025-07-10T05:35:01.395Z","repository":{"id":33470969,"uuid":"152869033","full_name":"jahredhope/html-render-webpack-plugin","owner":"jahredhope","description":"webpack plugin for rendering static HTML in a multi-config webpack build","archived":false,"fork":false,"pushed_at":"2023-02-09T02:30:56.000Z","size":920,"stargazers_count":9,"open_issues_count":16,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-06T22:33:15.297Z","etag":null,"topics":["npm-package"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jahredhope.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-10-13T12:19:52.000Z","updated_at":"2022-08-29T03:31:46.000Z","dependencies_parsed_at":"2024-06-19T01:26:47.731Z","dependency_job_id":"a8d6b7b7-3913-4dfa-bd09-e16eda93e897","html_url":"https://github.com/jahredhope/html-render-webpack-plugin","commit_stats":{"total_commits":44,"total_committers":5,"mean_commits":8.8,"dds":"0.15909090909090906","last_synced_commit":"0e1a3f13f9cfa27569277a1fa7cafe4035e412d0"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/jahredhope/html-render-webpack-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jahredhope%2Fhtml-render-webpack-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jahredhope%2Fhtml-render-webpack-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jahredhope%2Fhtml-render-webpack-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jahredhope%2Fhtml-render-webpack-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jahredhope","download_url":"https://codeload.github.com/jahredhope/html-render-webpack-plugin/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jahredhope%2Fhtml-render-webpack-plugin/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264535998,"owners_count":23624405,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["npm-package"],"created_at":"2024-10-01T15:12:30.987Z","updated_at":"2025-07-10T05:35:01.333Z","avatar_url":"https://github.com/jahredhope.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# html-render-webpack-plugin\n\n[![npm](https://img.shields.io/npm/v/html-render-webpack-plugin.svg)](https://www.npmjs.com/package/html-render-webpack-plugin)\n\nPlugin to create HTML files with JavaScript.\n\n- Supports [multiple configurations](https://webpack.js.org/configuration/configuration-types/#exporting-multiple-configurations)\n- Supports [code-splitting](https://webpack.js.org/guides/code-splitting/) and [dynamic imports](https://webpack.js.org/guides/code-splitting/#dynamic-imports)\n\n# Setup\n\n```bash\n$ npm install webpack html-render-webpack-plugin\n# OR\n$ yarn add webpack html-render-webpack-plugin\n```\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  ...,\n  plugins: [new HtmlRenderPlugin().rendererPlugin]\n};\n```\n\n# Multiple configurations\n\nIf you use [multiple webpack configurations](https://webpack.js.org/configuration/configuration-types/#exporting-multiple-configurations) you may want to add information from other builds when rendering.\n\nFor example, you may wish to add a script tag where the name includes a hash. The asset name comes from the output of one build (browser assets) whilst the render is performed in another build (node rendering).\n\n**src/render.js**\n\n```js\nexport default ({ assetsByChunkName }) =\u003e {\n  return `\u003chtml\u003e\n\u003cbody\u003e\n  \u003cscript src=\"${assetsByChunkName.main}\"\u003e\u003c/script\u003e\n\u003c/body\u003e\n\u003c/html\u003e`;\n};\n```\n\n**dist/index.html**\n\n```html\n\u003chtml\u003e\n  \u003cbody\u003e\n    \u003cscript src=\"/main-daf2166db871ad045ea4.js\"\u003e\u003c/script\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\nSee [the full example below](#example-client-assets).\n\n## Multiple configuration setup\n\nAdd `htmlRenderPlugin.statsCollectorPlugin` to the plugins of all configurations you want to get stats for.\n\nAdd `htmlRenderPlugin.rendererPlugin` to the plugin of the configuration you want to use to render html.\n\nHtmlRenderPlugin will then pass the [Webpack Stats](https://webpack.js.org/api/stats/) for those builds into your render function.\n\n**webpack.config.js**\n\n```js\nconst { HtmlRenderPlugin } = require(\"html-render-webpack-plugin\");\n\nconst htmlRenderPlugin = new HtmlRenderPlugin();\nmodule.exports = [\n  {\n    name: \"render\",\n    target: \"node\", // Creates assets that render HTML that runs well in node\n    plugins: [htmlRenderPlugin.rendererPlugin],\n  },\n  {\n    name: \"client\",\n    target: \"web\", // Creates files that run on the browser\n    plugins: [htmlRenderPlugin.statsCollectorPlugin],\n  },\n];\n```\n\nSee [examples](#examples) for more details.\n\n# Options\n\n## Option: renderEntry _string_\n\n**default:** \"main\"\n\nThe [webpack entry](https://webpack.js.org/concepts/entry-points/) to use when rendering. Override when using [object syntax](https://webpack.js.org/concepts/entry-points/#object-syntax).\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  entry: {\n    myRender: \"./src/myRender.js\",\n  },\n  plugins: [\n    new HtmlRenderPlugin({\n      renderEntry: \"myRender\",\n    }).render,\n  ],\n};\n```\n\n## Option: renderDirectory _string_\n\nThe location to create rendered files. Defaults to the rendered assets output.\n\nUseful when deploying HTML files separate to other build assets.\n\n## Option: routes _Array\u003cobject|string\u003e_\n\n**default:** `[\"\"]`\n\nRenders a HTML page for each value in the array.\nA 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.\n\n```js\nconst routes = [\"\", \"contact\", \"about\"];\n```\n\nA route can be an object, containing a `route` parameter.\n\n```js\nconst routes = [\n  {\n    route: \"en-us/contact\",\n    language: \"en-us\",\n  },\n  {\n    route: \"en-us/about\",\n    language: \"en-us\",\n  },\n  {\n    route: \"en-au/contact\",\n    language: \"en-au\",\n  },\n  {\n    route: \"/en-au/about\",\n    language: \"en-au\",\n  },\n];\n```\n\n## Option: mapStatsToParams _Function_\n\n**default:** `({webpackStats, ...route}) =\u003e ({ webpackStats })`\n\nmapStatsToParams should accept webpackStats and [route](#option-routes-arrayobjectstring) information and returns values to be passed into render.\nThe function is called individually for each render.\n\n**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. It is recommended to override the default mapStatsToParams behaviour.\n\n## Option: transformFilePath _Function_\n\n**default:** `(route) =\u003e route.route ? route.route : route`\n\nBy default a file will be created using the `route` value.\nFor example the value `{route: '/about/us'}` would create **about/us/index.html**\n\nIf you want to use a different file path you can provide a `transformFilePath` function.\n\n```js\nnew HtmlRenderPlugin({\n  ...\n  transformFilePath: ({ route, language }) =\u003e `${language}/${route}`\n  routes: [\n    { route: '/about/us', language: 'en-us' },\n    { route: '/about/us', language: 'en-au' }\n  ]\n});\n```\n\nIn this example, the resulting files will be\n\n- **en-us/about/us/index.html**\n\n- **en-au/about/us/index.html**\n\n## Option: renderConcurrency _string (\"serial\"|\"parallel\")_\n\n**default:** `\"serial\"`\n\nBy default each file will be rendered one after the other, creating a simple sequential build log. When renders with significant asynchronous work you may want to have each render run in parallel.\n\n```\nnew HtmlRenderPlugin({\n  renderConcurrency: 'parallel'\n});\n```\n\n## Option: skipAssets _Function_\n\n**default:** `false`\n\nAfter waiting for all builds to complete HtmlRenderPlugin will render all routes. For particularly large projects with a large number of routes this can take some time. For watch builds you may want to skip emitting assets, relying on `createDevRouter` instead.\n\n## Option: transformExpressPath _Function_\n\n**default:** `(route) =\u003e route.route ? route.route : route`\n\nWhen creating a dev router each route will be attached to the router using it's `route` value.\n\nIf you want to use a different express route you can provide a `transformExpressPath` function.\n\n# Dev Server\n\nCreate an [Express Middleware](https://expressjs.com/en/guide/using-middleware.html) to attach to Webpack Dev Server to speed up development builds.\n\nFor particularly large projects with slow renders and a large number of routes rendering every route on every build can slow down development. The dev server allows you to only render the pages as they are needed during development, whilst ensuring the resulting render works like the full production render.\n\nUsing the [Webpack Dev Server Node API](https://github.com/webpack/webpack-dev-server/blob/master/examples/api/simple/server.js#L14) create a dev server and attach the dev HtmlRenderPlugin router to it. When pages are requested they will be rendered just-in-time, using the same method of rendering as production.\n\n```js\nconst htmlRenderPlugin = new HtmlRenderPlugin({\n  routes,\n  skipAssets: true,\n});\n\nconst compiler = webpack(config);\n\nconst webpackDevServer = new WebpackDevServer(compiler, {\n  before: (app) =\u003e {\n    app.use(htmlRenderPlugin.createDevRouter());\n  },\n});\n\nwebpackDevServer.listen(\"8081\");\n```\n\n**Note:** Ensure that you use the same htmlRenderPlugin created for your webpack configuration as you use for your dev server.\n\n# Manual just-in-time rendering\n\nAs an alternative to using the default dev server you can access `renderWhenReady` to apply your own just-in-time rendering.\n\nJust call `renderWhenReady` with any route, and the next time the renderer is ready the render will be performed.\n\n**Note:** Be careful to only use routes that are generated in a production. Not doing this can lead to differences between development and production builds.\n\nExample: Using an Express App to render a dynamic path with ids.\n\n```js\napp.get('/books/:id', (req, res) =\u003e {\n  res.send(await htmlRenderPlugin.renderWhenReady({route: '/books/_id'}))\n})\n```\n\nErrors returned during this render will contain a `webpackStats` attribute when available. This can be useful when rendering your own error pages.\n\n# Examples\n\n## Example: Client assets\n\nAn example of using `mapStatsToParams` to create `\u003cscript\u003e` tags.\n\n**src/render.js**\n\n```js\nexport default ({ mainChunk }) =\u003e {\n  return `\u003chtml\u003e\n  \u003cbody\u003e\n    \u003cscript src=\"${mainChunk}\"\u003e\u003c/script\u003e\n  \u003c/body\u003e\n  \u003c/html\u003e`;\n};\n```\n\n**webpack.config.js**\n\n```js\nconst path = require(\"path\");\n\nconst { htmlRenderPlugin, htmlRenderClientPlugin } = createHtmlRenderPlugin({\n  mapStatsToParams: ({ webpackStats }) =\u003e ({\n    mainChunk: webpackStats.toJson().assetsByChunkName.main,\n  }),\n});\n\nmodule.exports = [\n  {\n    name: \"client\",\n    target: \"web\",\n    output: {\n      filename: \"client-[name]-[contenthash].js\",\n    },\n    entry: path.resolve(\"src\", \"client.js\"),\n    plugins: [htmlRenderPlugin.statsCollectorPlugin],\n  },\n  {\n    name: \"render\",\n    target: \"node\",\n    output: {\n      libraryExport: \"default\",\n      libraryTarget: \"umd2\",\n      filename: \"render-[name]-[contenthash].js\",\n    },\n    entry: path.resolve(\"src\", \"render.js\"),\n    plugins: [htmlRenderPlugin.rendererPlugin],\n  },\n];\n```\n\n# Migration Guides\n\nMigration from v1 to v2? Checkout the [Migration Guide](./MIGRATION_GUIDE_v1_to_v2.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjahredhope%2Fhtml-render-webpack-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjahredhope%2Fhtml-render-webpack-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjahredhope%2Fhtml-render-webpack-plugin/lists"}