Formula Lint

0.1.1 verified Fri May 01 auth: no javascript

Formula Lint is a CLI tool that provides a unified linting setup for JavaScript/TypeScript projects, built on ESLint with preconfigured rules for React, TypeScript, and formatting. Version 0.1.1 is the current stable release, targeted at developers who want to add consistent code standards to any project in minutes. It generates flat ESLint configs (eslint.config.js) automatically, integrates with VSCode for on-save fixing, and supports CI/CD via GitHub Actions. The tool requires Node.js >= 18.0.0, ships TypeScript definitions, and is distributed as a global npm package.

Common errors

error Cannot find module '@formula/lint-config' ↓

cause The package @formula/lint-config is not installed; formula-lint expects it as a peer dependency.

fix

Run npm install -g @formula/lint-config or add it to your project dependencies: npm install --save-dev @formula/lint-config

error Error: Requires Babel to transform but it is not configured ↓

cause The generated eslint.config.js may need Babel for certain syntax; formula-lint expects TypeScript or modern JS.

fix

Enable typescript: true in the formula config if using TS, or ensure your project uses valid ES syntax.

error formula: command not found ↓

cause formula-lint is not installed or not in PATH.

fix

Install globally: npm install -g formula-lint.

error ESLint couldn't find the config 'formula' to extend from. ↓

cause The flat config import of @formula/lint-config fails if the package is not installed or module resolution fails.

fix

Install @formula/lint-config: npm install --save-dev @formula/lint-config

Warnings

breaking ESM-only package: formula-lint and @formula/lint-config do not support CommonJS require(). ↓

fix Use import statements and ensure your project uses ESM or has TypeScript configured to handle ES modules.

breaking Flat config required: formula-lint generates eslint.config.js (flat config), not the legacy .eslintrc format. ↓

fix If you need legacy config, do not use formula-lint; or manually convert the flat config to .eslintrc.

deprecated The @formula/lint-config package may be updated separately; breaking changes there can affect your project. ↓

fix Pin version of @formula/lint-config in package.json if stability is needed.

gotcha Global installation recommended: if you install formula-lint locally, the CLI may not be in PATH. ↓

fix Install with npm install -g formula-lint, or use npx formula-lint for local installs.

gotcha Node.js >= 18 required: older Node versions will fail with syntax errors due to ESM features. ↓

fix Update Node.js to version 18 or later.

gotcha VSCode ESLint plugin must be installed separately for editor integration. ↓

fix Install the ESLint extension from the VSCode marketplace.

Install

npm install formula-lint

yarn add formula-lint

pnpm add formula-lint

Imports

default (initialization function)
wrong
```
const formula = require('@formula/lint-config')
```
correct
```
import formula from '@formula/lint-config'
```
ESM-only; CommonJS require will fail. The package is ESM-only since v0.1.x.
init (CLI command)
wrong
```
formula init --overwrite
```
correct
```
formula init [--force] [--verbose]
```
The CLI command does not accept --overwrite; use --force instead.
lint (CLI command)
wrong
```
formula run lint
```
correct
```
formula lint [files...] [--fix] [--format <format>] [--max-warnings <n>] [--verbose]
```
The lint command is not a subcommand of any package script; it's invoked directly via the global CLI.

formula function (config export)

wrong

module.exports = formula({ react: true })

correct

export default formula({ react: true, typescript: true, formatters: true, ignores: [], rules: {} })

eslint.config.js must use ESM export default; CommonJS module.exports is not supported.

Quickstart

Install globally, initialize project config, then run lint with auto-fix and JSON output.

npm install -g formula-lint
cd /path/to/your/project
formula init
# after init, edit eslint.config.js as needed
formula lint --fix
formula lint --format json