Contract Forge Starter

Ultimate AI-Native React/TypeScript Starter Pack implementing Alperen Keleş's "Test, Don't Verify" philosophy.

Philosophy

This starter pack shifts from a focus on implementation details to a focus on observable outcomes. For AI-assisted coding, this is the "Holy Grail." AI is terrible at maintaining complex internal state logic but excellent at writing code that passes a rigorous test suite. By providing a "Test, Don't Verify" foundation, you give the AI a feedback loop where it can fix its own mistakes without human intervention.

Core Principles

1. Test Observable Outcomes: Don't test if a function was called; test if the user sees the expected result.
2. Contract-First Development: Define Zod schemas before writing code. All data boundaries must be validated.
3. AI Self-Correction: The AI can read test failures and fix code without human intervention.
4. Type Safety: TypeScript strict mode + Zod schemas = AI-proof validation.

Tech Stack

Core

• Next.js 16 (App Router) - Unified server/client boundary
• TypeScript (Strict mode) - Type safety
• Prisma + SQLite - Database/ORM (SQLite is AI-readable)
• Zod - Runtime validation and TypeScript types
• Zustand + Immer - Lightweight state management

Server Actions & Validation

• next-safe-action - Type-safe Server Actions with Zod
• Better Auth - Authentication built on Prisma/Zod

UI & UX

• shadcn/ui - Copy-paste components (AI can read/modify source)
• React Hook Form + Zod resolver - Form handling
• TanStack Query - Server state synchronization
• Sonner - Toast notifications (observable outcomes)
• Lucide React - Predictable icon library
• Framer Motion - Declarative animations

Testing

• Playwright - E2E testing (observable outcomes)
• Vitest - Integration testing
• @axe-core/playwright - Accessibility testing

Developer Experience

• Biome - Fast linting + formatting (replaces ESLint/Prettier)
• ts-reset - Improved TypeScript global types
• zod-to-json-schema - Export schemas for AI tool-calling

Getting Started

Prerequisites

• Node.js 18+
• npm or pnpm

Installation

1. Clone the repository:

git clone <your-repo-url>
cd contract-forge-starter

2. Install dependencies:

npm install

3. Set up the database:

# Copy the example env file and adjust as needed
cp .env.example .env

# Set DATABASE_URL in .env (or use default)
# DATABASE_URL="file:./dev.db"

# Generate Prisma client and run migrations
npm run db:generate
npm run db:migrate

4. Start the development server:

npm run dev

5. Open http://localhost:3000

Project Structure

├── .cursorrules          # AI behavior guidelines
├── prisma/               # Prisma schema and migrations
├── src/
│   ├── app/             # Next.js App Router routes
│   │   └── api/        # API routes (including /dev/db-check)
│   ├── components/     # React components (shadcn/ui)
│   ├── hooks/           # Custom React hooks
│   ├── lib/
│   │   ├── actions/    # Server Actions with Zod validation
│   │   ├── schemas/    # Zod schemas (source of truth)
│   │   ├── queries/    # React Query key factory
│   │   ├── db.ts       # Prisma client
│   │   └── auth.ts     # Better Auth configuration
│   ├── stores/         # Zustand stores
│   └── __tests__/
│       ├── integration/ # Vitest integration tests
│       └── utils/       # Test utilities
└── tests/
    └── e2e/            # Playwright E2E tests

Development Workflow

Adding a New Feature

1. Define the Contract (Zod schema in src/lib/schemas/)
2. Write a Failing Test (Playwright E2E test in tests/e2e/)
3. Implement the Server Action (with Zod validation in src/lib/actions/)
4. Create the UI Component (using shadcn/ui components)
5. Run Quality Checks: npm run ai:check
6. Fix Issues: Use the test feedback loop

AI-Assisted Development

The .cursorrules file instructs AI agents to:

• Always write tests before implementing features
• Use Zod for all validation
• Run npm run ai:check before completing tasks
• Fix test failures automatically using the feedback loop

Quality Checks

# Run all checks (Biome + TypeScript + Vitest + Playwright)
npm run ai:check

# Auto-fix formatting and linting
npm run ai:fix

# Type checking only
npm run type-check

# Run tests
npm test              # Vitest
npm run test:e2e      # Playwright

Testing Philosophy

E2E Tests (Playwright)

Test what the user sees, not how it's implemented:

test("should create a task", async ({ page }) => {
  await page.goto("/");
  await page.fill('[data-testid="task-title-input"]', "My Task");
  await page.click('[data-testid="task-submit-button"]');

  // Test observable outcome: success toast appears
  await expect(page.locator('text=Task created successfully')).toBeVisible();
});

Integration Tests (Vitest)

Test contracts (Zod schemas):

it("should validate task schema", () => {
  const result = TaskSchema.safeParse({ title: "ab" }); // Too short
  expect(result.success).toBe(false);
});

Database Inspection

In development, you can inspect the database state via:

GET /api/dev/db-check

This allows AI agents to verify data was saved correctly during test runs.

Scripts

• npm run dev - Start development server
• npm run build - Build for production
• npm run lint - Run Biome checks
• npm run format - Format code with Biome
• npm run type-check - TypeScript type checking
• npm test - Run Vitest tests
• npm run test:e2e - Run Playwright E2E tests
• npm run ai:check - Run all quality checks (Biome + TypeScript + Vitest + Playwright)
• npm run ai:fix - Auto-fix formatting/linting
• npm run db:migrate - Run Prisma migrations
• npm run db:studio - Open Prisma Studio

Playwright uses PLAYWRIGHT_DATABASE_URL (defaults to file:./prisma/test.db) and applies migrations during global setup. To reuse an already running dev server, set PLAYWRIGHT_START_WEB_SERVER=false and PLAYWRIGHT_BASE_URL to the server URL.

Contributing

See CONTRIBUTING.md for development workflow guidelines.

License

MIT