A reliable JavaScript or TypeScript workflow separates code quality from code style, runs fast checks before commits, and repeats authoritative checks in CI. This guide compares ESLint, Prettier, Biome, Husky, lint-staged, and CI checks, then provides practical setup patterns and a reusable maintenance checklist.
Overview
Linting and formatting solve related but different problems. A formatter such as Prettier applies consistent layout rules: indentation, line wrapping, quotes, and trailing commas. A linter such as ESLint examines code for likely bugs, unsafe patterns, maintainability issues, and project-specific conventions. TypeScript adds another layer of checking through the compiler, but type checking does not replace linting or formatting.
Biome can combine formatting and linting in one tool, which may simplify a repository that does not need the broader ESLint plugin ecosystem. ESLint and Prettier remain a flexible choice when a project depends on framework-specific, accessibility, testing, import-order, or custom lint rules. Neither approach is universally best; the right choice depends on language support, plugin requirements, repository size, and how much configuration the team wants to maintain.
| Tool or check | Primary job | Good fit |
|---|---|---|
| ESLint | Static analysis and project rules | Projects that need a broad plugin ecosystem or custom rules |
| Prettier | Opinionated code formatting | Teams that want formatting handled independently from lint rules |
| Biome | Integrated formatting and linting | Repositories that prefer one fast, consolidated tool |
| Husky | Git hook management | Running repository commands at commit or other Git lifecycle points |
| lint-staged | Runs commands only on staged files | Keeping pre-commit checks quick in larger repositories |
| CI checks | Authoritative validation on a clean environment | Protecting the shared branch from local configuration differences |
A useful default is to let the formatter own stylistic decisions, let ESLint or Biome own code-quality decisions, use a pre-commit hook for fast staged-file checks, and use CI for complete validation. Keep the responsibilities explicit so two tools do not repeatedly rewrite the same lines.
Checklist by scenario
For a new JavaScript or TypeScript repository
- Record the supported runtime, package manager, module format, and source directories.
- Choose either ESLint plus Prettier or Biome as the initial formatting and linting strategy.
- Add an ignore file or configuration for generated output, dependencies, coverage files, build directories, and editor metadata.
- Define explicit scripts such as
lint,format,format:check,typecheck, andtest. - Run the tools against a small, representative part of the codebase before applying them everywhere.
- Add a pre-commit hook only after the commands work directly from a clean terminal.
- Duplicate the important checks in CI rather than treating the local hook as a security boundary.
For ESLint and Prettier
Use the current ESLint flat-config format for a new setup unless the repository is intentionally staying on a legacy configuration. A minimal flat configuration can look like this, with plugin and parser entries adjusted for the project:
import js from "@eslint/js";
export default [
{
ignores: ["dist/**", "coverage/**"],
},
js.configs.recommended,
{
files: ["**/*.{js,mjs,cjs,ts,tsx}"],
rules: {
// Add project rules here.
},
},
];
TypeScript projects generally add the TypeScript ESLint parser and plugin configuration. Check that the versions of ESLint, the TypeScript integration, framework plugins, and any shared configurations support the configuration format you are using. A configuration that loads successfully is not necessarily a configuration that analyzes every intended file, so verify the file globs and ignored paths.
Keep Prettier configuration small and committed. For example:
{
"semi": true,
"singleQuote": true,
"trailingComma": "all"
}
Use a Prettier integration for your editor if desired, but make the package script authoritative. A common script pattern is prettier . --write for local formatting and prettier . --check for CI. Do not make ESLint stylistic rules fight with Prettier; disable overlapping rules through the supported integration for your chosen versions.
For Biome
Biome is a reasonable alternative when a project wants one configuration surface for formatting and linting. Start with the configuration generated by the installed tool, then narrow its file scope and rules. Typical scripts separate automatic changes from verification:
"format": "biome format --write .",
"format:check": "biome format .",
"lint": "biome lint .",
"check": "biome check ."
Confirm the languages, syntax features, framework patterns, and editor integrations your repository needs before migrating. If the project relies on ESLint plugins with no equivalent in Biome, keep ESLint for those checks or adopt a staged migration rather than removing a required rule.
For pre-commit checks
Husky manages the Git hook entry point; lint-staged decides which staged files receive commands. A representative lint-staged configuration is:
export default {
"*.{js,mjs,cjs,ts,tsx}": ["prettier --write", "eslint --fix"],
"*.{json,md,yml,yaml}": ["prettier --write"]
};
The exact configuration format depends on how your package manager and lint-staged version load configuration. The important sequence is consistent: format staged files, run safe automatic lint fixes, then allow the hook to fail if unresolved errors remain. Add a prepare package script for the repository's Husky setup and commit the hook files so every contributor receives the same workflow. After installation, test the hook in a fresh clone or clean environment; a hook that works only on its author's machine is not a dependable check.
For CI
CI should install dependencies from the lockfile and run non-mutating checks. Prefer commands such as format:check, lint, typecheck, and tests. If CI runs an auto-fix command, it should do so in a deliberate formatting job rather than silently changing the branch under review. Keep local and CI commands aligned, but do not assume a pre-commit hook covers files changed by generated code, merge operations, or automation.
What to double-check
- File coverage: Confirm that source, test, configuration, and script files are included where intended. Check that generated files are excluded for a documented reason.
- Configuration format: ESLint flat config, legacy config files, and shared presets are not interchangeable. Verify the format expected by each installed package.
- Type-aware linting: Decide whether linting needs TypeScript project information. It can catch additional issues but may require more configuration and execution time.
- Rule ownership: Assign formatting to Prettier or Biome, not several competing rule sets. Review any rule that changes whitespace, quotes, line breaks, or import layout.
- Fix safety: Treat automatic fixes as code changes. Run tests and inspect the diff, especially after a rule upgrade or a large migration.
- Editor parity: Ensure editor extensions use the repository's installed versions and configuration rather than a globally installed tool.
- Package-manager behavior: Test scripts with the package manager used by CI and contributors. Shell syntax and executable resolution can differ across environments.
- Generated and vendored code: Exclude files that the team does not own, or establish a separate validation path for them.
For React projects, linting is only one part of the development feedback loop. Pair it with focused testing and accessibility checks; the frontend testing tools comparison and React accessibility audit workflow can help define those adjacent checks.
Common mistakes
- Running every check on every commit: A full type check, test suite, formatter, and linter may make commits unnecessarily slow. Keep the hook focused on fast staged-file checks and leave complete validation to CI.
- Using two formatters: Running Prettier and Biome formatting on the same files creates avoidable churn. Choose one owner per file set.
- Adding rules without an adoption plan: Enabling a strict ruleset across an old repository can produce a huge, distracting diff. Start with warnings, scoped directories, or a baseline and tighten rules incrementally.
- Mixing configuration generations: A legacy ESLint preset may not work as a native flat-config object. Use a documented compatibility approach and test upgrades separately.
- Ignoring lockfiles and runtime versions: A changed parser, plugin, Node runtime, or package-manager version can alter results. Review the lockfile and toolchain together.
- Trusting hooks as the only protection: Hooks can be skipped, unavailable, or bypassed by automation. CI remains the shared enforcement point.
- Formatting an unrelated diff: Large formatting churn makes review and conflict resolution harder. Apply migrations in a dedicated commit when possible.
When to revisit
Review this workflow before a seasonal planning cycle, a major dependency upgrade, a framework migration, or a repository split. Also revisit it when contributors report slow commits, editors disagree with CI, or a pull request contains repeated formatting churn.
Use this maintenance checklist:
- Check the release notes and compatibility guidance for ESLint, Prettier, Biome, TypeScript integrations, Husky, and lint-staged before upgrading them together.
- Run the formatter in check mode and compare lint results before and after the change.
- Test a staged-file commit, an unstaged-file change, a merge, and a clean clone.
- Confirm that CI uses the lockfile, the intended runtime, and the same configuration files as local development.
- Inspect the first upgrade diff for rule changes, renamed options, newly analyzed files, and generated-file noise.
- Document the selected tool, ownership of each check, and the commands a new contributor should run.
When the workflow changes, update the scripts, hook, CI job, editor guidance, and contributor documentation in the same change. A small, explicit toolchain is easier to debug than a collection of overlapping checks. For broader frontend workflow planning, also see the bundle-size analysis guide and the React DevTools guide.
