{"id":29045578,"url":"https://github.com/hyperse-io/html-webpack-plugin-loader","last_synced_at":"2025-11-03T17:42:45.670Z","repository":{"id":298856511,"uuid":"1000720386","full_name":"hyperse-io/html-webpack-plugin-loader","owner":"hyperse-io","description":"A custom template loader that parses HTML templates for the `html-webpack-plugin` package","archived":false,"fork":false,"pushed_at":"2025-06-17T09:08:02.000Z","size":1233,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-25T09:05:38.299Z","etag":null,"topics":["html-loader","html-webpack-plugin","html-webpack-plugin-loader","hyperse","rspack","webpack"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/hyperse-io.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","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,"zenodo":null},"funding":{"github":["hyperse-net"]}},"created_at":"2025-06-12T08:11:14.000Z","updated_at":"2025-06-17T09:07:31.000Z","dependencies_parsed_at":"2025-06-13T09:37:52.317Z","dependency_job_id":null,"html_url":"https://github.com/hyperse-io/html-webpack-plugin-loader","commit_stats":null,"previous_names":["hyperse-io/html-webpack-plugin-loader"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hyperse-io/html-webpack-plugin-loader","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperse-io%2Fhtml-webpack-plugin-loader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperse-io%2Fhtml-webpack-plugin-loader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperse-io%2Fhtml-webpack-plugin-loader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperse-io%2Fhtml-webpack-plugin-loader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyperse-io","download_url":"https://codeload.github.com/hyperse-io/html-webpack-plugin-loader/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperse-io%2Fhtml-webpack-plugin-loader/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262103371,"owners_count":23259440,"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":["html-loader","html-webpack-plugin","html-webpack-plugin-loader","hyperse","rspack","webpack"],"created_at":"2025-06-26T16:37:55.055Z","updated_at":"2025-11-03T17:42:45.663Z","avatar_url":"https://github.com/hyperse-io.png","language":"TypeScript","readme":"# @hyperse/html-webpack-plugin-loader\n\nA powerful HTML template parser and manipulator for webpack applications, providing a fluent API for modifying HTML templates with ease.\n\n\u003cp align=\"left\"\u003e\n  \u003ca aria-label=\"Build\" href=\"https://github.com/hyperse-io/html-webpack-plugin-loader/actions?query=workflow%3ACI\"\u003e\n    \u003cimg alt=\"build\" src=\"https://img.shields.io/github/actions/workflow/status/hyperse-io/html-webpack-plugin-loader/ci-integrity.yml?branch=main\u0026label=ci\u0026logo=github\u0026style=flat-quare\u0026labelColor=000000\" /\u003e\n  \u003c/a\u003e\n  \u003ca aria-label=\"stable version\" href=\"https://www.npmjs.com/package/@hyperse/html-webpack-plugin-loader\"\u003e\n    \u003cimg alt=\"stable version\" src=\"https://img.shields.io/npm/v/%40hyperse%2Fhtml-webpack-plugin-loader?branch=main\u0026label=version\u0026logo=npm\u0026style=flat-quare\u0026labelColor=000000\" /\u003e\n  \u003c/a\u003e\n  \u003ca aria-label=\"Top language\" href=\"https://github.com/hyperse-io/html-webpack-plugin-loader/search?l=typescript\"\u003e\n    \u003cimg alt=\"GitHub top language\" src=\"https://img.shields.io/github/languages/top/hyperse-io/html-webpack-plugin-loader?style=flat-square\u0026labelColor=000\u0026color=blue\"\u003e\n  \u003c/a\u003e\n  \u003ca aria-label=\"Licence\" href=\"https://github.com/hyperse-io/html-webpack-plugin-loader/blob/main/LICENSE\"\u003e\n    \u003cimg alt=\"Licence\" src=\"https://img.shields.io/github/license/hyperse-io/html-webpack-plugin-loader?style=flat-quare\u0026labelColor=000000\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nA TypeScript-based HTML template parser that provides a fluent API for manipulating HTML documents. This package is designed to work seamlessly with webpack applications, allowing you to easily modify HTML templates during the build process.\n\n## Features\n\n- 🔄 Fluent API for HTML manipulation\n- 🎯 Precise control over HTML document structure\n- 📦 Easy integration with webpack\n- 🚀 TypeScript support\n- 🔍 Built-in support for common HTML modifications:\n- 📝 Title tag management\n- 🎨 Favicon handling with customizable attributes\n- 📱 Meta tags management\n- 💅 Style injection (both external and inline)\n- 📜 Script injection (both external and inline)\n- 🔄 Head and body modifications with position control\n\n## Installation\n\n```bash\nnpm install --save @hyperse/html-webpack-plugin-loader\n```\n\n## API Reference\n\n### TemplateParser\n\nThe main class that provides HTML template manipulation capabilities.\n\n```typescript\nimport { TemplateParser } from '@hyperse/html-webpack-plugin-loader';\n\n// Create a new parser instance\nconst parser = new TemplateParser(htmlSource);\n\n// Define template options\nconst templateOptions: TemplateOptions = {\n  // Set page title\n  title: 'My Page Title',\n\n  // Set website favicon with custom attributes\n  favicon: {\n    href: '/favicon.ico',\n    rel: 'icon',\n    attributes: {\n      type: 'image/x-icon',\n      sizes: '32x32',\n    },\n  },\n\n  // Set meta tags in head\n  headMetaTags: ['\u003cmeta name=\"description\" content=\"My page description\"\u003e'],\n\n  // Set external styles in head\n  headStyles: [\n    {\n      id: 'main-css',\n      href: '/styles/main.css',\n      position: 'end',\n      order: 1,\n    },\n  ],\n\n  // Set inline styles in head\n  headInlineStyles: [\n    {\n      id: 'critical-css',\n      content: 'body { margin: 0; }',\n      position: 'beginning',\n      order: 0,\n    },\n  ],\n\n  // Set external scripts in head\n  headScripts: [\n    {\n      id: 'main-js',\n      src: '/main.js',\n      position: 'end',\n      type: 'module',\n      async: true,\n      defer: false,\n      crossOrigin: 'anonymous',\n      integrity: 'sha384-hash',\n      nonce: 'abc123',\n      order: 1,\n    },\n  ],\n\n  // Set inline scripts in head\n  headInlineScripts: [\n    {\n      id: 'inline-script',\n      content: 'console.log(\"Hello\");',\n      position: 'end',\n      order: 2,\n    },\n  ],\n\n  // Set scripts in body\n  bodyScripts: [\n    {\n      id: 'app-js',\n      src: '/app.js',\n      position: 'end',\n      type: 'module',\n      async: true,\n      defer: false,\n      order: 1,\n    },\n  ],\n};\n\n// Use template options to modify HTML\nconst modifiedHtml = parser\n  .upsertTitleTag(templateOptions.title)\n  .upsertFaviconTag(\n    templateOptions.favicon.href,\n    templateOptions.favicon.rel,\n    templateOptions.favicon.attributes\n  )\n  .upsertHeadMetaTags(templateOptions.headMetaTags)\n  .upsertHeadStyles(templateOptions.headStyles)\n  .upsertHeadInlineStyles(templateOptions.headInlineStyles)\n  .upsertHeadScripts(templateOptions.headScripts)\n  .upsertHeadInlineScripts(templateOptions.headInlineScripts)\n  .upsertBodyScripts(templateOptions.bodyScripts)\n  .serialize();\n```\n\n#### Available Methods\n\n- `upsertTitleTag(title: string)`: Updates or inserts the page title\n- `upsertFaviconTag(href: string, rel?: string, attributes?: Record\u003cstring, string\u003e)`: Updates or inserts the favicon link with optional rel and custom attributes\n- `upsertHeadMetaTags(tags: string[])`: Updates or inserts meta tags in the head\n- `upsertHeadStyles(styles: StyleItem[])`: Updates or inserts external style links in the head\n- `upsertHeadInlineStyles(styles: StyleInlineItem[])`: Updates or inserts inline style tags in the head\n- `upsertHeadScripts(scripts: ScriptItem[])`: Updates or inserts external script tags in the head\n- `upsertHeadInlineScripts(scripts: ScriptInlineItem[])`: Updates or inserts inline script tags in the head\n- `upsertBodyScripts(scripts: ScriptItem[])`: Updates or inserts script tags in the body\n- `serialize()`: Converts the modified document back to HTML string\n\n### `parseTemplate` Function\n\nA utility function that provides a convenient way to parse and modify HTML templates in a single step.\n\n```typescript\nimport { parseTemplate } from '@hyperse/html-webpack-plugin-loader';\n\n// Parse and modify HTML template in one go\nconst modifiedHtml = parseTemplate(htmlSource, templateOptions).serialize();\n```\n\nThe `parseTemplate` function is a shorthand for creating a `TemplateParser` instance and applying all template modifications at once. It accepts two parameters:\n\n- `htmlSource: string`: The source HTML template to parse and modify\n- `options: TemplateOptions`: The template modification options (same as described above)\n\nThis function is particularly useful when you want to perform all template modifications in a single operation without manually chaining multiple method calls.\n\n### Type Definitions\n\n```typescript\ntype Position = 'beginning' | 'end';\n\ninterface HtmlItemBase {\n  id: string;\n  position: Position;\n  order?: number;\n}\n\ninterface StyleItem extends HtmlItemBase {\n  href: string;\n}\n\ninterface StyleInlineItem extends HtmlItemBase {\n  content: string;\n}\n\ninterface ScriptItem extends HtmlItemBase {\n  src: string;\n  type?: string;\n  async?: boolean;\n  defer?: boolean;\n  crossOrigin?: string;\n  integrity?: string;\n  nonce?: string;\n}\n\ninterface ScriptInlineItem extends HtmlItemBase {\n  content: string;\n}\n\ninterface FaviconItem {\n  href: string;\n  rel: string;\n  attributes: Record\u003cstring, string\u003e;\n}\n\ninterface TemplateOptions {\n  title?: string;\n  favicon?: FaviconItem;\n  headMetaTags?: string[];\n  headStyles?: StyleItem[];\n  headInlineStyles?: StyleInlineItem[];\n  headScripts?: ScriptItem[];\n  headInlineScripts?: ScriptInlineItem[];\n  bodyScripts?: ScriptItem[];\n}\n```\n\n## Webpack Loader Integration with html-webpack-plugin\n\nThis package provides seamless integration with webpack through a custom loader. The loader works in conjunction with `html-webpack-plugin` to modify HTML templates during the build process.\n\n### Basic Setup\n\nFirst, ensure you have both `html-webpack-plugin` and this package installed:\n\n```bash\nnpm install --save-dev html-webpack-plugin @hyperse/html-webpack-plugin-loader\n```\n\n### Webpack Configuration\n\nAdd the loader to your webpack configuration file (e.g., `webpack.config.js` or `webpack.config.ts`):\n\n```javascript\nconst HtmlWebpackPlugin = require('html-webpack-plugin');\nconst path = require('path');\nconst loader = require.resolve('@hyperse/html-webpack-plugin-loader/loader');\n\nmodule.exports = {\n  // ... other webpack config\n  plugins: [\n    new HtmlWebpackPlugin({\n      template: `${loader}!/xxx/src/index.html`,\n      templateParameters: {\n        // Template options (same as TemplateOptions interface)\n        title: 'My Webpack App',\n        favicon: {\n          href: '/favicon.ico',\n          rel: 'icon',\n          attributes: {\n            type: 'image/x-icon',\n          },\n        },\n        headMetaTags: [\n          '\u003cmeta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\"\u003e',\n          '\u003cmeta name=\"description\" content=\"My webpack application\"\u003e',\n        ],\n        headStyles: [\n          {\n            id: 'main-css',\n            href: '/styles/main.css',\n            position: 'end',\n          },\n        ],\n        bodyScripts: [\n          {\n            id: 'app-js',\n            src: '/app.js',\n            position: 'end',\n            type: 'module',\n          },\n        ],\n      },\n    }),\n  ],\n};\n```\n\n### Usage with TypeScript\n\nIf you're using TypeScript, you can import the types for better type checking:\n\n```typescript\nimport type { TemplateOptions } from '@hyperse/html-webpack-plugin-loader';\nimport HtmlWebpackPlugin from 'html-webpack-plugin';\nimport path from 'path';\nconst loader = require.resolve('@hyperse/html-webpack-plugin-loader/loader');\n\nconst templateParameters: TemplateOptions = {\n  title: 'My TypeScript Webpack App',\n  // ... other template options\n};\n\nconst config = {\n  plugins: [\n    new HtmlWebpackPlugin({\n      template: `$loader}!/xxx/src/index.html`,\n      templateParameters,\n    }),\n  ],\n};\n\nexport default config;\n```\n\n### Advanced Usage\n\n#### Dynamic Template Parameters\n\nYou can dynamically generate template parameters based on your environment or other conditions:\n\n```javascript\nconst getTemplateParameters = (env) =\u003e ({\n  title: env.production ? 'Production App' : 'Development App',\n  headMetaTags: [\n    `\u003cmeta name=\"environment\" content=\"${env.production ? 'production' : 'development'}\"\u003e`,\n  ],\n  // ... other options\n});\nconst loader = require.resolve('@hyperse/html-webpack-plugin-loader/loader');\n\nmodule.exports = (env) =\u003e ({\n  // ... other webpack config\n  plugins: [\n    new HtmlWebpackPlugin({\n      template: `${loader}!/xxx/src/index.html`,\n      templateParameters: getTemplateParameters(env),\n    }),\n  ],\n});\n```\n\n#### Multiple HTML Templates\n\nYou can use different template parameters for different HTML files:\n\n```javascript\nconst loader = require.resolve('@hyperse/html-webpack-plugin-loader/loader');\n\nmodule.exports = {\n  // ... other webpack config\n  plugins: [\n    new HtmlWebpackPlugin({\n      template: `${loader}!/xxx/src/index.html`,\n      filename: 'index.html',\n      chunks: ['main'],\n      templateParameters: {\n        title: 'Main Application',\n        // ... main app options\n      },\n    }),\n    new HtmlWebpackPlugin({\n      template: `${loader}!/xxx/src/index.html`,\n      filename: 'admin.html',\n      chunks: ['admin'],\n      templateParameters: {\n        title: 'Admin Dashboard',\n        // ... admin-specific options\n      },\n    }),\n  ],\n};\n```\n\n### Loader Options\n\nThe loader accepts only one option:\n\n- `force` (boolean, optional): When set to `true`, forces template processing even if no template parameters are provided. Default is `false`.\n\n### Best Practices\n\n1. **Template Organization**:\n   - Keep your HTML templates in a dedicated directory (e.g., `src/templates/`)\n   - Use consistent naming conventions for your template files\n\n2. **Environment-specific Configuration**:\n   - Use webpack's environment configuration to manage different settings for development and production\n   - Consider using environment variables for sensitive or environment-specific values\n\n3. **Performance Optimization**:\n   - Use `position: 'end'` for non-critical scripts and styles\n   - Use `position: 'beginning'` for critical resources\n   - Consider using `order` property to control the loading sequence\n\n4. **Security**:\n   - Always use `integrity` checks for external resources when possible\n   - Use `nonce` for inline scripts when implementing CSP\n   - Set appropriate `crossOrigin` attributes for external resources\n\n5. **Maintenance**:\n   - Keep template parameters in a separate configuration file for better maintainability\n   - Use TypeScript for better type safety and IDE support\n   - Document your template parameters for team reference\n\n## Contributing\n\nContributions are welcome! Please read our [contributing guidelines](https://github.com/hyperse-io/.github/blob/main/CONTRIBUTING.md) before submitting pull requests.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","funding_links":["https://github.com/sponsors/hyperse-net"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperse-io%2Fhtml-webpack-plugin-loader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyperse-io%2Fhtml-webpack-plugin-loader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperse-io%2Fhtml-webpack-plugin-loader/lists"}