Quality Standards

Overview

BetterStarter enforces high code quality through automated tooling and checks that run before every commit.

oxlint

oxlint is a blazing-fast JavaScript/TypeScript linter written in Rust. It replaces ESLint for the majority of linting needs.

Commands

# Lint the codebase
pnpm lint

# Lint and auto-fix issues
pnpm lint:fix

Configuration

oxlint config is in .oxlintrc.json:

{
  "plugins": ["react", "typescript", "oxc"],
  "categories": {
    "correctness": "error",
    "suspicious": "warn"
  },
  "rules": {
    "react/no-array-index-key": "warn"
  }
}

oxfmt

oxfmt is a fast TypeScript/JavaScript formatter built on the OXC toolchain. It replaces Prettier.

Commands

# Check formatting
pnpm format

# Format and write changes
pnpm format:fix

Run Both Together

# Lint + format check
pnpm lint-format

# Fix lint + format issues
pnpm lint-format:fix

TypeScript

Full type safety is enforced. All code must pass TypeScript compilation without casting.

Type Checking

# Check types without building
pnpm tsc --noEmit

Best Practices

• Never use as or type assertions unless absolutely necessary
• Infer types from schemas and function returns
• Use generics with T prefix: TData, TReturn, TArgs
• Fix type errors at the source, not at the point of use

Husky & lint-staged

Pre-commit hooks automatically run quality checks:

What Happens on Commit

1. Staged files are automatically linted with oxlint and formatted with oxfmt
2. Syntax errors prevent commits
3. Type errors must be fixed before pushing

Git Hooks

Located in .husky/:

• pre-commit: Runs oxlint and oxfmt on staged files
• Prevents committing code with linting errors

Pre-commit Workflow

Example: Making a Change

# Edit files
$ vim src/MyComponent.tsx

# Stage changes
$ git add src/MyComponent.tsx

# Commit (triggers pre-commit hook)
$ git commit -m "Add MyComponent"
# → oxfmt automatically formats your code
# → oxlint catches syntax and style errors
# → Errors fail the commit

If you have linting or formatting issues:

# Fix all issues automatically
pnpm lint-format:fix

# Then re-stage and commit
git add .
git commit -m "Add MyComponent"

Continuous Integration

In CI environments, all checks run:

pnpm lint-format  # Verify linting and formatting
pnpm tsc --noEmit # Type checking
pnpm build        # Production build

Failing CI prevents merging to main.

Standards Summary

Overriding Rules

To disable an oxlint rule for a specific line:

// oxlint-disable-next-line no-async-promise-executor
const x = new Promise(async () => {})

For TypeScript:

// @ts-ignore
const x: string = 123

Avoid overrides unless absolutely necessary—they're a code smell.