@neosianexus/quality

Ultra-strict Biome + TypeScript + Husky + Commitlint configuration for React/Next.js projects

A comprehensive, enterprise-grade configuration package that provides ultra-strict code quality standards for TypeScript/JavaScript projects. Zero-config setup with an interactive CLI.

Features

Two-tier Biome presets - stable (version-safe, survives Biome minor bumps) + opt-in strict (full nursery layer)
Ultra-strict Biome configuration - 100+ linting rules with maximum strictness
TypeScript strict mode - All strict flags enabled including noUncheckedIndexedAccess
Conventional Commits - Commitlint integration with automatic validation
Git hooks - Husky + lint-staged for pre-commit checks
Dead code detection - Knip integration to find unused exports
VS Code configuration - Optimized settings and recommended extensions
AI assistant ready - CLAUDE.md generation for Claude Code integration
Multi-project support - Next.js, React, and Node.js/TypeScript configurations
Package manager agnostic - Works with npm, yarn, pnpm, and bun

Installation

Prerequisites

Node.js >= 18.0.0
Git (for Husky hooks)

Quick Install

# Run directly with npx (recommended)
npx @neosianexus/quality

# Or install as a dev dependency
npm install --save-dev @neosianexus/quality

Peer Dependencies

These are required and will be installed automatically:

npm install --save-dev @biomejs/biome typescript

Quick Start

Interactive Setup (Recommended)

npx @neosianexus/quality

The CLI will guide you through:

Project type detection - Automatically detects Next.js, React, or Node.js
Package manager detection - Detects bun, pnpm, yarn, or npm
Feature selection - Choose which tools to enable:
- Conventional Commits (commitlint)
- Git hooks (Husky + lint-staged)
- VS Code configuration
- Dead code detection (Knip)
- Strict (nursery) preset
- CLAUDE.md for AI assistants

Non-Interactive Setup

# Use all detected defaults
npx @neosianexus/quality init --yes

# Preview changes without writing
npx @neosianexus/quality init --dry-run

CLI Commands

The CLI provides two main commands: init for initial setup and upgrade for updating existing configurations.

Running the CLI

# Method 1: Run directly with npx (no installation required)
npx @neosianexus/quality

# Method 2: Run after installing the package
npx quality

# Method 3: If installed globally
quality

Note: Running quality without any subcommand automatically executes the init command.

`quality init`

Initialize quality configuration in your project. This is the main command for setting up code quality tools.

quality init [options]

Options

Option	Short	Description
`--yes`	`-y`	Skip all prompts and use detected defaults
`--force`	`-f`	Overwrite existing configuration files
`--commitlint`	`-c`	Enable Conventional Commits validation
`--skip-husky`		Skip Husky and lint-staged setup
`--skip-vscode`		Skip VS Code configuration
`--knip`	`-k`	Enable Knip for dead code detection
`--strict`	`-s`	Enable the strict (nursery) preset — requires matching Biome version
`--claude-md`		Generate CLAUDE.md for AI assistants
`--skip-claude-md`		Skip CLAUDE.md generation
`--dry-run`	`-d`	Preview changes without writing files

Interactive Flow

When you run quality init without flags, you'll see an interactive wizard:

┌  @neosianexus/quality v1.0.0
│
◇  Project type?
│  ● Next.js (detected)
│  ○ React
│  ○ Node.js / TypeScript
│
◇  Package manager?
│  ● bun (detected)
│  ○ pnpm
│  ○ yarn
│  ○ npm
│
◇  Enable Conventional Commits (commitlint)?
│  Yes / No
│
◇  Set up git hooks (Husky + lint-staged)?
│  Yes / No
│
◇  Add VS Code configuration?
│  Yes / No
│
◇  Add Knip (dead code detection)?
│  Yes / No
│
◇  Enable strict (nursery) preset? Requires matching @biomejs/biome version.
│  Yes / No
│
◇  Create CLAUDE.md (instructions for Claude Code)?
│  Yes / No
│
◆  Configuring...

Usage Examples

# Interactive setup (recommended for first-time users)
npx @neosianexus/quality

# Quick setup with all defaults (CI/CD friendly)
npx @neosianexus/quality init --yes

# Setup with specific features
npx @neosianexus/quality init --commitlint --knip --claude-md

# Setup without git hooks (useful for monorepos)
npx @neosianexus/quality init --skip-husky

# Preview what would be created
npx @neosianexus/quality init --dry-run

# Force overwrite existing configs
npx @neosianexus/quality init --force

# Minimal setup: just Biome + TypeScript
npx @neosianexus/quality init --yes --skip-husky --skip-vscode

What Happens During Init

Detection Phase
- Reads package.json to detect project type (Next.js, React, or Node.js)
- Checks for lock files to detect package manager
- Verifies if Git is initialized
Configuration Generation
- Creates biome.json extending the stable preset (adds the strict preset too if --strict is passed)
- Creates tsconfig.json with path aliases (@/* → src/*)
- Optionally creates commitlint, Knip, VS Code configs
Dependency Installation
- Installs required peer dependencies (@biomejs/biome, typescript)
- Installs optional dependencies based on selections (husky, lint-staged, commitlint, knip)
Git Hooks Setup (if not skipped)
- Initializes Husky
- Creates pre-commit hook running lint-staged
- Creates commit-msg hook running commitlint (if enabled)
Package.json Updates
- Adds quality scripts (check, lint, format, typecheck)
- Adds lint-staged configuration
- Adds prepare script for Husky

`quality upgrade`

Upgrade existing configuration to the latest version with intelligent merging.

quality upgrade [options]

Options

Option	Short	Description
`--yes`	`-y`	Skip confirmation prompts
`--force`	`-f`	Replace configs entirely instead of merging
`--no-backup`		Don't create backup files before modifying
`--dry-run`	`-d`	Preview changes without writing files

How Smart Merge Works

The upgrade command uses intelligent merging to preserve your customizations:

Your Config          +    New Defaults         =    Merged Result
─────────────────────────────────────────────────────────────────
{                         {                         {
  "rules": {                "rules": {                "rules": {
    "myRule": "off"  ←──    "newRule": "error"        "myRule": "off",    ← preserved
  }                         "myRule": "error"          "newRule": "error"  ← added
}                         }                         }
                                                   }

Your custom rules are preserved - If you disabled a rule, it stays disabled
New rules are added - Latest recommended rules are merged in
Arrays are replaced, not concatenated - Avoids duplicate entries

Usage Examples

# Interactive upgrade with confirmation
npx @neosianexus/quality upgrade

# Automatic upgrade (CI/CD friendly)
npx @neosianexus/quality upgrade --yes

# Preview changes before applying
npx @neosianexus/quality upgrade --dry-run

# Full replacement (discard customizations)
npx @neosianexus/quality upgrade --force

# Upgrade without creating backups
npx @neosianexus/quality upgrade --yes --no-backup

Upgrade Output Example

┌  @neosianexus/quality upgrade
│
◇  Files to update:
│
│  biome.json
│    + linter.rules.security.noSecrets: "error"
│    ~ formatter.lineWidth: 80 → 100
│
│  tsconfig.json
│    + compilerOptions.noUncheckedSideEffectImports: true
│
◇  Continue? (files will be backed up)
│  Yes / No
│
◆  Backup created: biome.backup.2026-02-01T14-30-45.json
◆  Configuration updated!

CLI Architecture

The CLI is built with the citty framework and follows this structure:

quality [command] [options]
    │
    ├── (no command) → runs "init" by default
    │
    ├── init
    │   ├── Interactive prompts (via @clack/prompts)
    │   ├── Project detection
    │   ├── Config generation
    │   ├── Dependency installation
    │   └── Git hooks setup
    │
    └── upgrade
        ├── Config analysis
        ├── Smart merge (via deepmerge)
        ├── Backup creation
        └── File updates

What Gets Created

Configuration Files

File	Description
`biome.json`	Ultra-strict linting and formatting rules
`tsconfig.json`	TypeScript configuration with path aliases
`commitlint.config.mjs`	Conventional Commits validation (optional)
`.vscode/settings.json`	VS Code editor settings (optional)
`.vscode/extensions.json`	Recommended extensions (optional)
`knip.json`	Dead code detection config (optional)
`.husky/pre-commit`	Git pre-commit hook
`.husky/commit-msg`	Git commit message hook (optional)
`CLAUDE.md`	AI assistant instructions (optional)
`src/types/css.d.ts`	CSS module type declarations (React/Next.js)

Package.json Updates

The following scripts are added to your package.json:

{
  "scripts": {
    "check": "biome check .",
    "check:fix": "biome check --write --unsafe .",
    "lint": "biome lint .",
    "lint:fix": "biome lint --write --unsafe .",
    "format": "biome format --write .",
    "typecheck": "tsc --noEmit",
    "knip": "knip",
    "prepare": "husky"
  }
}

Project Types

The CLI auto-detects your project type and applies the appropriate configuration:

Next.js

TypeScript: Extends @neosianexus/quality/tsconfig.nextjs
Biome: Allows default exports for pages/routes
Knip: Configured for App Router entry points

React

TypeScript: Extends @neosianexus/quality/tsconfig.react
Biome: Named exports only (no default exports)
Knip: Configured for typical React entry points

Node.js / TypeScript

TypeScript: Extends @neosianexus/quality/tsconfig.base
Biome: Full strictness, no default exports
Knip: Minimal configuration

Package Managers

Auto-detected from lock files in this priority order:

Package Manager	Lock File
bun	`bun.lockb` or `bun.lock`
pnpm	`pnpm-lock.yaml`
yarn	`yarn.lock`
npm	`package-lock.json`

Extending Configurations

You can import and extend the provided configurations directly:

Biome

Two presets are shipped:

Preset	Import	What you get	Version coupling
Stable (default)	`@neosianexus/quality`	All stable Biome groups (`recommended` + ultra-strict overrides)	Forward-compatible with any `@biomejs/biome` `>=2.4.0`
Strict (opt-in)	`@neosianexus/quality/strict`	Adds the full nursery layer (`noFloatingPromises`, `useSortedClasses`, `noShadow`, `useExplicitType`, …)	Tightly coupled — must match the `@biomejs/biome` version the package was built against

Use only the stable preset if you want a setup that survives Biome minor bumps without any action from you:

{
  "extends": ["@neosianexus/quality"]
}

Layer the strict preset on top when you want the bleeding-edge nursery rules (and accept the coupling):

{
  "extends": ["@neosianexus/quality", "@neosianexus/quality/strict"]
}

Why the split? Biome maintainers explicitly state that nursery rules are not covered by semantic versioning and can be promoted, renamed, or removed between minor versions. Shipping them inside the default preset means every consumer inherits the churn. Keeping them behind an opt-in lets you upgrade Biome freely without surprise "unknown rule" errors.

Migrating from an earlier version

Earlier versions shipped nursery rules inside the default preset. If you were relying on them and want to keep the same set of rules enforced, add the strict preset to your extends:

{
-  "extends": ["@neosianexus/quality"]
+  "extends": ["@neosianexus/quality", "@neosianexus/quality/strict"]
}

If you're happy to drop nursery rules (Biome maintainers recommend doing so), no change is needed — your project is now forward-compatible with future Biome minor releases.

TypeScript

{
  "extends": "@neosianexus/quality/tsconfig.base"
}

Available TypeScript configurations:

@neosianexus/quality/tsconfig.base - Base strict configuration
@neosianexus/quality/tsconfig.react - React with JSX support
@neosianexus/quality/tsconfig.nextjs - Next.js optimized

Commitlint

// commitlint.config.mjs
import config from "@neosianexus/quality/commitlint";
export default config;

The .mjs extension forces Node to load the file as ESM regardless of whether your project declares "type": "module" in package.json. A .js file using export default fails in projects without "type": "module".

Knip

{
  "extends": ["@neosianexus/quality/knip"]
}

Configuration Details

Biome Rules

The Biome configuration includes 100+ rules with maximum strictness:

Formatting: Tabs (2-space width), double quotes, semicolons always, 100-char line width
Accessibility: All a11y rules set to error
Complexity: Max cognitive complexity of 15
Security: All security rules enabled
Import organization: Auto-sorted imports enabled

TypeScript Strict Mode

All strict flags are enabled:

{
  "strict": true,
  "noImplicitAny": true,
  "exactOptionalPropertyTypes": true,
  "noUncheckedIndexedAccess": true,
  "noImplicitReturns": true,
  "verbatimModuleSyntax": true
}

Conventional Commits

When enabled, commit messages must follow this format:

type(scope): description

[optional body]

[optional footer]

Allowed types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert

Development

Setup

git clone https://github.com/neosianexus/quality.git
cd quality
bun install

Scripts

Script	Description
`bun run build`	Build the CLI
`bun run validate`	Run lint + typecheck + knip
`bun run check`	Lint and format check
`bun run check:fix`	Auto-fix lint/format issues
`bun run typecheck`	TypeScript type checking
`bun run knip`	Find unused code
`bun run dev`	Run CLI directly from TypeScript

Architecture

quality/
├── bin/
│   ├── cli.ts              # CLI entry point (citty framework)
│   ├── commands/
│   │   ├── init.ts         # Init command implementation
│   │   └── upgrade.ts      # Upgrade command implementation
│   └── utils/
│       ├── constants.ts    # Package metadata and types
│       ├── detect.ts       # Project/PM detection logic
│       ├── exec.ts         # Shell command execution
│       ├── fs.ts           # File system utilities
│       └── generators.ts   # Config file generators
├── vscode/                 # VS Code configuration templates
├── biome.json              # Exported Biome config
├── tsconfig.*.json         # Exported TypeScript configs
├── commitlint.config.js    # Exported Commitlint config
└── knip.config.json        # Exported Knip config

Troubleshooting

Common Issues

Biome not found

npm install --save-dev @biomejs/biome

TypeScript not found

npm install --save-dev typescript

Husky hooks not running

npx husky install

Permission denied on hooks

chmod +x .husky/pre-commit .husky/commit-msg

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to the main branch.

Fork the repository
Create your feature branch (git checkout -b feat/amazing-feature)
Commit your changes (git commit -m 'feat: add amazing feature')
Push to the branch (git push origin feat/amazing-feature)
Open a Pull Request

Support

GitHub Issues - Bug reports and feature requests
GitHub Sponsors - Support the project

License

MIT - Made with care by neosianexus

Name		Name	Last commit message	Last commit date
Latest commit History 43 Commits
.github		.github
bin		bin
vscode		vscode
.editorconfig		.editorconfig
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
biome.dev.json		biome.dev.json
biome.json		biome.json
biome.strict.json		biome.strict.json
bun.lock		bun.lock
commitlint.config.js		commitlint.config.js
knip.config.json		knip.config.json
knip.json		knip.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.base.json		tsconfig.base.json
tsconfig.json		tsconfig.json
tsconfig.nextjs.json		tsconfig.nextjs.json
tsconfig.react.json		tsconfig.react.json
tsup.config.ts		tsup.config.ts

Folders and files

Latest commit

History

Repository files navigation

@neosianexus/quality

Features

Installation

Prerequisites

Quick Install

Peer Dependencies

Quick Start

Interactive Setup (Recommended)

Non-Interactive Setup

CLI Commands

Running the CLI

quality init

Options

Interactive Flow

Usage Examples

What Happens During Init

quality upgrade

Options

How Smart Merge Works

Usage Examples

Upgrade Output Example

CLI Architecture

What Gets Created

Configuration Files

Package.json Updates

Project Types

Next.js

React

Node.js / TypeScript

Package Managers

Extending Configurations

Biome

Migrating from an earlier version

TypeScript

Commitlint

Knip

Configuration Details

Biome Rules

TypeScript Strict Mode

Conventional Commits

Development

Setup

Scripts

Architecture

Troubleshooting

Common Issues

Contributing

Support

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`quality init`

`quality upgrade`

Packages