Stack overview

GlassKit's stack is opinionated. Every choice trades flexibility for shipping speed. This page explains why each piece is there so you can decide what to keep and what to swap.

Toolchain

Bun

Why: 4–25× faster install than npm, faster test runner, native TypeScript support, drop-in npm replacement. Buyers feel the speed on every command. Vercel auto-detects bun.lock and uses Bun for production builds too — no config needed.

If you'd rather use npm, GlassKit works fine — delete bun.lock, run npm install to generate package-lock.json, commit it, and you're back on npm. You just lose the speed.

Runtime

Next.js 16.2 (App Router, RSC)

Why: React Server Components let you write database-touching code right next to the UI that uses it — no API layer between you and your data. Route groups ((web), (docs), (apps)) keep the marketing site, docs, and example apps on separate layouts without separate apps.

Warning: This is not the Next.js most LLMs were trained on. APIs, conventions, and file structure differ from Next.js 14. If you ask an AI assistant to write Next.js code, point it at node_modules/next/dist/docs/ first.

Key changes you'll hit:

params and searchParams in pages are async — await them
cookies(), headers(), draftMode() return Promises
The Pages Router still exists but everything in GlassKit is App Router
fetch no longer caches by default — opt in explicitly

React 19.2

Why: Server Actions, useActionState, useOptimistic, and the new use() hook make forms and async state simple without a state management library.

TypeScript (strict)

Why: Strict mode catches bugs that show up as runtime crashes in JS. tsconfig.json is wired with the path alias @/* pointing at the project root.

Auth

Clerk

Why: Drop-in <SignIn /> / <SignUp /> / <UserButton /> components. OAuth providers (Google, GitHub, Apple) configured in the dashboard. Middleware-based route protection. Excellent Next.js App Router support. Free tier covers 10K MAU.

Files: middleware.ts, app/(auth)/, lib/auth.ts.

Backend

Convex

Why: TypeScript-native real-time database with reactive queries, file storage, vector search, and scheduled functions all in one. Great fit for AR/voice apps where multi-device sync between glasses and phone matters. Free tier covers 1 GB storage and 1M function calls per month.

Files: convex/ — schema, queries, mutations, scheduled jobs.

Payments

Stripe

Why: Universal payment processor. Checkout sessions, webhooks with signature verification, customer portal, subscription helpers — all wired and ready to swap your keys into.

Files: lib/stripe.ts, app/api/stripe/checkout/route.ts, app/api/stripe/webhook/route.ts, lib/config.ts → plans.

Full walkthrough at Stripe setup.

UI

Tailwind CSS v4

Why: CSS-first config (no tailwind.config.js), native CSS variables, oklch color space for perceptually uniform palettes. The whole design system lives in app/globals.css — search for @theme.

shadcn/ui (Nova preset)

Why: Components you copy into your project, not a black-box library. Built on base-ui. Components live in components/ui/.

Geist Sans + Geist Mono

Why: Vercel's typeface family. Looks crisp, optimized for product interfaces. Loaded via next/font/google.

AI

Vercel AI SDK

Why: Provider-agnostic LLM client with streaming, tool use, and structured output built in. Swap Anthropic for OpenAI by changing one import.

Providers wired up:

@ai-sdk/anthropic — Claude Opus, Sonnet, Haiku
@ai-sdk/openai — GPT-4o, GPT-4o-mini, o1

See AI providers for the patterns.

Docs

Fumadocs

Why: MDX-based, beautifully themed, Orama search out of the box. The docs you're reading right now are Fumadocs running at the /docs route group with its own root layout.

Content lives in content/docs/. Add a new page by dropping a .mdx file there and adding it to meta.json.

Infra

GitHub Actions CI

Why: Catch bugs before they hit main. The workflow at .github/workflows/ci.yml runs typecheck, lint, and build on every pull request. Three green checks before merge.

Vercel (deployment target)

Why: One-click deploy from a GitHub repo. Preview deployments for every PR. Edge runtime where it matters. Custom domains with automatic HTTPS.

See Deploy for the production checklist.

File layout

glasskit/
├── app/
│   ├── (web)/              # Marketing site root layout
│   │   ├── page.tsx        # Landing page
│   │   ├── pricing/
│   │   └── thanks/
│   ├── (docs)/             # Fumadocs root layout
│   │   └── docs/[[...slug]]/
│   ├── (apps)/             # Example Meta Ray-Ban Display apps
│   ├── (auth)/             # Clerk sign-in / sign-up
│   ├── api/
│   │   ├── stripe/         # Stripe checkout + webhook
│   │   └── search/         # Fumadocs search
│   └── globals.css         # Tailwind v4 theme
├── components/
│   ├── landing/            # Hero, Features, Pricing, etc.
│   └── ui/                 # shadcn/ui Nova preset
├── convex/                 # Convex schema + functions
├── content/docs/           # MDX docs (this page)
├── lib/
│   ├── config.ts           # Single source of truth for site config
│   ├── env.ts              # Typed env vars (zod schema)
│   ├── stripe.ts           # Stripe helpers
│   └── source.ts           # Fumadocs source adapter
├── middleware.ts           # Clerk auth middleware
└── .github/workflows/      # CI