Taxonomy at the Edge

Taxonomy at the Edge is an experimental boilerplate for Next.js 13+ that runs entirely on the Edge Runtime, adapted from shadcn's taxonomy starter so it can deploy to Cloudflare Pages, which requires the edge runtime.

What is Taxonomy at the Edge?

Taxonomy at the Edge is an experimental fork of shadcn's popular taxonomy starter application, redesigned so every route, including server-rendered pages, opts into the edge runtime. It takes a standard Next.js SaaS starter with authentication, database, documentation, blog, and Stripe subscriptions and replaces the parts that are incompatible with edge environments — NextAuth becomes Firebase Auth, Prisma becomes Drizzle, Contentlayer becomes next/mdx, PlanetScale becomes Cloudflare D1. The result is a deployable Next.js app for Cloudflare Pages with 0ms cold starts, though it can run anywhere the edge runtime is supported.

Key Features

• Edge Runtime everywhere — All routes, including server-rendered pages, include export const runtime = "edge" to opt into edge execution for broad deployment and fast cold starts.
• Firebase Auth with cookie-based sessions — Replaces NextAuth, which is currently incompatible with the edge runtime, using next-firebase-auth-edge to let server components read auth cookies directly instead of sending JWTs on every request.
• Drizzle ORM on Cloudflare D1 — Replaces Prisma, which is not edge-compatible; the database moved from PlanetScale to Cloudflare D1 in April 2024 when PlanetScale's free tier was discontinued.
• MDX content via next/mdx — Replaces Contentlayer because Contentlayer evaluates code at runtime using edge-incompatible APIs; documentation and blog pages render MDX directly.
• Stripe subscriptions adapted for edge — Stripe is modified to use Web Crypto, constructEventAsync, and createFetchHttpClient to work in edge runtime environments.
• shadcn/ui components in a separate package — The component library lives in a package named components, linked to the Next.js app through yarn workspaces, built with Radix UI and Tailwind CSS.
• TypeScript and Zod validation — The entire project is written in TypeScript and uses Zod for schema validation.
• Cloudflare Pages deployment configuration — Includes the exact build command (yarn && cd packages/web && npx @cloudflare/next-on-pages) and output directory (/packages/web/.vercel/output/static) needed to deploy on Cloudflare Pages.

Who should use Taxonomy at the Edge?

• Next.js developers deploying to Cloudflare Pages — This starter gives you a complete, known-good configuration for edge runtime, avoiding the pitfalls of running a standard Next.js app on Pages.
• Developers migrating from shadcn/taxonomy — If you already know the original starter, this repo shows exactly which dependencies were swapped and why, making it a practical migration guide.
• SaaS builders wanting a production-feature starter — The app includes authentication, database migrations, markdown documentation, a blog, and Stripe subscriptions out of the box.

What can you do with Taxonomy at the Edge?

• Deploy a full SaaS starter on Cloudflare Pages: Set the build command and output directory, configure your environment variables (including NODE_VERSION 18.19.1 and a FIREBASE_PRIVATE_KEY without literal newline characters), and get a live Next.js app with auth, blog, docs, and subscriptions.
• Explore edge runtime compatibility: Read the changelog-style "What's different" list to see concrete replacements — next/image is swapped because Cloudflare Pages doesn't support it, vercel/og is disabled for next-on-pages, and EditorJS is disabled because its wasm import breaks builds.
• Manage a Cloudflare D1 database: Run the included yarn scripts in the packages/web directory to generate migrations from the Drizzle schema, list unapplied migrations, and apply them locally, to preview, or to production.

How does it work?

Running locally requires installing dependencies with yarn, copying packages/web/.env.example to packages/web/.env.local with your own variables, then starting the dev server with yarn run web. For Cloudflare Pages, you push the repo to GitHub, follow Cloudflare's Next.js framework guide, set the build command and output directory, and ensure all environment variables are present or the build fails.

FAQ

Is Taxonomy at the Edge free?

Yes, the repository is licensed under the MIT license, so you can freely use and modify it for personal or commercial projects.

Why use Firebase Auth instead of NextAuth?

NextAuth is currently incompatible with the edge runtime, and next-firebase-auth-edge offers an easy cookie-based approach that works in server components without manually sending JWTs on each request.

Why is Prisma replaced with Drizzle?

Prisma is not currently compatible with the edge runtime, while Drizzle ORM is. The database itself runs on Cloudflare D1, and you can replace D1 with another database if you prefer.

What are the known limitations?

The table of contents on certain MDX pages is disabled, next/image is not usable because Cloudflare Pages lacks support, and both vercel/og and EditorJS are disabled due to next-on-pages build issues. Because this is an experimental app, it may contain bugs.