chore: 🤖 update docs & unitest

Author: tianyingchun

README.md

@@ -229,6 +229,188 @@ interface TemplateOptions {
 }
 ```
 
+## Webpack Loader Integration with html-webpack-plugin
+
+This 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.
+
+### Basic Setup
+
+First, ensure you have both `html-webpack-plugin` and this package installed:
+
+```bash
+npm install --save-dev html-webpack-plugin @hyperse/html-webpack-plugin-loader
+```
+
+### Webpack Configuration
+
+Add the loader to your webpack configuration file (e.g., `webpack.config.js` or `webpack.config.ts`):
+
+```javascript
+const HtmlWebpackPlugin = require('html-webpack-plugin');
+const path = require('path');
+const loader = require.resolve('@hyperse/html-webpack-plugin-loader/loader');
+
+module.exports = {
+  // ... other webpack config
+  plugins: [
+    new HtmlWebpackPlugin({
+      template: `${loader}!/xxx/src/index.html`,
+      templateParameters: {
+        // Template options (same as TemplateOptions interface)
+        title: 'My Webpack App',
+        favicon: {
+          href: '/favicon.ico',
+          rel: 'icon',
+          attributes: {
+            type: 'image/x-icon',
+          },
+        },
+        headMetaTags: [
+          '<meta name="viewport" content="width=device-width, initial-scale=1.0">',
+          '<meta name="description" content="My webpack application">',
+        ],
+        headStyles: [
+          {
+            id: 'main-css',
+            href: '/styles/main.css',
+            position: 'end',
+          },
+        ],
+        bodyScripts: [
+          {
+            id: 'app-js',
+            src: '/app.js',
+            position: 'end',
+            type: 'module',
+          },
+        ],
+      },
+    }),
+  ],
+};
+```
+
+### Usage with TypeScript
+
+If you're using TypeScript, you can import the types for better type checking:
+
+```typescript
+import type { TemplateOptions } from '@hyperse/html-webpack-plugin-loader';
+import HtmlWebpackPlugin from 'html-webpack-plugin';
+import path from 'path';
+const loader = require.resolve('@hyperse/html-webpack-plugin-loader/loader');
+
+const templateParameters: TemplateOptions = {
+  title: 'My TypeScript Webpack App',
+  // ... other template options
+};
+
+const config = {
+  plugins: [
+    new HtmlWebpackPlugin({
+      template: `$loader}!/xxx/src/index.html`,
+      templateParameters,
+    }),
+  ],
+};
+
+export default config;
+```
+
+### Advanced Usage
+
+#### Dynamic Template Parameters
+
+You can dynamically generate template parameters based on your environment or other conditions:
+
+```javascript
+const getTemplateParameters = (env) => ({
+  title: env.production ? 'Production App' : 'Development App',
+  headMetaTags: [
+    `<meta name="environment" content="${env.production ? 'production' : 'development'}">`,
+  ],
+  // ... other options
+});
+const loader = require.resolve('@hyperse/html-webpack-plugin-loader/loader');
+
+module.exports = (env) => ({
+  // ... other webpack config
+  plugins: [
+    new HtmlWebpackPlugin({
+      template: `${loader}!/xxx/src/index.html`,
+      templateParameters: getTemplateParameters(env),
+    }),
+  ],
+});
+```
+
+#### Multiple HTML Templates
+
+You can use different template parameters for different HTML files:
+
+```javascript
+const loader = require.resolve('@hyperse/html-webpack-plugin-loader/loader');
+
+module.exports = {
+  // ... other webpack config
+  plugins: [
+    new HtmlWebpackPlugin({
+      template: `${loader}!/xxx/src/index.html`,
+      filename: 'index.html',
+      chunks: ['main'],
+      templateParameters: {
+        title: 'Main Application',
+        // ... main app options
+      },
+    }),
+    new HtmlWebpackPlugin({
+      template: `${loader}!/xxx/src/index.html`,
+      filename: 'admin.html',
+      chunks: ['admin'],
+      templateParameters: {
+        title: 'Admin Dashboard',
+        // ... admin-specific options
+      },
+    }),
+  ],
+};
+```
+
+### Loader Options
+
+The loader accepts only one option:
+
+- `force` (boolean, optional): When set to `true`, forces template processing even if no template parameters are provided. Default is `false`.
+
+### Best Practices
+
+1. **Template Organization**:
+
+   - Keep your HTML templates in a dedicated directory (e.g., `src/templates/`)
+   - Use consistent naming conventions for your template files
+
+2. **Environment-specific Configuration**:
+
+   - Use webpack's environment configuration to manage different settings for development and production
+   - Consider using environment variables for sensitive or environment-specific values
+
+3. **Performance Optimization**:
+
+   - Use `position: 'end'` for non-critical scripts and styles
+   - Use `position: 'beginning'` for critical resources
+   - Consider using `order` property to control the loading sequence
+
+4. **Security**:
+
+   - Always use `integrity` checks for external resources when possible
+   - Use `nonce` for inline scripts when implementing CSP
+   - Set appropriate `crossOrigin` attributes for external resources
+
+5. **Maintenance**:
+   - Keep template parameters in a separate configuration file for better maintainability
+   - Use TypeScript for better type safety and IDE support
+   - Document your template parameters for team reference
+
 ## Contributing
 
 Contributions are welcome! Please read our [contributing guidelines](https://github.com/hyperse-io/.github/blob/main/CONTRIBUTING.md) before submitting pull requests.

tests/fixtures/loader/index.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = 'common';

tests/htmlPluginBasic.test.ts

@@ -28,7 +28,11 @@ describe('htmlPluginBasic', () => {
             template: `${loader}!${join(fixtureCwd, '../index.html')}`,
             templateParameters: {
               title: 'default title',
-              favicon: 'default favicon',
+              favicon: {
+                href: 'default favicon',
+                rel: 'icon',
+                attributes: {},
+              },
             },
           }),
         ],

tests/htmlPluginLoader.test.ts

@@ -0,0 +1,47 @@
+import HtmlWebpackPlugin from 'html-webpack-plugin';
+import { existsSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { getDirname, testWebpackPlugin } from './testUtils.js';
+
+const fixtureCwd = getDirname(import.meta.url, './fixtures/loader');
+const fixtureDist = join(fixtureCwd, 'dist');
+
+describe('htmlPluginLoader', () => {
+  beforeEach(() => {
+    if (existsSync(fixtureDist)) {
+      rmSync(fixtureDist, { recursive: true });
+    }
+  });
+
+  it('should return the correct html with webpack loader', async () => {
+    const loader = require.resolve(
+      '@hyperse/html-webpack-plugin-loader/loader'
+    );
+    const result = await testWebpackPlugin(
+      {
+        entry: join(fixtureCwd, './index.js'),
+        output: {
+          path: fixtureDist,
+          filename: 'index_bundle.js',
+        },
+        plugins: [
+          new HtmlWebpackPlugin({
+            inject: 'body',
+            template: `${loader}!${join(fixtureCwd, '../index.html')}`,
+            templateParameters: {
+              title: 'default title',
+              favicon: {
+                href: 'default favicon',
+                rel: 'icon',
+                attributes: {},
+              },
+            },
+          }),
+        ],
+      },
+      fixtureDist
+    );
+    expect(result).toContain('<title>default title</title>');
+    expect(result).toContain('<link rel="icon" href="default favicon">');
+  });
+});