Registry / web-framework / vite-plugin-esi

vite-plugin-esi

library1.3.1jsnpmunverified

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.

web-framework devops

npm install vite-plugin-esi

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-ESI

vite-plugin-esi

web-frameworkjavascriptv1.3.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

viteEsi (default)

✓ import viteEsi from 'vite-plugin-esi'

✗ const viteEsi = require('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

✓ import type { ViteEsiOptions } from 'vite-plugin-esi'

✗ import { ViteEsiOptions } from 'vite-plugin-esi'

Options type is exported as a named type. Use 'import type' for compile-time only usage.

Tag

✓ import type { Tag } from 'vite-plugin-esi'

✗ import { Tag } from 'vite-plugin-esi'

The Tag type is also exported. Use type import to avoid runtime inclusion.

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

Debug

Known issues

gotchaHTML comments must follow the exact pattern  including the name attribute. Incorrect comment format silently fails.

fix

Ensure comments match: <!--vite-plugin-esi name="yourKey" -->

affects: >=1.0.0

breakingv1.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.

affects: 1.1.0

deprecatedOptions 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: '...' }

affects: <1.3.0

gotchaPlugin 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.

affects: >=1.0.0

gotchaThe '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.

affects: >=1.0.0

Errors

Common errors & fixes

Cannot find module 'vite-plugin-esi'

Package not installed or incorrect import path.

fix

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

TypeError: viteEsi is not a function

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

fix

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

Plugin ESI: No fragments defined for name 'xyz'

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: nodesi: ESI include failed

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

fix

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

Upgrade

Version history

1.3.1latest on npm

Audit

Dependencies

nodesirequiredCore dependency used to parse and resolve ESI tags.

Agent activity

8 hits · last 30 days

node

Bingbot

OpenAI (training)

Resources

githubhttps://github.com/marcusthelin/vite-plugin-esi ↗

packagehttps://www.npmjs.com/package/vite-plugin-esi ↗