Bun + Biome + Lefthook + commitlint + Fallow bootstrap for new projects (silica-cli pattern)

bun-tooling-bootstrap.md

Bun tooling bootstrap

A baseline setup for a new TypeScript/Bun project. Used in silica-cli. Copy the files, tweak the values that are personal preference, ship.

What you get

• Biome for linting and formatting (replaces ESLint + Prettier)
• Lefthook for git hooks
• commitlint enforcing conventional commits
• Fallow for codebase intelligence (dead code, duplication, complexity)
• tsc --noEmit wired into pre-commit for type safety
• One install command that sets up hooks automatically

Install

bun add -d @biomejs/biome lefthook @commitlint/cli @commitlint/config-conventional fallow

Files

biome.json

{
    "$schema": "https://biomejs.dev/schemas/2.4/schema.json",
    "vcs": {
        "enabled": true,
        "clientKind": "git",
        "useIgnoreFile": true
    },
    "files": {
        "ignoreUnknown": false,
        "includes": ["**", "!**/node_modules", "!**/dist", "!**/build", "!**/.astro", "!**/.idea", "!**/.turbo"]
    },
    "formatter": {
        "enabled": true,
        "indentStyle": "space",
        "indentWidth": 4,
        "lineWidth": 120
    },
    "linter": {
        "enabled": true,
        "rules": {
            "recommended": true,
            "correctness": {
                "noUnusedVariables": "error",
                "useImportExtensions": "off"
            }
        }
    },
    "javascript": {
        "formatter": {
            "quoteStyle": "single",
            "trailingCommas": "all",
            "semicolons": "always"
        }
    },
    "json": {
        "parser": {
            "allowComments": true
        }
    },
    "assist": {
        "enabled": true,
        "actions": {
            "source": {
                "organizeImports": "on"
            }
        }
    }
}

.commitlintrc.json

{
    "extends": ["@commitlint/config-conventional"]
}

lefthook.yml

pre-commit:
  parallel: true
  commands:
    lint:
      run: ~/.bun/bin/bun run lint
      skip:
        - merge
        - rebase
    types:
      run: ~/.bun/bin/bun run check:types
      skip:
        - merge
        - rebase
    fallow:
      run: ~/.bun/bin/bunx fallow dead-code
      skip:
        - merge
        - rebase
commit-msg:
  parallel: true
  commands:
    commitlint:
      run: ~/.bun/bin/bunx commitlint --edit $1

Note on ~/.bun/bin/bun: the path is hardcoded to match how Bun installs on this machine. If your Bun is on $PATH (e.g. via a Homebrew install or a different shim), replace ~/.bun/bin/bun with bun. The skip: merge, rebase entries keep the hooks from re-running on fast-forwarded commits.

package.json scripts

Add these to your package.json:

{
  "scripts": {
    "prepare": "lefthook install",
    "check:types": "tsc --noEmit",
    "lint": "biome lint src/",
    "format": "biome format --write src/"
  }
}

The prepare script means bun install wires up the git hooks automatically — you don't have to remember to run lefthook install yourself.

Verify it works

# bad commit message should fail
git commit --allow-empty -m "stuff"
# -> commitlint should reject this

# good commit message should pass
git commit --allow-empty -m "chore: verify tooling bootstrap"
# -> biome, tsc, and fallow all run; commit succeeds

What's intentionally not included

• No ESLint, no Prettier. Biome covers both. Adding the others is duplicate tooling.
• No Husky. Lefthook is a single YAML file and faster.
• No tsconfig.json template. Project shape varies; copy from your previous project or the Bun init default.
• No formatter for tests / lockfiles. lint: biome lint src/ only covers source. Extend the glob if you want more.
• No CI config. Hooks run locally; CI is a separate concern.

Tweaking the personal bits

These are the values that reflect one developer's taste. Adjust freely:

• indentWidth: 4 — 2 is also common
• lineWidth: 120 — 80 is the default in most formatters
• quoteStyle: single — Biome defaults to double
• trailingCommas: all — es5 is more conservative, none is also valid

other conventions:

1. prefer a service oriented architecture with business logic living in classes for easier testing
2. prefer path alias for apps
3. prefer protected visibility over private
4. 1 file per class
5. class file name should match class name