Vite Plugin Builder

1.0.0 verified Mon Apr 27 auth: no javascript

A Vite plugin that simplifies dual compilation for SSR (Server-Side Rendering) and CSR (Client-Side Rendering) in a single Vite project. Version 1.0.0 supports Vite ^4||^5||^6. It allows building both server and client entry points simultaneously, streamlining workflows for modern SPAs requiring SSR. Notably, it provides separate output directories for server (dist/) and client (dist/public/) assets, with configurable server build options and external dependencies. Written in TypeScript, it offers type safety and minimal setup compared to manual dual-build configurations.

Common errors

error Error: The plugin 'vite-plugin-builder' doesn't support Vite version 3.x. Please upgrade to Vite 4 or later. ↓

cause Using Vite 3 which is not supported by the plugin.

fix

Upgrade Vite to version >=4: npm install vite@latest

error TypeError: builder is not a function ↓

cause Named import instead of default import.

fix

Change import statement to: import builder from 'vite-plugin-builder'

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

cause Package not installed or import path incorrect.

fix

Run npm install vite-plugin-builder --save-dev or yarn add vite-plugin-builder --dev, and ensure import path is correct.

error Error: Expected options.clientEntry to be an object, got string ↓

cause Passed a string to clientEntry instead of an object.

fix

Wrap value in an object: clientEntry: { main: 'index.html' }

Warnings

gotcha Builder plugin overrides Vite's output directory structure; server output goes to dist/, client to dist/public/. Do not manually set 'outDir' in Vite config as it will conflict with plugin's internal logic. ↓

fix Do not set 'outDir' in your Vite config; allow the plugin to manage output directories automatically.

gotcha clientEntry expects an object mapping logical names to HTML template files. Using a plain string will cause a build error. ↓

fix Use { main: 'index.html' } instead of just 'index.html'.

gotcha The plugin automatically externalizes dependencies when serverConfig.external is set to 'true'. If you need specific externals, provide an array instead. ↓

fix Set external: ['express', 'react'] for fine-grained control, or avoid setting it to keep default behavior.

gotcha serverBuild function receives a Vite config object and must return it; omitting the return statement will break the build. ↓

fix Always return the modified viteConfig object from serverBuild.

breaking Version 1.0.0 drops support for Vite 3; only Vite ^4, ^5, ^6 are supported. ↓

fix Upgrade Vite to version 4 or later.

Install

npm install vite-plugin-builder

yarn add vite-plugin-builder

pnpm add vite-plugin-builder

Imports

builder

wrong

import { builder } from 'vite-plugin-builder'

correct

import builder from 'vite-plugin-builder'

Default export; named import will fail.

BuilderOptions
wrong
```
import { BuilderOptions } from 'vite-plugin-builder'
```
correct
```
import type { BuilderOptions } from 'vite-plugin-builder'
```
TypeScript type exported; import as type to avoid runtime issues. Use 'import type' for type-only imports.

ViteConfig

wrong

import { ViteConfig } from 'vite-plugin-builder'

correct

import type { ViteConfig } from 'vite-plugin-builder'

TypeScript type for server build config override function. Not a class or value.

Quickstart

Configures Vite with the builder plugin: sets server entry, client entry, and custom build defines for SSR/CSR dual compilation.

// vite.config.ts
import { defineConfig } from 'vite';
import path from 'path';
import react from '@vitejs/plugin-react-swc';
import builder from 'vite-plugin-builder';

export default defineConfig({
  base: '/',
  plugins: [
    react(),
    builder({
      serverEntry: 'server/main.js',
      clientEntry: {
        main: 'index.html',
      },
      serverConfig: {
        define: {
          'BUILD.BASE': '"/"',
          'BUILD.BASE_API': '"/api"',
          'BUILD.STATIC_DIR': '"public"',
          'BUILD.SERVER_IP': '"0.0.0.0"',
          'BUILD.SERVER_PORT': '3001',
        },
      },
    }),
  ],
});