Skip to content
Shell
4.4 KB
Raw Blame

STACK.md

ID8Labs Default Technology Stack

Unless there's a specific reason to deviate, use these defaults.


Why Defaults Matter

Every technology decision has a learning curve and integration cost. By standardizing on a stack:

  • We compound expertise across projects
  • Patterns become reusable
  • Onboarding is instant
  • Debugging is familiar

Deviate when there's a clear reason. Document when you do.


The Stack

Frontend

Layer Default Why
Framework Next.js 14+ (App Router) Full-stack React, great DX, Vercel integration
Styling Tailwind CSS Utility-first, fast iteration, consistent
Components shadcn/ui Accessible, customizable, owns the code
State Zustand (simple) / React Query (server) Minimal boilerplate, great DX
Forms React Hook Form + Zod Type-safe validation, good UX

Backend

Layer Default Why
API Next.js API Routes / Server Actions Colocation, type safety
Database Supabase (PostgreSQL) Generous free tier, auth included, real-time
Auth Supabase Auth Integrated, handles OAuth, sessions
Storage Supabase Storage Same platform, good CDN
Edge Functions Vercel Edge / Supabase Edge Low latency, global

Infrastructure

Layer Default Why
Hosting Vercel Best Next.js support, great DX
Domain Vercel Domains or Cloudflare Easy DNS, SSL automatic
Monitoring Vercel Analytics + Sentry Built-in + error tracking
Email Resend Simple API, good deliverability

Development

Tool Default Why
Package Manager pnpm Fast, disk efficient
TypeScript Always Catch errors early
Linting ESLint + Prettier Consistent code
Testing Vitest (unit) + Playwright (e2e) Fast, modern
Git GitHub Ecosystem, Actions, Copilot

Project Initialization

# New Next.js project with defaults
pnpm create next-app@latest my-project --typescript --tailwind --eslint --app --src-dir

# Add shadcn/ui
pnpm dlx shadcn-ui@latest init

# Add common dependencies
pnpm add @supabase/supabase-js zustand zod react-hook-form @hookform/resolvers

# Add dev dependencies
pnpm add -D vitest @playwright/test

Supabase Setup Pattern

// lib/supabase/client.ts - Browser client
import { createBrowserClient } from '@supabase/ssr'

export function createClient() {
  return createBrowserClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
  )
}

// lib/supabase/server.ts - Server client
import { createServerClient } from '@supabase/ssr'
import { cookies } from 'next/headers'

export function createClient() {
  const cookieStore = cookies()
  return createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        get(name: string) {
          return cookieStore.get(name)?.value
        },
        // ... set, remove
      },
    }
  )
}

Environment Variables Template

# .env.local
NEXT_PUBLIC_SUPABASE_URL=your-project-url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-key  # Server only, never expose

# Optional
NEXT_PUBLIC_APP_URL=http://localhost:3000
RESEND_API_KEY=your-resend-key
SENTRY_DSN=your-sentry-dsn

When to Deviate

Valid Reasons to Use Something Else

Situation Alternative Example
Mobile app needed React Native / Expo Cross-platform native
Heavy real-time Socket.io / Ably Chat, collaboration
Complex state Redux Toolkit Large enterprise app
Static site only Astro Marketing site, blog
Need CMS Sanity / Contentful Content-heavy site
Specific cloud AWS / GCP Client requirement

Document Deviations

When using non-default tech, add to project file:

### Stack Deviation: [Tech]
**Default**: [What we normally use]
**Using Instead**: [What we're using]
**Reason**: [Why this project needs it]
**Tradeoffs**: [What we lose/gain]

Remember

"Choose boring technology." - Dan McKinley

The stack exists to ship products, not to learn new tools. Save innovation tokens for your product's differentiators.