Vite Plugin PostHTML

0.0.3 verified Mon Apr 27 auth: no javascript

Vite plugin to run PostHTML transformations on served/built HTML files (index.html). Current version is 0.0.3. It supports mixing synchronous and asynchronous PostHTML plugins, runs in asynchronous mode, and allows overriding the PostHTML function. Compared to other PostHTML integrations, this plugin is specifically designed for Vite's plugin system and processes the HTML entry point.

Common errors

error TypeError: posthtmlPlugin is not a function ↓

cause Default import instead of named import

fix

Use import { posthtmlPlugin } from 'vite-plugin-posthtml'

error Error: Cannot find module 'posthtml' ↓

cause Missing peer dependency posthtml

fix

Install the peer dependency: npm install posthtml

Warnings

gotcha Plugin runs only on the main HTML entry (index.html), not on other HTML files ↓

fix Use additional handling if you need to process multiple HTML files.

gotcha The sync option in options is always overridden to false (async mode) ↓

fix Do not rely on sync mode; plugins must work asynchronously.

deprecated Version 0.0.3 may have limited support for newer Vite versions ↓

fix Check compatibility with your Vite version (likely 2.x or 3.x).

Install

npm install vite-plugin-posthtml

yarn add vite-plugin-posthtml

pnpm add vite-plugin-posthtml

Imports

posthtmlPlugin

wrong

import posthtmlPlugin from 'vite-plugin-posthtml'

correct

import { posthtmlPlugin } from 'vite-plugin-posthtml'

ESM-only; named export, not default.

posthtmlPlugin (CommonJS)

wrong

const posthtmlPlugin = require('vite-plugin-posthtml')

correct

const { posthtmlPlugin } = require('vite-plugin-posthtml')

CommonJS require with destructuring.

(none)

wrong

import { PostHTMLPluginConfig } from 'vite-plugin-posthtml'

correct

import type { PostHTMLPluginConfig } from 'vite-plugin-posthtml'

TypeScript type import; config interface not exported as value.

Quickstart

Sets up Vite with posthtmlPlugin including a PostHTML plugin, demonstrating configuration and import.

// vite.config.js
import { defineConfig } from 'vite';
import { posthtmlPlugin } from 'vite-plugin-posthtml';
// Optionally import PostHTML plugins
import include from 'posthtml-include';

export default defineConfig({
  plugins: [
    posthtmlPlugin({
      plugins: [include({ root: './src' })],
      options: { /* parser options, sync: false forced */ },
    }),
  ],
});