{"id":22654,"library":"vite-plugin-esi","title":"vite-plugin-esi","description":"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.","status":"active","version":"1.3.1","language":"javascript","source_language":"en","source_url":"https://github.com/marcusthelin/vite-plugin-esi","tags":["javascript","vite","vite plugin","esi","nodesi","typescript"],"install":[{"cmd":"npm install vite-plugin-esi","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-esi","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-esi","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency used to parse and resolve ESI tags.","package":"nodesi","optional":false}],"imports":[{"note":"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.","wrong":"const viteEsi = require('vite-plugin-esi')","symbol":"viteEsi (default)","correct":"import viteEsi from 'vite-plugin-esi'"},{"note":"Options type is exported as a named type. Use 'import type' for compile-time only usage.","wrong":"import { ViteEsiOptions } from 'vite-plugin-esi'","symbol":"ViteEsiOptions","correct":"import type { ViteEsiOptions } from 'vite-plugin-esi'"},{"note":"The Tag type is also exported. Use type import to avoid runtime inclusion.","wrong":"import { Tag } from 'vite-plugin-esi'","symbol":"Tag","correct":"import type { Tag } from 'vite-plugin-esi'"}],"quickstart":{"code":"// vite.config.ts\nimport { defineConfig } from 'vite';\nimport viteEsi from 'vite-plugin-esi';\n\nexport default defineConfig({\n  plugins: [\n    viteEsi({\n      esi: {\n        headFragments: [\n          { src: 'https://example.com/esi/header' },\n          { src: 'https://example.com/esi/footer' }\n        ]\n      },\n      resolveESI: true\n    })\n  ]\n});","lang":"typescript","description":"Basic setup: install and configure vite-plugin-esi with two ESI fragments for the head section."},"warnings":[{"fix":"Ensure comments match: <!--vite-plugin-esi name=\"yourKey\" -->","message":"HTML comments must follow the exact pattern <!--vite-plugin-esi name=\"...\" --> including the name attribute. Incorrect comment format silently fails.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade to >=1.2.0 or use ESM-compatible setup.","message":"v1.1.0 output ES6 modules which broke CommonJS consumers. v1.2.0 reverted to CommonJS.","severity":"breaking","affected_versions":"1.1.0"},{"fix":"Use esiOptions object for nodesi options: esiOptions: { baseDir: '...' }","message":"Options structure changed in v1.3.0 with 'esiOptions' replacing previous top-level fields. Old config may cause errors.","severity":"deprecated","affected_versions":"<1.3.0"},{"fix":"Use only in main HTML entry. For other files, consider alternative ESI implementations.","message":"Plugin only processes HTML files (index.html). It does not inject ESI into other file types like .vue or .js.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Define fragments in the desired order in the array.","message":"The 'esi' option keys are arbitrary names used in HTML comments. The order of fragments is preserved from the array definition.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"npm i -D vite-plugin-esi and use import viteEsi from 'vite-plugin-esi'","cause":"Package not installed or incorrect import path.","error":"Cannot find module 'vite-plugin-esi'"},{"fix":"Use import viteEsi from 'vite-plugin-esi' (default export) instead of destructured import.","cause":"Using require() in an ESM context or default import mismatch.","error":"TypeError: viteEsi is not a function"},{"fix":"Ensure esi option includes a key matching the comment's name attribute.","cause":"HTML comment references a name not defined in the esi option.","error":"Plugin ESI: No fragments defined for name 'xyz'"},{"fix":"Check that the ESI fragment URLs are accessible during build/server.","cause":"nodesi cannot fetch the ESI fragment URL (network error, wrong URL, etc.).","error":"Error: nodesi: ESI include failed"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}