Turbostack: Convex + Next.js + Vite + Clerk + Turborepo + Vercel
A premium, production-ready monorepo template for building high-performance, type-safe full-stack applications. Includes a Next.js marketing site and a Vite-powered app ready for native deployment via Capacitor.
✨ Features
- 🏎️ Turborepo - High-performance build system for JavaScript/TypeScript monorepos.
- 🎨 Modern UI - Tailwind CSS v4 with shadcn/ui and Base UI primitives. No Radix UI.
- 📱 Cross-Platform - Shared logic and components across Next.js (Marketing) and Vite React (App), with Capacitor for native deployments.
- ⚡ Reactive Backend - Convex for a 100% type-safe, real-time backend and database.
- 🔐 Optional Auth - Clerk integration for user management — fully optional; the stack runs auth-free when Clerk env vars are unset.
- 🛠️ Unified Toolchain - Biome for lightning-fast linting and formatting.
- 📈 Analytics - A key-gated PostHog package (
@repo/analytics) for product analytics; every event is stamped with product and surface so products can share one PostHog project.
- 🧰 DX & Safety - Typed/validated env (
@t3-oss/env), Portless named .localhost dev URLs, git hooks (Biome + commitlint), and GitHub Actions CI.
🛠️ Tech Stack
📁 Project Structure
├── apps/
│ ├── www/ # Next.js marketing site & landing pages
│ └── app/ # Vite React app (Capacitor-ready, runs on port 5173)
├── e2e/
│ ├── app/ # Playwright specs for apps/app
│ └── www/ # Playwright specs for apps/www
├── packages/
│ ├── api/ # Convex backend, schema, and shared business logic
│ ├── ui/ # Shared high-performance UI components
│ ├── analytics/ # Key-gated PostHog analytics provider
│ ├── e2e-kit/ # Playwright harness: servers, Convex seed, page objects
│ └── config/ # Shared TypeScript & Tailwind configurations
└── docs/ # Project documentation and changelogs
🚀 Getting Started
Prerequisites
- Convex account
- Vercel account
- Clerk account (optional — only if you want auth)
- Node.js 24 (see
.nvmrc — e.g. nvm use)
- pnpm (
npm install -g pnpm)
Quick Start
-
Clone the repo:
git clone <repository-url>
cd turbostack
-
Install dependencies:
pnpm install
-
Set up environment variables:
Local development secrets live in Doppler, not in
.env.local files. doppler.yaml maps each package to a config in the
turbostack project — packages/api → dev_api, apps/app → dev_app,
apps/www → dev_www — and each package's dev script runs under
doppler run. Once per checkout (and per git worktree, since Doppler
remembers the selection by path):
brew install dopplerhq/cli/doppler
doppler login
pnpm setup:envs # doppler setup --no-interactive
Each package's .env.example lists the variables its Doppler config holds.
Production is not in Doppler — Vercel supplies its own values.
-
(Optional) Clerk Auth Keys:
Clerk is optional — skip this to run without auth. To enable it, go to your Clerk Dashboard > API Keys and add the keys to the dev_www and dev_app Doppler configs.
-
Convex:
The Convex CLI reads CONVEX_DEPLOY_KEY (a dev deploy key) from the dev_api
config, so pnpm dev needs no npx convex login. For any other Convex CLI
command, go through the same wrapper:
pnpm --filter @repo/api convex env list
-
Run the development environment:
# From the root
pnpm dev
🔐 Authentication Setup
To sync Clerk auth with your Convex backend:
-
Clerk Dashboard:
- Go to Configure > JWT Templates > New Template > Convex.
- This creates a template named
convex.
- Copy the Issuer URL (or use the Frontend API URL from API Keys).
-
Convex Dashboard:
- Go to Settings > Environment Variables.
- Add
CLERK_JWT_ISSUER_DOMAIN and paste the URL.
Note: Ensure you do this for both Production and Development environments in Clerk.
🛠️ Development Workflows
- Dev:
pnpm dev — runs all apps via Turbo. Portless serves stable HTTPS .localhost URLs (e.g. https://www.turbostack.localhost, https://app.turbostack.localhost).
- Lint & Format:
pnpm lint / pnpm format / pnpm check (Biome).
- Typecheck:
pnpm typecheck (per-package tsc --noEmit).
- Unit tests:
pnpm test (Storybook component tests in a real browser; excludes e2e).
- E2E tests:
pnpm test:e2e runs both Playwright suites; pnpm test:e2e:app / pnpm test:e2e:www run one. Safe to run from several git worktrees at once.
- Storybook:
pnpm storybook (visualize shared components).
- Build:
pnpm build (optimized production build for all apps).
Git hooks (lefthook) run Biome on staged files and validate Conventional Commits on each commit — they install automatically on pnpm install.
🚢 Deployment
main deploys to staging and prod deploys to production. Environments, domains, variables and how to set staging up are in docs/infrastructure.md. The steps below are for setting up a Vercel project from scratch.
Vercel (Full Stack)
-
Create Vercel Project:
- Go to Vercel, create a new project, and import your repository.
- Hit Deploy. The first build may fail until Convex is connected (it needs a
CONVEX_DEPLOY_KEY). Clerk is optional and not required to deploy.
-
Connect Integrations:
- In your Vercel project, go to Settings > Integrations.
- Install and connect Clerk.
- Install and connect Convex. Vercel will automatically handle production environment variables.
-
Configure Clerk Domains:
- In the Clerk Dashboard, go to Configure > Domains.
- Complete the domain configuration for your Vercel URL, otherwise Vercel's production checks may fail.
-
Add JWT Template:
- In Clerk, go to JWT Templates and add the Convex template for both
prod and dev.
-
Finalize Convex Prod Env:
- Go to the Clerk Dashboard > API Keys and copy the Frontend API URL.
- In the Convex Dashboard, go to your production project > Settings > Environment Variables.
- Add
CLERK_JWT_ISSUER_DOMAIN with the value you copied.
-
Redeploy:
- Go back to Vercel and trigger a redeploy. Your app should now be live and fully integrated!
🤝 Contributing
Before contributing, please read AGENTS.md for our standards on:
- Conventional Commits
- Tailwind v4 & shadcn/ui patterns
- Mandatory Base UI usage (No Radix UI)
- Type safety and strict Biome checks
Built with ❤️ by Cloudexible
