Project Structure

Understanding the project structure is crucial for efficient development. This guide will walk you through the main directories and files in the Supabase TDD Boilerplate.

Root Directory

The root directory contains configuration files and the main application folders:

supabase-tdd-boilerplate/
├── apps/                    # Main applications
│   ├── web/                # Next.js frontend application
│   └── api/                # Hono API application
├── packages/               # Shared packages
│   ├── supabase/          # Supabase configuration and migrations
│   ├── ui/                # Shared UI components
│   └── config/            # Shared configuration
├── .github/               # GitHub Actions workflows
├── .vscode/               # VS Code configuration
├── package.json           # Root package.json
├── pnpm-workspace.yaml    # PNPM workspace configuration
├── turbo.json            # Turborepo configuration
└── tsconfig.json         # Root TypeScript configuration

Apps Directory

Web Application (apps/web/)

The Next.js frontend application:

apps/web/
├── __mocks__/            # Mock files for testing
├── __tests__/           # Test files
├── .next/               # Next.js build output
├── app/                 # Next.js app directory
│   ├── api/            # API routes
│   └── layout.tsx      # Root layout
├── components/         # React components
│   ├── ui/            # Basic UI components
│   └── shared/        # Shared components
├── config/            # Configuration files
├── e2e/              # End-to-end tests
├── features/         # Feature-based components and logic
├── hooks/            # Custom React hooks
├── integration/      # Integration tests
├── lib/             # Utility functions and services
│   ├── supabase/    # Supabase client
│   └── utils/       # General utilities
├── playwright-report/ # Playwright test reports
├── public/          # Static files
├── types/          # TypeScript types
└── utils/          # Utility functions

API Application (apps/api/)

The Hono API application:

apps/api/
├── src/                  # Source directory
│   ├── config/          # Configuration files
│   ├── features/        # Feature-based route handlers and logic
│   ├── lib/            # Shared libraries and utilities
│   ├── middleware/     # Custom middleware
│   ├── routes/         # API route definitions
│   ├── test/           # Test files
│   ├── types/          # TypeScript type definitions
│   ├── app.ts          # Main application setup
│   └── server.ts       # Server entry point
├── .dockerignore       # Docker ignore file
├── .env                # Environment variables
├── .env.example        # Example environment variables
├── Dockerfile         # Docker configuration
├── eslint.config.js   # ESLint configuration
├── package.json       # Package dependencies
├── tsconfig.json      # TypeScript configuration
└── vitest.config.ts   # Vitest test configuration

Packages Directory

Supabase Package (packages/supabase/)

Contains Supabase-related files and configurations:

packages/supabase/
├── migrations/        # Database migrations
│   ├── 00000000000000_initial_schema.sql
│   ├── 00000000000001_organization_schema.sql
│   └── 00000000000002_team_schema.sql
├── seed.sql          # Seed data
├── types/           # Generated TypeScript types
└── supabase.config.ts # Supabase configuration

UI Package (packages/ui/)

Shared UI components:

packages/ui/
├── components/       # UI components
├── styles/          # Shared styles
└── tests/          # Component tests

Config Package (packages/config/)

Shared configuration:

packages/config/
├── eslint/         # ESLint configurations
├── typescript/     # TypeScript configurations
└── tailwind/       # Tailwind configurations

Testing Structure

The project follows a three-layer testing approach:

1. Unit Tests

   • Located in */test/ directories
   • Test individual components and functions
   • Use Vitest for testing

2. Integration Tests

   • Located in */integration/ directories
   • Test component interactions and API endpoints
   • Use Vitest with MSW for API mocking

3. E2E Tests

   • Located in apps/web/e2e/
   • Test complete user flows
   • Use Playwright for browser automation

Development Scripts

Common development scripts (run from root):

# Install dependencies
pnpm install

# Start development servers
pnpm dev

# Run tests
pnpm test:unit
pnpm test:integration
pnpm test:e2e

# Build applications
pnpm build

# Lint code
pnpm lint

# Format code
pnpm format

Next Steps

1. Set up Supabase locally
2. Configure the database
3. Set up Google Sign-In