CnameWebpackPlugin

3.0.0 verified Sat Apr 25 auth: no javascript

Webpack plugin to generate a CNAME file (used by GitHub Pages, Netlify, etc.) for custom domains during build. v3.0.0 is stable, low maintenance cadence. Key differentiator: minimal, zero-config approach for adding a CNAME file to webpack output. Supports webpack 4 and 5. No dependencies beyond webpack peer.

Common errors

error TypeError: CnameWebpackPlugin is not a constructor ↓

cause Using ES6 import incorrectly on a CJS module.

fix

Use require('cname-webpack-plugin') instead of import.

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

cause Missing package installation or incorrect path.

fix

Run 'npm install cname-webpack-plugin --save-dev' and ensure node_modules exists.

error ValidationError: Invalid options object. Cname Webpack Plugin has been initialized using an options object that does not match the API schema. ↓

cause Options object missing required 'domain' property.

fix

Pass an object with a 'domain' key: new CnameWebpackPlugin({ domain: 'example.com' });

Warnings

breaking Version 1.x used a different API: new CnamePlugin(); v2+ renamed to CnameWebpackPlugin. ↓

fix Rename import/require to CnameWebpackPlugin and update constructor call.

gotcha Plugin does not validate domain format; invalid domain will produce a malformed CNAME file. ↓

fix Ensure domain is a valid hostname (e.g., 'example.com' without protocol or trailing slash).

gotcha Plugin writes only to the main output path; does not work with multi-compiler or multi-output configs. ↓

fix Use one plugin instance per compiler or manually handle with multiple compilations.

deprecated Webpack 4 support will be removed in future major version; upgrade to webpack 5. ↓

fix If using webpack 4, pin to version 2.x. Otherwise upgrade to webpack 5.

Install

npm install cname-webpack-plugin

yarn add cname-webpack-plugin

pnpm add cname-webpack-plugin

Imports

CnameWebpackPlugin

wrong

import CnameWebpackPlugin from 'cname-webpack-plugin';

correct

const CnameWebpackPlugin = require('cname-webpack-plugin');

ESM import available in v3+? Actually this package is CJS-only, do not default import.

CnameWebpackPlugin

wrong

const { CnameWebpackPlugin } = require('cname-webpack-plugin');

correct

import CnameWebpackPlugin from 'cname-webpack-plugin';

For ESM projects, use default import. Common mistake is destructuring require.

CnameWebpackPlugin (type)
```
import type { CnameWebpackPlugin } from 'cname-webpack-plugin';
```
TypeScript users: type import only exists if types are provided. Package does not ship types; use @types/cname-webpack-plugin.

Quickstart

Shows basic usage: import plugin, add to webpack plugins array with domain option.

// webpack.config.js
const CnameWebpackPlugin = require('cname-webpack-plugin');

module.exports = {
  entry: './src/index.js',
  output: {
    filename: 'bundle.js',
    path: __dirname + '/dist',
  },
  plugins: [
    new CnameWebpackPlugin({
      domain: 'example.com',
    }),
  ],
};