Contributing

Before starting work on any new features or major changes, please open an issue first to discuss your proposal and get approval. We don’t want you to waste time on work that might not align with the project’s direction or get merged.

Overview

Better-T-Stack is an open-source monorepo containing:

CLI: apps/cli - The scaffolding CLI tool (create-better-t-stack)
Documentation: apps/web - Official website and documentation
Template Generator: packages/template-generator - Template generation engine
Backend: packages/backend - Convex backend for web features
Types: packages/types - Shared schemas and types

Prerequisites

Before you begin, ensure you have:

Node.js LTS (version 20 or higher)
Bun (recommended for development)
Git (for version control)

Development Setup

Clone the repository

git clone https://github.com/AmanVarshney01/create-better-t-stack.git
cd create-better-t-stack

Install dependencies

bun install

This installs all workspace dependencies across the monorepo.

Choose your development path

Decide whether you’re working on the CLI, documentation site, or both.

CLI Development

Navigate to CLI directory

cd apps/cli

Link the CLI globally (optional)

bun link

This allows you to use create-better-t-stack from anywhere in your system.

Start development server

bun dev

This runs tsdown build in watch mode, automatically rebuilding on changes.

Test the CLI

Navigate to a test folder and run:

create-better-t-stack

This will run your locally developed CLI.

CLI Testing

Before committing CLI changes:

cd apps/cli
bun run test          # Run test suite
bun run test:watch    # Run tests in watch mode
bun run test:coverage # Run tests with coverage

Documentation Development

Install dependencies

# From repo root
bun install

Setup backend

cd packages/backend
bun dev:setup

You can choose local development in the prompts.

Configure environment

Copy the Convex URL from packages/backend/.env.local to apps/web/.env:

NEXT_PUBLIC_CONVEX_URL=http://127.0.0.1:3210/

Set GitHub tokens

Run bun dev in the root. It will complain about GitHub tokens, so run this in packages/backend:

npx convex env set GITHUB_ACCESS_TOKEN=xxxxx
npx convex env set GITHUB_WEBHOOK_SECRET=xxxxx

Start development server

# From repo root
bun dev:web

This starts the Next.js development server at http://localhost:3333.

Code Style & Conventions

File Naming

Use kebab-case for files: database-setup.ts, template-processor.ts
Use PascalCase for types and components: CLIError, ProjectCreationError
Use camelCase for functions and variables: createProject, validateOptions

TypeScript

Language: TypeScript (strict mode enabled)
Modules: ESM-first ("type": "module" where applicable)
Keep feature logic near domain folders (helpers, utils, template-handlers)

Error Handling

In CLI code, prefer better-result over ad-hoc try/catch:

import { Result } from "better-result";

// Use typed Result<T, E>
const result = Result.try(() => riskyOperation());

result.match({
  ok: (data) => console.log(data),
  err: (error) => console.error(error),
});

Reuse domain errors from apps/cli/src/utils/errors.ts:

CLIError
ProjectCreationError
UserCancelledError

Template Authoring

Templates live in packages/template-generator/templates and use Handlebars with custom helpers:

{{!-- Conditional output --}}
{{#if (eq orm "prisma")}}
  // Prisma-specific code
{{else if (eq orm "drizzle")}}
  // Drizzle-specific code
{{/if}}

{{!-- Available helpers: eq, ne, and, or, includes --}}

Important: When files must contain literal {{ ... }} (Vue/JSX), escape braces:

\{{ vueVariable }}

Testing Guidelines

Framework: bun:test
Test files: *.test.ts naming convention
Location: apps/cli/test and packages/template-generator/test
Add or update tests with behavior changes (especially prompt flows, template output, config validation)
Keep tests deterministic; reuse shared setup utilities in apps/cli/test/setup.ts

Linting & Formatting

Before committing, ensure your code passes checks:

# From repo root
bun run check  # Runs oxfmt . && oxlint .

Formatting and linting use:

oxfmt for formatting
oxlint for linting

Contribution Workflow

Create an issue

If one doesn’t exist, create an issue describing:

The bug or feature request
Steps to reproduce (for bugs)
Proposed solution

Fork the repository

Click the “Fork” button on GitHub and clone your fork locally.

Create a feature branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

Make your changes

Follow existing code style
Update documentation as needed
Add or update tests

Test and format

# For CLI changes
cd apps/cli
bun dev
bun run test

# Lint and format (from root)
bun run check

Commit your changes

Use conventional commits with appropriate scope:

git add .
git commit -m "feat(cli): add new feature"
# or
git commit -m "fix(web): fix bug description"

Push to your fork

git push origin feature/your-feature-name

Create a Pull Request

Link to the related issue
Describe your changes clearly
Include verification steps
Add screenshots/GIFs for UI changes

Commit Conventions

Use Conventional Commits with the appropriate scope:

feat(cli): add new CLI feature
fix(cli): fix CLI bug
feat(web): add new web feature
fix(web): fix web bug
chore(web): update dependencies
docs: update documentation
test(cli): add tests for feature

Pull Request Guidelines

Your PR should include:

Clear summary of changes
Linked issue (if applicable)
Verification steps run (bun run check, relevant tests)
Screenshots/GIFs for web UI changes
Breaking changes clearly marked (if any)

Available Commands

# Workspace commands (from root)
bun install           # Install workspace dependencies
bun dev:cli          # Watch-build CLI package
bun dev:web          # Run web app locally (next dev --port 3333)
bun build            # Build all packages/apps through Turbo
bun build:cli        # Build only the CLI target
bun run check        # Format + lint (oxfmt . && oxlint .)

# CLI-specific commands
cd apps/cli && bun run test          # Run CLI tests
cd apps/cli && bun run test:watch    # Run tests in watch mode
cd apps/cli && bun run test:coverage # Run tests with coverage

Getting Help

GitHub Issues

Open an issue for bugs or feature requests

GitHub Discussions

Join discussions for questions or ideas

Discord

Join our Discord for real-time help

Documentation

Check existing issues and PRs for similar work

License

By contributing to Better-T-Stack, you agree that your contributions will be licensed under the MIT License.

Resources

Overview

Prerequisites

Development Setup

CLI Development

CLI Testing

Documentation Development

Code Style & Conventions

File Naming

TypeScript

Error Handling

Template Authoring

Testing Guidelines

Linting & Formatting

Contribution Workflow

Commit Conventions

Pull Request Guidelines

Available Commands

Getting Help

GitHub Issues

GitHub Discussions

Discord

Documentation

License

Build docs developers (and LLMs) love

Resources

Documentation Index

​Overview

​Prerequisites

​Development Setup

​CLI Development

​CLI Testing

​Documentation Development

​Code Style & Conventions

​File Naming

​TypeScript

​Error Handling

​Template Authoring

​Testing Guidelines

​Linting & Formatting

​Contribution Workflow

​Commit Conventions

​Pull Request Guidelines

​Available Commands

​Getting Help

GitHub Issues

GitHub Discussions

Discord

Documentation

​License

Build docs developers (and LLMs) love

Overview

Prerequisites

Development Setup

CLI Development

CLI Testing

Documentation Development

Code Style & Conventions

File Naming

TypeScript

Error Handling

Template Authoring

Testing Guidelines

Linting & Formatting

Contribution Workflow

Commit Conventions

Pull Request Guidelines

Available Commands

Getting Help

License