Contributing

Thanks for wanting to contribute! Here's everything you need to get started.

Important: Open an issue before starting work on new features or major changes.

TL;DR

git clone https://github.com/Marve10s/Better-Fullstack.git
cd Better-Fullstack
bun install
bun dev:cli    # CLI development
bun dev:web    # Website development

Project Structure

├── apps/
│   ├── cli/                    # create-better-fullstack CLI
│   └── web/                    # Documentation website
└── packages/
    ├── template-generator/     # Handlebars templates → generated output
    ├── types/                  # Shared TypeScript types & schemas
    ├── backend/                # Convex backend
    └── create-bfs/             # Project bootstrapper

Development

Prerequisites

• Node.js (LTS)
• Bun (recommended)

Setup

git clone https://github.com/Marve10s/Better-Fullstack.git
cd Better-Fullstack
bun install

CLI

bun dev:cli

Runs tsdown in watch mode. To test globally:

cd apps/cli && bun link
create-better-fullstack

Website

bun dev:web

Template Generator

After editing .hbs template files:

bun run --filter=@better-fullstack/template-generator generate-templates
bun run --filter=@better-fullstack/template-generator build
bun run --filter=create-better-fullstack build

After editing src/post-process/*.ts files, only the build steps are needed (skip generate-templates).

Testing

Quick reference

bun run test              # CLI unit tests
bun run test:all          # All tests across the monorepo
bun run lint              # Lint all packages (turbo lint)
bun run check             # Format + lint (oxfmt + oxlint)

CLI tests

bun run test:cli          # Unit tests
bun run test --watch      # Watch mode (from apps/cli/)
bun run test:coverage     # With coverage report
bun run test:ci           # CI mode (bail after 5 failures)
bun run test:e2e          # End-to-end tests

Matrix tests

Test combinations of frontends, backends, databases, etc:

bun run test:matrix       # Batched mode
bun run test:matrix:fast  # 10% random sample
bun run test:matrix:full  # All combinations (slow)

Web tests

cd apps/web
bun test                           # Unit tests
bun run validate:tech-links        # Validate all tech resource links
bun run perf:check                 # Check performance budget

Type checking

bun run --filter=create-better-fullstack check-types     # CLI
bun run --filter=web typecheck                           # Website
bun run --filter=@better-fullstack/template-generator typecheck  # Template generator

Build

turbo build               # Build everything
bun run build:cli         # CLI only
bun run build:web         # Website only

Dependency Management

bun run update-deps       # Check template dependency versions
bun run update-deps:fix   # Auto-update template dependency versions
bun run sync-versions     # Check template version sync

Making Changes

1. Open an issue — Describe the bug or feature
2. Fork & clone — Create your own copy
3. Branch — git checkout -b feat/your-feature or fix/your-bug
4. Code — Follow existing patterns
5. Test — bun run test
6. Lint — bun run check
7. Commit — Use conventional commits (see below)
8. Push & PR — Link the related issue

Commit Convention

feat: add new feature
fix: resolve bug
docs: update documentation
chore: maintenance tasks
refactor: code changes without feature/fix
test: add or update tests

Lefthook runs turbo lint on every commit automatically.

Need Help?

• Check existing issues
• Open a new issue with your question

---

By contributing, you agree that your contributions will be licensed under the MIT License.