Development Guide

Shipkit is built for developers who want to ship fast. Let's get you set up and building.

Quick Start

Get Shipkit running in 4 steps:

  1. Clone the repo:

    git clone https://github.com/your-repo/shipkit.git
cd shipkit

  2. Install dependencies:

    bun install --frozen-lockfile

  3. Set up environment:

    cp .env.example .env.local
# Edit .env.local with your values

  4. Start developing:

    bun dev

That's it! You're ready to build.

What You Need

Required Tools

  • Node.js v18+ (download)
  • Bun v1.1+ (install)
  • PostgreSQL v15+ (for database features)
  • VS Code (recommended)

VS Code Setup

Install these extensions for the best experience:

  • Biome - Code formatting and linting
  • Tailwind CSS IntelliSense - CSS autocompletion
  • TypeScript Importer - Smart imports
  • MDX - Markdown with JSX support

Project Structure

Shipkit follows a clean, logical structure:

src/
├── app/                 # Next.js App Router pages
├── components/          # React components
│   ├── ui/             # Reusable UI components
│   └── blocks/         # Page-specific components
├── lib/                # Utility functions
├── server/             # Backend code
│   ├── actions/        # Server actions
│   ├── auth/          # Authentication config
│   └── services/      # Business logic
└── styles/             # Global styles

Development Workflow

Components

  • Server components first - Better performance, fewer bugs
  • Client components only when needed - For interactivity (forms, animations)
  • Organize by purpose - UI components in ui/, page blocks in blocks/

API Routes

  • Server actions for forms and mutations
  • API routes for external integrations
  • Zod validation on all inputs
  • Consistent error handling

Database

  • Drizzle ORM for type-safe queries
  • Migrations for schema changes
  • Transactions for data consistency

Authentication

  • Auth.js v5 for all auth needs
  • Multiple providers supported
  • Server-side sessions preferred

Common Tasks

Add a New Page

# Create app/(app)/my-page/page.tsx
export default function MyPage() {
  return <div>Hello World</div>;
}

Add a Component

// src/components/ui/my-component.tsx
export function MyComponent() {
  return <div>My Component</div>;
}

Add Database Schema

bun run db:generate
# Edit the migration file
bun run db:migrate

Feature Flags

Control features with environment variables:

# Enable Stripe payments
NEXT_PUBLIC_FEATURE_STRIPE_ENABLED=true

# Enable GitHub auth
NEXT_PUBLIC_FEATURE_AUTH_GITHUB_ENABLED=true

Features auto-enable when you add the required env vars.

Before Production

Run these checks:

# Type checking
bun run typecheck

# Code quality
bun run lint

# Tests (if you have them)
bun run test

# Build test
bun run build

Need Help?