Vite Plugin Craft CMS

4.0.0 verified Mon Apr 27 auth: no javascript

Integrates Vite with Craft CMS without requiring a Craft plugin. Current stable version is 4.0.0, compatible with Vite 6 or 7 and Node 18+. The plugin parses Vite's HTML output and generates Twig partials for asset injection. Key differentiators: no Craft plugin needed, supports multiple entry points, auto-generates Twig macros for static assets, and respects Vite's server.origin. Release cadence: major versions track Vite major releases, with minor/patch updates for dependency bumps.

Common errors

error Error: Cannot find module 'vite-plugin-craftcms' ↓

cause Package not installed or not using ESM import.

fix

Run 'npm i -D vite-plugin-craftcms' and use 'import { vitePluginCraftCms } from 'vite-plugin-craftcms''.

error TypeError: vitePluginCraftCms is not a function ↓

cause Default import used instead of named import (package is ESM-only).

fix

Change 'import vitePluginCraftCms from ...' to 'import { vitePluginCraftCms } from ...'.

error [vite] URL import is not available in old Node.js versions ↓

cause Running Node < 18 with v3+ of the plugin.

fix

Upgrade Node to version 18 or higher.

error The service worker navigation preload request was cancelled before 'preloadResponse' resolved. ↓

cause Mismatch between server.origin and expected proxy URL; often due to HTTPS vs HTTP.

fix

Set server.origin in Vite config or ensure dev server uses HTTPS if production does.

Warnings

breaking v3.0.0 drops support for Node < 18 and Vite < 6.0.0. ↓

fix Upgrade Node to >=18 and Vite to >=6.0.0.

breaking v2.0.0 changes output file naming when multiple entry points are used; [name] pattern is required. ↓

fix Update outputFile to include '[name]' for multiple entry points.

gotcha The plugin expects an HTML fragment as entry file; using a full HTML document may cause issues. ↓

fix Use a minimal HTML fragment with relative asset paths in './src'.

gotcha Static asset URLs via the Twig macro only work for files inside the Vite publicDir. ↓

fix Place static assets in the directory specified by publicDir (e.g., './web/dist').

Install

npm install vite-plugin-craftcms

yarn add vite-plugin-craftcms

pnpm add vite-plugin-craftcms

Imports

vitePluginCraftCms

wrong

const vitePluginCraftCms = require('vite-plugin-craftcms')

correct

import { vitePluginCraftCms } from 'vite-plugin-craftcms'

Package is ESM-only since v3; named export not default.

vitePluginCraftCms

wrong

import vitePluginCraftCms from 'vite-plugin-craftcms'

correct

import { vitePluginCraftCms } from 'vite-plugin-craftcms'

Default import is not available; must use named import.

type
```
import type { VitePluginCraftCmsOptions } from 'vite-plugin-craftcms'
```
Type import for options object; only available in TypeScript projects.

Quickstart

Minimal Vite config using vite-plugin-craftcms with entry.html, Twig partial output, and dev server on port 3000.

// vite.config.js
import { defineConfig } from 'vite';
import { vitePluginCraftCms } from 'vite-plugin-craftcms';

export default defineConfig(({ command }) => ({
  base: command === 'serve' ? '' : '/dist/',
  server: {
    port: process.env.VITE_DEV_PORT || 3000,
  },
  build: {
    manifest: true,
    outDir: './web/dist/',
    rollupOptions: {
      input: './src/entry.html',
    },
  },
  plugins: [
    vitePluginCraftCms({
      outputFile: './templates/_partials/vite.twig',
    }),
  ],
}));