Vue SSR Webpack Plugin

3.0.0 verified Fri May 01 auth: no javascript

A Webpack plugin for Vue 2.x server-side rendering that generates a bundle manifest (JSON) from Webpack code-split server builds, enabling seamless use with Vue's bundleRenderer. Current stable version is 3.0.0. Requires vue-server-renderer >= 2.2.0. Key differentiator: automatically packs multiple output files from on-demand code-splitting into a single JSON bundle, and optionally generates a client manifest for automatic preload/prefetch directives. Release cadence is low (major versions align with Vue 2 SSR API changes).

Common errors

error TypeError: Cannot read property 'tapAsync' of undefined ↓

cause Using VueSSRServerPlugin with Webpack 5+ which removed tapAsync from certain hooks.

fix

Upgrade to vue-ssr-webpack-plugin@4.0.0 or later (if available) or downgrade to Webpack 4.

error Error: [vue-ssr-webpack-plugin] server bundle should have a single entry. Found multiple: [object Object] ↓

cause Server Webpack config has multiple entry points or uses CommonsChunkPlugin.

fix

Ensure server config has exactly one entry point and remove any plugins that produce multiple outputs.

error no such file or directory, open 'vue-ssr-bundle.json' ↓

cause Plugin output file not generated because Webpack build failed or path is incorrect.

fix

Check Webpack output path; ensure build succeeds without errors. For custom filename, provide absolute path or use relative path from output directory.

error Cannot find module 'vue-server-renderer' ↓

cause vue-server-renderer is not installed or not listed in dependencies.

fix

Run npm install vue-server-renderer --save (requires peer version >=2.2.0).

Warnings

breaking Version 3.x drops support for vue-server-renderer < 2.2.0. Plugin will not work with Vue 1.x or Vue 2.0.x SSR. ↓

fix Upgrade vue-server-renderer to >=2.2.0, or stay on vue-ssr-webpack-plugin@1.x for older versions.

gotcha Do not use CommonsChunkPlugin in your server bundle config. The server bundle should have a single entry point; code splitting is handled by the plugin. ↓

fix Remove CommonsChunkPlugin from server Webpack config.

gotcha Client manifest generation requires webpack runtime chunk (via CommonsChunkPlugin) to be separate. Failure to do so will cause missing async chunk injection. ↓

fix Add new webpack.optimize.CommonsChunkPlugin({ name: 'manifest', minChunks: Infinity }) before VueSSRClientPlugin.

deprecated CommonsChunkPlugin is deprecated in Webpack 4+. Use splitChunks and optimization.runtimeChunk instead. ↓

fix For Webpack 4+: use optimization: { runtimeChunk: { name: 'manifest' } } and splitChunks options.

gotcha When using client manifest with html-webpack-plugin, set inject: false to avoid duplicate script tags. ↓

fix Configure HtmlWebpackPlugin with { inject: false }.

Install

npm install vue-ssr-webpack-plugin

yarn add vue-ssr-webpack-plugin

pnpm add vue-ssr-webpack-plugin

Imports

VueSSRServerPlugin
wrong
```
const VueSSRServerPlugin = require('vue-ssr-webpack-plugin')
```
correct
```
import { VueSSRServerPlugin } from 'vue-ssr-webpack-plugin'
```
ESM default export is an object with named exports; CJS require returns the same object. For CJS, use destructuring as shown.

VueSSRClientPlugin

wrong

const { VueSSRClientPlugin } = require('vue-ssr-webpack-plugin')

correct

import { VueSSRClientPlugin } from 'vue-ssr-webpack-plugin'

Available since v2.0. Same import pattern as ServerPlugin.

Plugin instantiation

wrong

VueSSRServerPlugin({ filename: 'my-bundle.json' })

correct

new VueSSRServerPlugin({ filename: 'my-bundle.json' })

Must use 'new' keyword; plugin is a class constructor.

Quickstart

Webpack server config using VueSSRServerPlugin to generate a bundle JSON for Vue SSR.

const { VueSSRServerPlugin } = require('vue-ssr-webpack-plugin');
const path = require('path');

module.exports = {
  target: 'node',
  entry: './src/server-entry.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'server-bundle.js',
    libraryTarget: 'commonjs2'
  },
  plugins: [
    new VueSSRServerPlugin({ filename: 'vue-ssr-bundle.json' })
  ]
};