Shell
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 |
| 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.