SymlinkWebpackPlugin

1.1.0 verified Sat Apr 25 auth: no javascript

A Webpack plugin to create symbolic links for emitted files. Current stable version is 1.1.0 (released in 2022). The plugin runs after Webpack's emit phase (by default) to create symlinks from one built file to another. It supports array configuration for multiple symlinks, a force option to create missing directories, and a hook option to specify the exact compiler hook (e.g., entryOption). Designed for static site deployments where a single-file router (like index.html) must also appear under a different name (e.g., 200.html). Works with Webpack 4 and 5. Maintained but low churn.

Common errors

error Error: Cannot find module 'symlink-webpack-plugin' ↓

cause Missing installation or wrong import path in a monorepo.

fix

Run npm install --save-dev symlink-webpack-plugin or yarn add --dev symlink-webpack-plugin.

error TypeError: SymlinkWebpackPlugin is not a constructor ↓

cause Used import incorrectly (ESM default import) or forgot 'new'.

fix

Use const SymlinkWebpackPlugin = require('symlink-webpack-plugin'); then new SymlinkWebpackPlugin(...).

error SymlinkWebpackPlugin: symlink option should be a string for non-array configuration ↓

cause Passed an object without 'symlink' property, or passed a non-string value.

fix

Ensure each configuration object has 'origin' and 'symlink' as strings. For multiple symlinks, pass an array of objects.

Warnings

breaking v1.0.0 drops support for Webpack 2 and 3. Requires Webpack 4+. ↓

fix Upgrade Webpack to version 4 or later. If stuck on older Webpack, use v0.2.0 (last version supporting Webpack 2/3).

gotcha The default hook is 'afterEmit'. If your Webpack config uses a different emit-like hook (e.g., 'afterProcessAssets'), symlinks may not be created at the expected time. ↓

fix Explicitly set 'hook' option to the desired compiler hook (e.g., 'thisCompilation', 'emit', 'afterProcessAssets').

gotcha When 'force' is false (default), the plugin will silently skip symlinks whose target directory does not exist. No error is thrown. ↓

fix Set 'force: true' to create missing directories, or ensure the directory structure exists before the build.

deprecated The package relies on 'fs-extra' for directory creation. Webpack 5 has native support for 'mkdirRecursive', but this plugin does not use it. ↓

fix No immediate action required; the dependency is stable. Future versions might drop fs-extra.

Install

npm install symlink-webpack-plugin

yarn add symlink-webpack-plugin

pnpm add symlink-webpack-plugin

Imports

SymlinkWebpackPlugin

wrong

import SymlinkWebpackPlugin from 'symlink-webpack-plugin';

correct

const SymlinkWebpackPlugin = require('symlink-webpack-plugin');

Package is CommonJS only; ESM import will fail. Use require.

SymlinkWebpackPlugin

wrong

plugins: [SymlinkWebpackPlugin({ origin: 'index.html', symlink: '200.html' })]

correct

plugins: [new SymlinkWebpackPlugin({ origin: 'index.html', symlink: '200.html' })]

Must use the 'new' keyword. The plugin is a constructor.

SymlinkWebpackPlugin

wrong

const SymlinkWebpackPlugin = require('symlink-webpack-plugin').default;

correct

const SymlinkWebpackPlugin = require('symlink-webpack-plugin');

There is no default export; direct require returns the constructor.

Quickstart

Configures SymlinkWebpackPlugin to create a symlink from 'index.html' to '200.html' after Webpack emits files.

// webpack.config.js
const SymlinkWebpackPlugin = require('symlink-webpack-plugin');
const path = require('path');

module.exports = {
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js',
  },
  plugins: [
    new SymlinkWebpackPlugin({ origin: 'index.html', symlink: '200.html' })
  ]
};