Skip to main content
We welcome contributions to ZeroStarter! Whether you’re fixing bugs, adding features, or improving documentation, your help is appreciated. This guide outlines the process for contributing and maintaining code quality.

​
Quick Start

1

Fork and Clone

Fork the repository and create a new branch with a descriptive name:
# Clone your fork
git clone https://github.com/YOUR_USERNAME/zerostarter.git
cd zerostarter

# Create a branch (use descriptive names)
git checkout -b feat/your-feature-name
# or
git checkout -b fix/your-bug-fix
Use prefixes like feat/, fix/, docs/, chore/ for branch names.
2

Install Dependencies

ZeroStarter uses Bun as its package manager and runtime:
# Install dependencies
bun install

# Set up environment variables
cp .env.example .env

# Generate and migrate database
bun run db:generate
bun run db:migrate
3

Make Changes

Make your changes following the code standards below.Add tests if applicable and ensure existing tests pass.
4

Run Quality Checks

Before committing, run these checks to ensure code quality:
# Build the project
bun run build

# Type checking
bun run check-types

# Format code
bun run format

# Lint code
bun run lint
Pre-commit hooks will automatically run these checks, but it’s good practice to run them manually first.
5

Commit Changes

Commit your changes using conventional commit format:
# Examples of good commit messages
git commit -m "feat: add user profile settings page"
git commit -m "fix: resolve authentication redirect issue"
git commit -m "docs: update installation guide"
git commit -m "chore: update dependencies"
See commit conventions for more details.
6

Submit Pull Request

Push your branch and open a pull request:
  1. Push your changes: git push origin your-branch-name
  2. Open a PR against the canary branch
  3. Describe your changes, motivation, and any migration notes
  4. Link related issues if applicable

​
Code Standards

​
Project Structure

ZeroStarter uses a monorepo architecture organized with Turborepo: 
.
├── api/
│   └── hono/          # Backend API server (Hono)
├── web/
│   └── next/          # Frontend application (Next.js)
└── packages/
    ├── auth/          # Shared authentication logic (Better Auth)
    ├── db/            # Database schema and Drizzle configuration
    ├── env/           # Type-safe environment variables
    └── tsconfig/      # Shared TypeScript configuration

​
Code Style

  • Always use TypeScript for type safety
  • Avoid any types - use proper typing
  • Export types and interfaces for reusability
  • Use type inference where possible
// Good
interface User {
  id: string
  email: string
  name: string | null
}

const getUser = async (id: string): Promise<User> => {
  // implementation
}

// Avoid
const getUser = async (id: any): Promise<any> => {
  // implementation
}
  • Use @/ alias for imports within a workspace
  • Use package names for cross-workspace imports
  • Group imports logically (external, internal, types)
// Good
import { hono } from "hono"
import { db } from "@packages/db"
import { apiClient } from "@/lib/api/client"
import type { User } from "@/types"

// Avoid
import { apiClient } from "../../../lib/api/client"
  • Only comment when absolutely necessary
  • Code should be self-documenting through clear naming
  • Use comments for complex logic or non-obvious decisions
// Good - self-documenting
const isUserActive = user.lastLoginAt > thirtyDaysAgo

// Avoid - unnecessary comment
// Check if user is active
const isActive = user.lastLoginAt > thirtyDaysAgo
Formatting is handled automatically by Oxfmt:
  • Run bun run format to format all files
  • Run bun run format:check to check formatting without changes
  • Pre-commit hooks automatically format staged files

​
Development Workflow

​
Available Scripts

Commonly used scripts from package.json: 
# Start development servers (TUI mode)
bun dev

# Build all packages and apps
bun run build

# Type checking across all workspaces
bun run check-types

# Lint all packages
bun run lint

# Format code with Oxfmt
bun run format

# Clean build artifacts and node_modules
bun run clean

# Generate database migrations
bun run db:generate

# Run database migrations
bun run db:migrate

# Open Drizzle Studio (database GUI)
bun run db:studio

​
Pre-commit Hooks

ZeroStarter uses Lefthook for Git hooks. Pre-commit hooks automatically:
  1. Audit dependencies (on canary branch only) 
    bun audit --audit-level high
  2. Run lint-staged to format and lint changed files
    • Formats with Oxfmt
    • Lints with Oxlint
    • Manages dependencies in package.json
  3. Build the project to ensure no build errors 
    bun run build

​
Commit Conventions

We use Conventional Commits enforced by commitlint:

feat

New feature for the user
feat: add email verification

fix

Bug fix for the user
fix: resolve login redirect issue

docs

Documentation changes
docs: update API reference

chore

Maintenance tasks
chore: update dependencies

refactor

Code refactoring
refactor: simplify auth logic

test

Adding or updating tests
test: add user service tests

perf

Performance improvements
perf: optimize database queries

ci

CI/CD changes
ci: update build workflow

<type>[(optional scope)]: <description>

[optional body]

[optional footer]
Examples:
# Simple commit
git commit -m "feat: add dark mode toggle"

# With scope
git commit -m "fix(auth): resolve session expiry issue"

# With body
git commit -m "feat: add user profile settings

Allow users to update their profile information including
name, email, and avatar. Includes form validation and
error handling."

# Breaking change
git commit -m "feat!: redesign authentication flow

BREAKING CHANGE: Previous auth tokens are no longer valid.
Users will need to re-authenticate."

​
Pull Request Guidelines

​
Before Opening a PR

1

Ensure Quality

  • All checks pass (build, check-types, format, lint)
  • Code follows project conventions
  • Commits follow conventional commit format
  • No merge conflicts with target branch
2

Write Clear Description

Include in your PR description:
  • What: Brief summary of changes
  • Why: Motivation and context
  • How: Implementation approach (if complex)
  • Migration notes: Any breaking changes or migration steps
  • Related issues: Link to issues being addressed
3

Target Correct Branch

  • Target canary branch for all PRs
  • PRs to main are only for releases (automated)

​
PR Template Example

## Description
Brief summary of changes

## Motivation
Why this change is needed

## Changes
- List of specific changes
- Each on a new line

## Migration Notes
Any breaking changes or required migrations

## Related Issues
Fixes #123
Related to #456

​
Large Changes

For breaking changes or large features, please open an issue first to discuss the approach before investing significant time in implementation.

​
Testing

While ZeroStarter doesn’t currently have a comprehensive test suite, we encourage:
  • Manual testing of your changes
  • Testing edge cases and error scenarios
  • Verifying type safety with bun run check-types
  • Testing in both development and production builds

​
Release Process

ZeroStarter uses an automated release workflow:
1

Development

All development happens on the canary branch.
2

Changelog

When PRs are merged to main, a changelog PR is automatically created to canary branch.
3

Version Bump

The changelog PR includes:
  • Updated CHANGELOG.md
  • Version bump in package.json
  • Contributor attribution
4

Release

Maintainers merge the changelog PR to create a new release.
Contributors don’t need to worry about versioning - it’s handled automatically by the CI/CD pipeline.

​
Getting Help

GitHub Issues

Report bugs or request features

Discussions

Ask questions and share ideas

Documentation

Browse the full documentation

Twitter/X

Follow @nrjdalal for updates

​
Code of Conduct

By contributing to ZeroStarter, you agree to:
  • Be respectful and inclusive in all interactions
  • Provide constructive feedback
  • Focus on what’s best for the community
  • Accept maintainer decisions gracefully

​
License

By contributing to ZeroStarter, you agree that your contributions will be licensed under the MIT License.
Thank you for contributing to ZeroStarter! Your efforts help make this project better for everyone.

Build docs developers (and LLMs) love

Get started for freeTalk to us