Vite Plugin Generate HTML

This plugin allows you to define separate output files for JavaScript and CSS bundles. It generates <script> and <link> elements from entry files and writes them to specified output files.

This is particularly useful when:

• Your bundles include a hash in the filename that changes with every compilation.
• You have multiple views that need to include these JS and CSS bundles.
• You want to output files in formats like .html, .cshtml (Razor), .php, etc.

Inspired by Webpack's HtmlWebpackPlugin, this plugin provides similar functionality for Vite.

Installation

Install the plugin using npm:

npm install --save-dev vite-plugin-generate-html

Parameters

The plugin accepts the following configuration options:

{
  /**
   * Directory to serve as plain static assets.
   * @default "/dist/"
   */
  publicDir?: string;

  /**
   * The file to write the generated `<script>` HTML to.
   */
  jsEntryFile: string;

  /**
   * The file to write the generated `<link>` HTML to.
   */
  cssEntryFile: string;

  /**
   * Custom attributes for `<script>` and `<link>` elements for specific entry points.
   *
   * - Entry point names must match those defined in your Vite configuration.
   * - If `output` is used, all entry points must be defined unless filtered using the `chunks` parameter.
   * - Default attributes:
   *   - `<script>`: `['type="module"']`
   *   - `<link>`: `['rel="stylesheet"', 'media="all"']`
   *
   * @default []
   * @example
   * output: [
   *   {
   *     main: {
   *       attrs: ['type="module"', 'data-foo="bar"'],
   *       linkAttrs: ['rel="stylesheet"', 'media="all"']
   *     }
   *   }
   * ]
   */
  output?: Array<
    Record<
      string,
      {
        /**
         * Attributes for the generated `<script>` element.
         */
        attrs: string[];

        /**
         * Attributes for the generated `<link>` element.
         */
        linkAttrs: string[];
      }
    >
  >;

  /**
   * Limit the plugin to handle only specific entry points.
   *
   * - By default, all entry points are handled.
   * - Use this to define different output paths for specific entries.
   *
   * @default []
   * @example
   * chunks: ["app", "otherEntry"]
   */
  chunks?: string[];
}

Basic Usage

Step 1: Import CSS in Your Main Entry File

Ensure your main entry file (e.g., main.ts) imports the required CSS:

import "sass/styles.scss";

// Other entry-related code
import { createApp } from "vue";

const app = createApp({});
app.mount("#app");

Step 2: Configure the Plugin in vite.config.ts

Add the plugin to your Vite configuration:

// vite.config.ts
import { resolve as pathResolve } from "path";
import { defineConfig } from "vite";
import VitePluginGenerateHtmlFiles from "vite-plugin-generate-html";

export default defineConfig({
  build: {
    rollupOptions: {
      input: {
        app: pathResolve(__dirname, "src/main.ts"),
        // otherEntry: pathResolve(__dirname, "src/other_entry.ts")
      },
    },
  },
  plugins: [
    VitePluginGenerateHtmlFiles({
      publicDir: "/dist/",
      jsEntryFile: pathResolve(__dirname, "../some/dir/for/javascript.html"),
      cssEntryFile: pathResolve(__dirname, "../some/dir/for/css.html"),
    }),
    // Reuse the plugin for another entry with custom output options:
    // VitePluginGenerateHtmlFiles({
    //   publicDir: "/dist/",
    //   jsEntryFile: pathResolve(__dirname, "../some/dir/for/another-javascript.html"),
    //   cssEntryFile: pathResolve(__dirname, "../some/dir/for/another-css.html"),
    //   output: [
    //     {
    //       otherEntry: {
    //         attrs: ['type="module"', 'data-foo="bar"'],
    //         linkAttrs: ['rel="stylesheet"', 'media="all"'],
    //       },
    //     },
    //   ],
    //   chunks: ["otherEntry"],
    // }),
  ],
});

Step 3: Generated Output

After building your project, the plugin will generate the following files (paths may vary based on your configuration):

javascript.html

<script type="module" src="/dist/app.[hash].js"></script>

css.html

<link href="/dist/main.[hash].css" rel="stylesheet" media="all" />

Note: The plugin will overwrite the contents of the specified output files.

Advanced Usage

Custom Attributes for Entry Points

You can define custom attributes for <script> and <link> elements for specific entry points using the output parameter:

output: [
  {
    main: {
      attrs: ['type="module"', 'data-foo="bar"'],
      linkAttrs: ['rel="stylesheet"', 'media="all"'],
    },
  },
];

Handling Specific Chunks

Use the chunks parameter to limit the plugin to specific entry points:

chunks: ["app", "otherEntry"];

This allows you to reuse the plugin for different entries with separate configurations.

License

This project is licensed under the MIT License.