Convention Lint

1.0.7 verified Fri May 01 auth: no javascript

Convention Lint is a CLI and VS Code extension that enforces naming conventions for files, folders, and HTML/JSX/Vue/Svelte class and id attributes. Current stable version is 1.0.7. It provides real-time diagnostics in the Problems panel, Quick Fix actions, and support for kebab-case, camelCase, PascalCase, snake_case, and lowercase rules. Key differentiators include atomic CSS detection for utility-first frameworks, per-rule severity settings, and disable comments. It competes with tools like ESLint naming plugins but focuses specifically on file and attribute naming.

Common errors

error Unrecognized token in .convention.json ↓

cause Configuration file has syntax errors or unexpected keys.

fix

Validate JSON with 'jsonlint .convention.json' and ensure only 'convention' top-level key.

error convention-lint: command not found ↓

cause Package not installed globally or not in PATH.

fix

Run 'npm install -g convention-lint' and verify with 'which convention-lint'.

error TypeError: conventionLint.lint is not a function ↓

cause Using default import instead of named import in ESM.

fix

Use 'import { lint } from 'convention-lint'' instead of 'import conventionLint from 'convention-lint''.

error Module not found: Can't resolve 'convention-lint' ↓

cause Package not installed locally or missing in node_modules.

fix

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

Warnings

gotcha Atomic CSS detection may skip classes that are not in the built-in list; custom atomic classes should be added via 'customAtomicClasses' config. ↓

fix Add unknown utility classes to 'customAtomicClasses' in .convention.json.

breaking Version 1.0.0 changed the configuration file format from .conventionrc.json to .convention.json; old config files are ignored. ↓

fix Rename .conventionrc.json to .convention.json.

gotcha CLI commands 'lint' and 'check' do not automatically ignore node_modules; you must specify in 'ignore' config or use --ignore flag. ↓

fix Add 'node_modules' to the 'ignore' array in .convention.json or run with '--ignore node_modules'.

gotcha Disable comments must be exactly as documented; extra spaces or typo will be ignored. ↓

fix Use exactly '' (no extra spaces).

deprecated The '--no-fail' flag in 'lint' is deprecated; use '--severity off' instead. ↓

fix Use 'convention-lint lint --severity off' instead of '--no-fail'.

Install

npm install convention-lint

yarn add convention-lint

pnpm add convention-lint

Imports

lintCLI

wrong

import conventionLint from 'convention-lint'

correct

import { lintCLI } from 'convention-lint'

ESM-only; no default export.

check

wrong

const { check } = require('convention-lint')

correct

import { check } from 'convention-lint'

ESM-only; CommonJS require is not supported.

typeConfig

wrong

import { ConventionConfig } from 'convention-lint'

correct

import type { ConventionConfig } from 'convention-lint'

Type import for config types.

Quickstart

Installs the CLI globally, creates a configuration file, and runs lint on a directory and specific files.

// Install globally
npm install -g convention-lint

// Create .convention.json
const fs = require('fs');
const config = {
  convention: {
    classNamingRule: 'kebab-case',
    idNamingRule: 'camelCase',
    fileNamingRule: 'kebab-case',
    folderNamingRule: 'lowercase',
    extensions: ['.html', '.vue', '.jsx', '.tsx', '.svelte', '.php'],
    ignoreAtomicCSS: true,
    severity: 'warning',
    ignore: ['node_modules', '.git', 'dist'],
    ignorePatterns: ['**/*.test.*']
  }
};
fs.writeFileSync('.convention.json', JSON.stringify(config, null, 2));

// Lint a directory
convention-lint lint ./src

// Check specific files for pre-commit
convention-lint check ./src/index.html ./src/component.vue