pug-lint Migration Configuration for Pug v2

1.0.2 verified Fri May 01 auth: no javascript

Provides a pug-lint configuration preset that helps migrate Pug templates from v1 to v2 by enabling rules that detect deprecated or incompatible patterns. Version 1.0.2 is the latest stable release, updated infrequently. Key differentiator: this is an official preset from the Pug team, ensuring accurate migration checks for breaking changes between Pug v1 and v2, such as attribute syntax and iteration.

Common errors

error Error: Cannot find module 'pug-lint' ↓

cause pug-lint not installed or not in node_modules.

fix

Run 'npm install --save-dev pug-lint' in your project root.

error Configuration file error: Could not load config "migration-v2" from package "pug-lint-config-migration-v2" ↓

cause The extends value in .pug-lintrc.json is incorrect or the package is not installed.

fix

Ensure your .pug-lintrc.json contains: { "extends": "migration-v2" } and run 'npm install --save-dev pug-lint-config-migration-v2'.

error Error: Unknown rule 'some-rule' ↓

cause pug-lint-config-migration-v2 presets include rules that may not exist in older pug-lint versions.

fix

Update pug-lint to version >=2.3.0 as specified in peer dependencies.

Warnings

breaking Pug v2 removes support for inline JavaScript expressions in tag attributes using parentheses (e.g., a(href='/') Home). Use interpolation or string syntax. ↓

fix Replace attribute values with template literals or string expressions, e.g., a(href=`/${user.id}`) Profile.

breaking Pug v2 drops the '&attributes' syntax for splat attributes; you must use object spread in attributes. ↓

fix Use div(attributes) or spread attributes with the rest syntax: div(...attrs).

deprecated The 'mixin' keyword is deprecated in Pug v2 in favor of 'include' or component-based approaches. ↓

fix Replace mixins with includes or composition patterns.

breaking Pug v2 changes the iteration of arrays and objects: 'each value, index in array' now yields index as the second variable, not first. ↓

fix Update iteration order: 'each value, index in array' (value first, then index).

breaking Pug v2 no longer supports the 'style' attribute as an object directly; must be a string or inline style string. ↓

fix Convert style objects to CSS strings: style="color: red; font-size: 14px" or use a helper.

Install

npm install pug-lint-config-migration-v2

yarn add pug-lint-config-migration-v2

pnpm add pug-lint-config-migration-v2

Imports

migration-v2

wrong

Using 'extends': 'pug-lint-config-migration-v2' (full package name)

correct

In .pug-lintrc.json: { "extends": "migration-v2" }

The config name is just 'migration-v2', not the full package name.

pug-lint
wrong
```
npm install pug-lint (missing --save-dev)
```
correct
```
npm install --save-dev pug-lint
```
pug-lint is a dev dependency; install it locally, not globally.
.pug-lintrc.json
wrong
```
Using .pug-lintrc.js or .pug-lintrc.yml without proper formatting
```
correct
```
Create .pug-lintrc.json in project root with the extends field
```
Only JSON format is supported for this config package; other formats may not resolve 'migration-v2' correctly.

Quickstart

Install pug-lint and the migration config, add .pug-lintrc.json with extends, then run the linter on your Pug files.

// Step 1: Install dependencies
npm i --save-dev pug-lint pug-lint-config-migration-v2

// Step 2: Create .pug-lintrc.json in project root
{
  "extends": "migration-v2"
}

// Step 3: Run linter
./node_modules/.bin/pug-lint .
// Expected output: list of warnings/errors for Pug v2 migration