base-lint CLI

1.2.1 verified Fri May 01 auth: no javascript

base-lint scans repositories for usage of modern Web Platform features and evaluates them against the Baseline dataset to ensure new features ship with fallbacks. Version 1.2.1 is current, with active maintenance and a GitHub Action for CI integration. Key differentiators include diff-mode analysis (default), Markdown and JSON reports, threshold-based enforcement (base-lint enforce), GitHub Checks annotation (base-lint annotate), and PR comment creation (base-lint comment). It relies on @typescript-eslint/typescript-estree for parsing TypeScript/JavaScript, requiring Node.js 18.17+ or 20.x LTS. Alternatives like Lighthouse or caniuse require external dataset integration, whereas base-lint provides an out-of-the-box CLI with built-in Baseline compliance tooling.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/base-lint/dist/index.js from /path/to/project/index.js not supported. ↓

cause Using CommonJS require() on an ESM-only package (v1.2.0+).

fix

Switch to ESM (type: module in package.json) and use import statements, or use dynamic import: const baseLint = await import('base-lint');

error Error: Command 'scan' failed with exit code 1: No staged changes found. Use --mode=repo to scan the entire repository. ↓

cause Running diff mode without any staged files in git.

fix

Stage changes with git add before running scan, or pass --mode=repo for full scan.

error TypeScript Error: Cannot find module 'base-lint' or its corresponding type declarations. ↓

cause Typings not installed; base-lint requires @types/base-lint for TypeScript.

fix

Run npm install --save-dev @types/base-lint (note: typings may be bundled in future versions).

Warnings

breaking ESM-only since v1.2.0: package no longer supports CommonJS require(). ↓

fix Use import instead of require; for CommonJS projects, upgrade to Node.js 20+ and use dynamic import or await import().

deprecated base-lint init --action flag is deprecated; use --github-action instead. ↓

fix Replace '--action' with '--github-action' when scaffolding GitHub Action workflow.

gotcha Diff mode (default) only scans staged changes; uncommitted files are ignored unless --mode=repo is passed. ↓

fix Ensure all changes are staged (git add) before running base-lint scan, or use --mode=repo for full codebase scan.

breakin Removed caching in v1.1.1 due to bundle size bloat; cache support no longer available. ↓

fix Remove any cache configuration from .base-lintrc.json; manual caching via CI artifacts is still possible.

gotcha TypeScript parsing errors may occur with TS versions not supported by @typescript-eslint/typescript-estree. ↓

fix Check @typescript-eslint/typescript-estree peer dependency version and keep TypeScript within supported range (≤5.4.x).

Install

npm install base-lint

yarn add base-lint

pnpm add base-lint

Imports

default
wrong
```
const baseLint = require('base-lint')
```
correct
```
import baseLint from 'base-lint'
```
The package is ESM-only since v1.2.0; CommonJS require() will fail.
scan
wrong
```
const { scan } = require('base-lint')
```
correct
```
import { scan } from 'base-lint'
```
Named export available for programmatic use; ESM import must use named syntax.

enforce

wrong

import enforce from 'base-lint/enforce'

correct

import { enforce } from 'base-lint'

enforce is a top-level named export, not a submodule.

Quickstart

Demonstrates programmatic usage of init, scan, enforce, and clean functions with ESM imports.

// Initialize a new base-lint configuration and run a diff scan
import { scan, init, clean } from 'base-lint';
import { writeFileSync, mkdirSync, existsSync } from 'fs';
import { resolve } from 'path';

async function main() {
  // Step 1: Initialize config (scaffold .base-lintrc.json, .base-lintignore)
  await init({ cwd: process.cwd() });

  // Step 2: Scan the current diff (default mode) and get report
  const result = await scan({
    cwd: process.cwd(),
    mode: 'diff', // or 'repo' for full scan
    outputDir: '.base-lint-report',
  });

  console.log('Report generated at:', result.outputPath);

  // Step 3: Enforce thresholds (e.g., max violations: 0)
  const enforceResult = await enforce({
    reportPath: resolve('.base-lint-report/report.json'),
    thresholds: { errors: 0, warnings: 5 },
  });

  if (!enforceResult.passed) {
    console.error('Enforcement failed:', enforceResult.violations);
    process.exit(1);
  }

  // Step 4: Clean up report artifacts (optional)
  await clean({ outputDir: '.base-lint-report' });
}

main().catch(console.error);