vite-plugin-esi

1.3.1 verified Mon Apr 27 auth: no javascript

Vite plugin that resolves Edge Side Includes (ESI) directives during the Vite dev server and build process using the nodesi library. Current stable version is 1.3.1 (April 2024). The plugin uses HTML comments as placeholders to inject ESI tags or resolved HTML fragments. Key differentiators: supports both resolving ESI into final HTML or preserving raw ESI tags for server-side processing, customizable nodesi options, and header forwarding. It is designed for Vite projects that need ESI integration, particularly in micro-frontend architectures or edge delivery setups.

Common errors

error Cannot find module 'vite-plugin-esi' ↓

cause Package not installed or incorrect import path.

fix

npm i -D vite-plugin-esi and use import viteEsi from 'vite-plugin-esi'

error TypeError: viteEsi is not a function ↓

cause Using require() in an ESM context or default import mismatch.

fix

Use import viteEsi from 'vite-plugin-esi' (default export) instead of destructured import.

error Plugin ESI: No fragments defined for name 'xyz' ↓

cause HTML comment references a name not defined in the esi option.

fix

Ensure esi option includes a key matching the comment's name attribute.

error Error: nodesi: ESI include failed ↓

cause nodesi cannot fetch the ESI fragment URL (network error, wrong URL, etc.).

fix

Check that the ESI fragment URLs are accessible during build/server.

Warnings

gotcha HTML comments must follow the exact pattern  including the name attribute. Incorrect comment format silently fails. ↓

fix Ensure comments match:

breaking v1.1.0 output ES6 modules which broke CommonJS consumers. v1.2.0 reverted to CommonJS. ↓

fix Upgrade to >=1.2.0 or use ESM-compatible setup.

deprecated Options structure changed in v1.3.0 with 'esiOptions' replacing previous top-level fields. Old config may cause errors. ↓

fix Use esiOptions object for nodesi options: esiOptions: { baseDir: '...' }

gotcha Plugin only processes HTML files (index.html). It does not inject ESI into other file types like .vue or .js. ↓

fix Use only in main HTML entry. For other files, consider alternative ESI implementations.

gotcha The 'esi' option keys are arbitrary names used in HTML comments. The order of fragments is preserved from the array definition. ↓

fix Define fragments in the desired order in the array.

Install

npm install vite-plugin-esi

yarn add vite-plugin-esi

pnpm add vite-plugin-esi

Imports

viteEsi (default)
wrong
```
const viteEsi = require('vite-plugin-esi')
```
correct
```
import viteEsi from 'vite-plugin-esi'
```
The package exports a default function. As of v1.2.0, it is CommonJS, so require() may work but is not recommended. In TypeScript or ESM contexts, use default import.
ViteEsiOptions
wrong
```
import { ViteEsiOptions } from 'vite-plugin-esi'
```
correct
```
import type { ViteEsiOptions } from 'vite-plugin-esi'
```
Options type is exported as a named type. Use 'import type' for compile-time only usage.
Tag
wrong
```
import { Tag } from 'vite-plugin-esi'
```
correct
```
import type { Tag } from 'vite-plugin-esi'
```
The Tag type is also exported. Use type import to avoid runtime inclusion.

Quickstart

Basic setup: install and configure vite-plugin-esi with two ESI fragments for the head section.

// vite.config.ts
import { defineConfig } from 'vite';
import viteEsi from 'vite-plugin-esi';

export default defineConfig({
  plugins: [
    viteEsi({
      esi: {
        headFragments: [
          { src: 'https://example.com/esi/header' },
          { src: 'https://example.com/esi/footer' }
        ]
      },
      resolveESI: true
    })
  ]
});