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:

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

---

Parameters

The plugin accepts the following configuration options:

1{
2  /**
3   * Directory to serve as plain static assets.
4   * @default "/dist/"
5   */
6  publicDir?: string;
7
8  /**
9   * The file to write the generated `<script>` HTML to.
10   */
11  jsEntryFile: string;
12
13  /**
14   * The file to write the generated `<link>` HTML to.
15   */
16  cssEntryFile: string;
17
18  /**
19   * Custom attributes for `<script>` and `<link>` elements for specific entry points.
20   *
21   * - Entry point names must match those defined in your Vite configuration.
22   * - If `output` is used, all entry points must be defined unless filtered using the `chunks` parameter.
23   * - Default attributes:
24   *   - `<script>`: `['type="module"']`
25   *   - `<link>`: `['media="all"']`
26   *
27   * @default []
28   * @example
29   * output: [
30   *   {
31   *     main: {
32   *       attrs: ['type="module"', 'data-foo="bar"'],
33   *       linkAttrs: ['media="all"']
34   *     }
35   *   }
36   * ]
37   */
38  output?: Array<
39    Record<
40      string,
41      {
42        /**
43         * Attributes for the generated `<script>` element.
44         */
45        attrs: string[];
46
47        /**
48         * Attributes for the generated `<link>` element.
49         */
50        linkAttrs: string[];
51      }
52    >
53  >;
54
55  /**
56   * Limit the plugin to handle only specific entry points.
57   *
58   * - By default, all entry points are handled.
59   * - Use this to define different output paths for specific entries.
60   *
61   * @default []
62   * @example
63   * chunks: ["app", "otherEntry"]
64   */
65  chunks?: string[];
66}

---

Basic Usage

Step 1: Import CSS in Your Main Entry File

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

1import "sass/styles.scss";
2
3// Other entry-related code
4import { createApp } from "vue";
5
6const app = createApp({});
7app.mount("#app");

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

Add the plugin to your Vite configuration:

1// vite.config.ts
2import { resolve as pathResolve } from "path";
3import { defineConfig } from "vite";
4import VitePluginGenerateHtmlFiles from "vite-plugin-generate-html";
5
6export default defineConfig({
7  build: {
8    rollupOptions: {
9      input: {
10        app: pathResolve(__dirname, "src/main.ts"),
11        // otherEntry: pathResolve(__dirname, "src/other_entry.ts")
12      },
13    },
14  },
15  plugins: [
16    VitePluginGenerateHtmlFiles({
17      publicDir: "/dist/",
18      jsEntryFile: pathResolve(__dirname, "../some/dir/for/javascript.html"),
19      cssEntryFile: pathResolve(__dirname, "../some/dir/for/css.html"),
20    }),
21    // Reuse the plugin for another entry with custom output options:
22    // VitePluginGenerateHtmlFiles({
23    //   publicDir: "/dist/",
24    //   jsEntryFile: pathResolve(__dirname, "../some/dir/for/another-javascript.html"),
25    //   cssEntryFile: pathResolve(__dirname, "../some/dir/for/another-css.html"),
26    //   output: [
27    //     {
28    //       otherEntry: {
29    //         attrs: ['type="module"', 'data-foo="bar"'],
30    //         linkAttrs: ['media="all"'],
31    //       },
32    //     },
33    //   ],
34    //   chunks: ["otherEntry"],
35    // }),
36  ],
37});

Step 3: Generated Output

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

javascript.html

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

css.html

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

1output: [
2  {
3    main: {
4      attrs: ['type="module"', 'data-foo="bar"'],
5      linkAttrs: ['media="all"'],
6    },
7  },
8];

Handling Specific Chunks

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

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

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

---

License

This project is licensed under the MIT License.