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

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

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

Plugin Options

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[];
  };
}

Adapter Configuration

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)

CDN Configuration

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:

// 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:

interface CdnContext {
  headTags: any[];
  bodyTags: any[];
  compilation?: any;
  compiler?: any;
  env?: Record<string, any>;
}

Scripts Configuration

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:

type SpyPageOptions = {
  version?: string;
  enablePerformance?: boolean;
  enableError?: boolean;
  enableUserBehavior?: boolean;
};

Custom Scripts

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

Basic Screen Adaptation

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

CDN with Dynamic Resources

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;
    }
  }
})

Multiple SDK Injection

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
      }
    ]
  }
})

Disabling Features

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

🔧 API Reference

WebpackHtmlInitPlugin Class

declare class WebpackHtmlInitPlugin {
  options: WebpackHtmlInitPluginOptions;
  
  constructor(options: WebpackHtmlInitPluginOptions);
  
  apply(compiler: any): void;
}

Types Exports

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

Build

npm run build

Development Mode

npm run dev

Clean

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

v0.0.0-beta.0

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