Tech Stack

Purpose: Locked technology choices for Framework projects. Covers the core stack, frontend/backend libraries, infrastructure, observability, and outgrow triggers for when each tool should be replaced.

Core stack

Layer	Technology	Version
Language	TypeScript	Latest (strict mode)
Runtime	Node.js	20+ LTS
Framework	Next.js	15+ (App Router)
Package Manager	pnpm	Latest

Frontend

Category	Technology	Rationale
UI Framework	React 19	Industry standard, Next.js native
Styling	Tailwind CSS	Utility-first, fast iteration
Component Library	shadcn/ui	Copy-paste, customizable, accessible (Radix primitives)
Premium Templates	Shadcnblocks Premium	Pre-built sections, consistent quality
Server State	TanStack Query	Data fetching, caching, optimistic updates
Client State	Zustand	Simple, minimal boilerplate
Forms	React Hook Form	Performant, minimal re-renders
Validation	Zod	TypeScript-first, runtime + compile-time safety
Date/Time	Luxon	Timezone-aware, immutable. Never use native Date

Key rules:

• TanStack Query for server state, Zustand for UI state — Never mix
• shadcn/ui before custom — Check Shadcnblocks Premium first
• date-fns is scaffold-only — Exists as a peer dependency of react-day-picker (used by shadcn/ui Calendar); do not import date-fns directly — all application date/time logic must use Luxon

Backend

Category	Technology	Rationale
Database	Supabase (Postgres)	Managed, real-time, generous free tier
ORM	Prisma	Type-safe queries, great migrations
Auth	Clerk	Organizations, RBAC, webhooks, modern UX
API Style	REST (Next.js API routes)	Simple, built-in to Next.js
Validation	Zod	Same schemas for frontend + backend

Infrastructure

Category	Technology	Rationale
Hosting	Vercel	Zero-config Next.js, preview environments, edge
CI/CD	Vercel (automatic)	Auto-deploy on push
Domain/DNS	Vercel DNS	Integrated, free SSL

No dedicated staging -- preview deployments per PR replace traditional staging.

Observability

Category	Technology	Rationale
Logging	Axiom	Fast search, generous free tier, Next.js integration
Error Tracking	Sentry	Industry standard, source maps, release tracking
Analytics	PostHog	Product analytics + feature flags, privacy-friendly
AI Cost Tracking	Helicone	LLM observability, cost tracking per feature

External services

Category	Technology	Rationale
Email	Resend + React Email	Modern API, JSX email templates, type-safe. No sandbox — code-level guard redirects to delivered@resend.dev in non-prod. See environments.md for full strategy.
Payments	Stripe	Industry standard, best docs, complete platform
File Storage	Supabase Storage	Integrated with database, CDN

Development tools

Category	Technology
AI Development	Claude Code (full SDLC via sub-agents)
AI Models	Claude Haiku / Sonnet / Opus 4.6
Browser Automation	Playwright MCP (@playwright/mcp)
Issue Tracking	Linear
Version Control	Git + GitHub
Linting	ESLint
Formatting	Prettier
Type Checking	TypeScript strict

Testing

Category	Technology	Rationale
Unit/Integration	Vitest	Fast, Vite-native, better DX than Jest
E2E	Playwright	Modern, reliable, multi-browser
Component Testing	Vitest + Testing Library	Industry standard for React

Business operations

Category	Technology	Cost
Entity Formation	Stripe Atlas	$500 one-time
Banking	Brex	Free (Essentials)
Accounting	QuickBooks Online	$30/mo
Tax Filing	Fondo	~$4K/yr
Payments	Stripe	2.9% + $0.30

Feature flagging and experimentation

PostHog (already listed under Observability) is the locked choice for both analytics and feature flagging. No separate tool needed.

Capability	Description
Feature flags	Boolean and multivariate flags to gate features by user, group, or environment
Percentage rollouts	Gradual release to a percentage of users (e.g., 5% -> 25% -> 100%)
A/B testing	Experiment framework with statistical significance tracking
Kill switches	Instant feature disable without a deploy — flip the flag, traffic stops

Outgrow: Enterprise targeting rules or SOC 2 compliance requirements -> migrate to LaunchDarkly (Low effort -- feature flag API is similar).

Infrastructure patterns

Patterns production apps need. Some already exist as reference implementations; others are planned.

Pattern	Approach	Status	When to Add
Circuit breakers	Custom Prisma-backed (proven in wix-access: lib/infrastructure/circuit-breaker.ts). Wraps outbound API calls, persists state to Postgres. Suitable for <1K RPM.	Reference implementation exists	When calling unreliable external APIs
Dead letter queue	Custom Prisma-backed (proven in wix-access: lib/infrastructure/dlq.ts + /api/cron/process-dlq). Failed operations queued for retry with exponential backoff.	Reference implementation exists	When webhook/job failures need retry
Rate limiting	rate-limiter-flexible	Not started	When exposing public APIs
Caching	Upstash Redis (replaces deprecated Vercel KV, Dec 2024)	Not started	When read-heavy endpoints need <50ms response
Search	Meilisearch (self-hosted or cloud)	Not started	When full-text search needed beyond Postgres LIKE
Job queues	BullMQ (Redis-backed)	Not started	When async processing needed beyond Vercel cron
Webhook handling	HMAC signature verification + idempotency keys + queue processing. Partial reference in wix-access lib/webhooks/router.ts.	Partial implementation exists	When receiving inbound webhooks
API versioning	URL path prefix (/api/v1/)	Not started	Before first breaking change to a public API
Health checks	Liveness (/api/health) + Readiness (/api/ready) endpoints	Not started	For every deployed app
Email template editing	Topol.io (@topol.io/editor-react), implemented in packages/email-editor/. Complements Resend + React Email for drag-and-drop template editing.	Done	When non-technical users need to edit email templates

Outgrow triggers

When each technology should be replaced, what to migrate to, and estimated effort.

Technology	Outgrow When	Migrate To	Effort	Notes
Supabase	10K concurrent connections or read replicas needed	AWS RDS Postgres	Medium	Prisma abstracts most migration pain
Clerk	1M+ MAU ($20K/mo)	Auth.js + Supabase backing store	High	Clerk provides session mgmt, org RBAC, pre-built UI -- all must be rebuilt
PostHog	Enterprise flag targeting / SOC 2 compliance	LaunchDarkly	Low	Feature flag API is similar
Vercel	>$500/mo or custom infrastructure needs	AWS Amplify / ECS	High	Lose preview deployments, edge functions
Axiom	>1TB/mo log retention	Datadog / ELK	Medium	Query language migration
Sentry	Custom error processing pipeline	Self-hosted Sentry	Low	Same SDK, different backend
Resend	>50K emails/day or SMTP relay needed	SendGrid / AWS SES	Low	API abstraction makes swap easy
Prisma	Edge computing / raw SQL perf critical	Drizzle ORM	Medium	Schema-first to code-first migration. Complexity increases with Prisma Extensions/Pulse/Accelerate adoption
Topol.io	Enterprise template management	Stripo or Beefree	Medium	--
Upstash Redis	Sub-ms latency / >10GB	AWS ElastiCache	Low	Standard Redis protocol
Meilisearch	>1M queries/mo or >100GB index	Algolia	Medium	Different API, similar concepts

Agent sync process

When a library is added to the framework, three things must update:

1. This document (tech-stack.md) — Add the tool to the appropriate section
2. Relevant agent definitions — Add awareness via skills or inline context in the agent's .md file
3. Relevant skills — Create or update a SKILL.md if the tool has non-trivial integration patterns

Known drift resolved in this audit (March 2026):

• Topol.io — Implemented in packages/email-editor/ but was not in tech-stack.md
• Circuit breaker + DLQ — Built in wix-access but not documented as framework patterns
• PostHog feature flags — Locked decision for analytics, but feature flagging capability was undocumented

Principles behind choices

1. Optimize for solo developer + AI — Minimal config, strong TypeScript, AI-friendly
2. Prefer managed services — Less ops, focus on product, generous free tiers
3. Provide best-in-class DX — Fast feedback, clear errors, good docs
4. Stay cost-conscious — Pay-as-you-grow, no enterprise lock-in

Related documents

• SDLC Standards
• Testing Standards
• Security Standards
• Environments

---

Last updated: March 2026