webpack-html-universal-plugin

A universal webpack plugin for HTML processing with screen adaptation, CDN resource management, and SDK auto-injection.

✨ Features

- Screen Adaptation: Automatically injects adaptive scripts for different environments (client, h5, h5-landscape, web)
- CDN Management: Flexible CDN resource configuration with dynamic path generation
- SDK Auto-injection: Built-in support for popular SDKs (QQ, WeChat, SpyPage, VSCode)
- Custom Scripts: Inject custom inline or external scripts
- TypeScript Support: Full type definitions included

📦 Installation

``bash
npm install webpack-html-universal-plugin --save-dev


or

yarn add webpack-html-universal-plugin -D

or

pnpm add webpack-html-universal-plugin -D
`

🚀 Quick Start

`javascript
const HtmlWebpackPlugin = require('html-webpack-plugin');
const WebpackHtmlInitPlugin = require('webpack-html-universal-plugin');

module.exports = {
// ... other webpack config
plugins: [
new HtmlWebpackPlugin({
// your html-webpack-plugin config
}),
new WebpackHtmlInitPlugin({
adapter: {
type: 'h5',
options: {
rootValue: 16
}
},
cdn: {
publicPath: 'https://cdn.example.com/',
resources: [
'https://cdn.example.com/bootstrap.min.css',
'https://cdn.example.com/jquery.min.js'
]
},
scripts: {
weixin: true,
custom: [
{
type: 'inline',
content: 'console.log("Custom script injected");'
}
]
}
})
]
};
`

⚙️ Configuration

$3

`typescript
interface WebpackHtmlInitPluginOptions {
adapter: {
type: 'client' | 'h5' | 'h5-landscape' | 'web';
options: {
rootValue?: number;
};
};
cdn?: CdnConfig | false | null;
scripts?: {
qq?: boolean | string;
weixin?: boolean | string;
spyPage?: boolean | SpyPageOptions;
vscode?: boolean | string;
custom?: CustomScriptItemType[];
};
}
`

$3

The adapter feature provides screen adaptation for different environments:

| Type | Description |
|------|-------------|
| client | Desktop web applications |
| h5 | Mobile H5 applications (portrait) |
| h5-landscape | Mobile H5 applications (landscape) |
| web | Generic web applications |

Options:
- rootValue: Base font size for rem calculation (default depends on adapter type)

$3

`typescript
interface CdnConfig {
/**
* CDN public path prefix
* Can be string or function for dynamic generation
*/
publicPath?: PublicPathType;

/**
* Default injection position
* link defaults to head, script defaults to body
*/
inject?: 'head' | 'body';

/**
* Resource list, automatically detects type (link or script)
* Supports strings, objects, or functions for dynamic resources
*/
resources?: (CdnItemType | ScriptItemType | string)[] |
((context: CdnContext) => (CdnItemType | ScriptItemType | string)[]);
}
`

Resource Types:
`typescript
// Simple string
'https://cdn.example.com/script.js'

// Object with full control
{
path: 'https://cdn.example.com/style.css',
publicPath: 'https://custom-cdn.example.com/',
inject: 'head',
position: 'start',
// script-specific options
async: true,
defer: true,
crossorigin: 'anonymous'
}
`

CDN Context:
The context passed to dynamic resource functions:
`typescript
interface CdnContext {
headTags: any[];
bodyTags: any[];
compilation?: any;
compiler?: any;
env?: Record;
}
`

$3

#### Built-in SDKs

| SDK | Description | Default URL |
|-----|-------------|-------------|
| qq | QQ SDK | Auto-detected |
| weixin | WeChat SDK | Auto-detected |
| spyPage | SpyPage monitoring | Configurable options |
| vscode | VSCode integration | Auto-detected |

SpyPage Options:
`typescript
type SpyPageOptions = {
version?: string;
enablePerformance?: boolean;
enableError?: boolean;
enableUserBehavior?: boolean;
};
`

#### Custom Scripts

`typescript
type CustomScriptItemType = string | {
type: 'external' | 'inline';
content?: string; // For inline scripts
src?: string; // For external scripts
inject?: 'head' | 'body';
position?: 'start' | 'end';
async?: boolean;
defer?: boolean;
crossorigin?: 'anonymous' | 'use-credentials';
integrity?: string;
nomodule?: boolean;
};
`

📖 Examples

$3

`javascript
new WebpackHtmlInitPlugin({
adapter: {
type: 'h5',
options: {
rootValue: 16
}
}
})
`

$3

`javascript
new WebpackHtmlInitPlugin({
cdn: {
publicPath: (path) => https://cdn-${process.env.NODE_ENV}.example.com/${path},
resources: (context) => {
const resources = [
'https://cdn.example.com/base.css',
'https://cdn.example.com/base.js'
];

if (process.env.NODE_ENV === 'production') {
resources.push('https://cdn.example.com/analytics.js');
}

return resources;
}
}
})
`

$3

`javascript
new WebpackHtmlInitPlugin({
scripts: {
weixin: true,
spyPage: {
version: '2.0.0',
enablePerformance: true,
enableError: true
},
custom: [
{
type: 'inline',
content: 'window.APP_CONFIG = { env: "production" };',
inject: 'head'
},
{
type: 'external',
src: 'https://analytics.example.com/tracker.js',
async: true
}
]
}
})
`

$3

`javascript
new WebpackHtmlInitPlugin({
adapter: {
type: 'web',
options: {}
},
cdn: false, // Disable CDN features
scripts: null // Disable script injection
})
`

🔧 API Reference

$3

`typescript
declare class WebpackHtmlInitPlugin {
options: WebpackHtmlInitPluginOptions;

constructor(options: WebpackHtmlInitPluginOptions);

apply(compiler: any): void;
}
`

$3

`typescript
export { WebpackHtmlInitPlugin as default };
export type { WebpackHtmlInitPluginOptions };

// Additional internal types (available via import)
type PublicPathType = string | ((val: string) => string);
type CdnResourceType = string | {
path: string;
publicPath?: PublicPathType;
inject?: 'head' | 'body';
position?: 'start' | 'end';
async?: boolean;
defer?: boolean;
crossorigin?: 'anonymous' | 'use-credentials';
integrity?: string;
nomodule?: boolean;
};
type CdnItemType = CdnResourceType;
type ScriptItemType = CdnResourceType;
`

🛠️ Development

$3

`bash
npm run build
`

$3

`bash
npm run dev
`

$3

`bash
npm run clean
``

📄 License

ISC

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🔗 Related Projects

- html-webpack-plugin - Required dependency
- postcss-pxtorem - Similar concept for CSS adaptation

📈 Changelog

$3

- Initial beta release
- Core features: adapter, CDN management, script injection
- Full TypeScript support