Development Workflows

ShipKit provides a streamlined development environment with tools and scripts for efficient development.

Local Development Setup

Prerequisites

1. Node.js

   • Use Node.js 18.x or later
   • Recommended: Use nvm with .nvmrc

2. Package Manager

   • PNPM is the default package manager
   • Install: npm install -g pnpm

3. Docker

   • Required for local database
   • Docker Compose for service orchestration

Environment Setup

1. Clone Repository

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

2. Install Dependencies

   pnpm install
   

3. Environment Variables

   cp .env.example .env
   # Edit .env with your configuration
   

4. Start Database

   docker-compose up -d
   

Development Server

1. Start Development Server

   pnpm dev
   

2. Access Application

   • Web: http://localhost:3000
   • Payload CMS: http://localhost:3000/admin

Database Management

Database Scripts

1. Sync Database

   pnpm db:sync
   

   This script:

   • Runs Drizzle migrations
   • Initializes Payload CMS
   • Seeds database if SEED_DB=true

2. Seed Database

   pnpm db:seed
   

   Seeds the database with:

   • CMS collections (RBAC, Features, FAQs, Testimonials)
   • Initial content

3. Drop Database

   pnpm db:drop
   

   Removes all database tables and content

Database Configuration

// docker-compose.yml
services:
  db:
    image: postgres:15
    environment:
      POSTGRES_DB: ${POSTGRES_DB:-lacy}
      POSTGRES_USER: ${POSTGRES_USER:-lacy_user}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-lacy_password}
    ports:
      - "5432:5432"

Development Tools

Code Quality

1. TypeScript

   • Strict mode enabled
   • Path aliases configured
   • Server/client type separation

2. ESLint

   pnpm lint
   pnpm lint:fix
   

3. Prettier

   pnpm format
   pnpm format:check
   

4. Biome

   pnpm biome:check
   pnpm biome:fix
   

Testing

1. Vitest Configuration

   // vitest.config.ts
   export default defineConfig({
     test: {
       environment: "node",
       include: ["src/**/*.test.ts"],
     },
   })
   

2. Run Tests

   pnpm test           # Run all tests
   pnpm test:watch     # Watch mode
   pnpm test:coverage  # Coverage report
   

Development Practices

Git Workflow

1. Branch Naming

   • Feature: feature/description
   • Fix: fix/description
   • Release: release/version

2. Commit Messages

   • Follow conventional commits
   • Include scope: feat(auth): add OAuth provider

3. Pull Requests

   • Use PR template
   • Include tests
   • Update documentation

Code Organization

1. Directory Structure

   src/
   ├── app/           # Next.js app router
   ├── components/    # React components
   ├── server/        # Server-side code
   │   ├── actions/   # Server actions
   │   ├── services/  # Internal services
   │   └── db/        # Database layer
   ├── lib/           # Shared utilities
   └── types/         # TypeScript types
   

2. Component Guidelines

   • Use functional components
   • Implement proper types
   • Add JSDoc comments
   • Include tests

3. API Guidelines

   • Use server actions
   • Implement error handling
   • Add request validation
   • Document endpoints

Environment Management

Configuration Files

1. Next.js Config

   // next.config.ts
   const config = {
     // Configuration options
   }
   

2. TypeScript Config

   // tsconfig.json
   {
     "compilerOptions": {
       "strict": true,
       "paths": {
         "@/*": ["./src/*"]
       }
     }
   }
   

3. Environment Variables

   # .env.example
   DATABASE_URL=
   NEXTAUTH_SECRET=
   RESEND_API_KEY=
   

Environment Sync

# Sync environment variables
./scripts/sync-env.sh

# Sync with upstream
pnpm sync:upstream

Deployment

Vercel Deployment

1. Configuration

   // vercel.json
   {
     "buildCommand": "pnpm build",
     "devCommand": "pnpm dev",
     "installCommand": "pnpm install"
   }
   

2. Environment Setup

   • Configure production variables
   • Set up database connection
   • Enable edge functions

3. Deployment Commands

   pnpm deploy        # Deploy to production
   pnpm deploy:stage  # Deploy to staging
   

Best Practices

1. Code Quality

   • Write clean, maintainable code
   • Follow TypeScript best practices
   • Add comprehensive tests
   • Document complex logic

2. Performance

   • Optimize bundle size
   • Use proper caching
   • Implement lazy loading
   • Monitor metrics

3. Security

   • Follow security guidelines
   • Validate user input
   • Use proper authentication
   • Handle sensitive data

4. Documentation

   • Keep docs up to date
   • Include code examples
   • Document breaking changes
   • Add troubleshooting guides

Notes

• Use TypeScript for all new code
• Follow the established coding style
• Write tests for new features
• Update documentation when needed
• Use server actions for API calls
• Keep dependencies up to date