Tech Stack
A deep dive into the technologies powering MuseMVP and why we chose them.
This page covers every core technology used in MuseMVP, along with the reasoning behind each choice. Every entry links to its official documentation so you can dive deeper whenever needed.
Next.js & React
Next.js 16 is one of the most mature React full-stack frameworks available, offering App Router, Server Components, and streaming rendering. We use Next.js to serve both the frontend and the backend API entry point (via a Hono bridge route). React 19 brings improved Server Actions and concurrency features that further reduce client-side JavaScript bundle size. The repo is typed with TypeScript 7. package.json engines.node is >=22.
Hono & TanStack Query
Hono is a lightweight, ultra-fast, edge-friendly web framework. Its built-in RPC client enables end-to-end type-safe function calls from the frontend. We mount the Hono app inside Next.js's app/api/[[...rest]] route, letting the frontend and backend coexist in the same repository.
TanStack Query handles data fetching, caching, and state synchronization on the client side. Paired with the Hono RPC client, it dramatically simplifies async data management logic.
Better Auth
Better Auth is a modern authentication library built for full-stack apps. It exposes ready-to-use auth flows and a plugin-based extension system. MuseMVP activates multiple plugins on top of Better Auth to cover everything from basic login to advanced security:
- Email + password login / Email OTP verification code login
- Google & GitHub OAuth social login
- TOTP-based two-factor authentication (2FA)
- Admin role plugin
- Cloudflare Turnstile bot protection
Drizzle ORM & D1
Drizzle ORM provides typed queries for D1 / SQLite through the Worker DB binding. The application binds shared queries to packages/db/src/schema-d1.ts and its migration history.
Tailwind CSS & UI Components
Tailwind CSS v4 is a utility-first CSS framework that forms the foundation of our design system. We pair it with shadcn/ui (accessible headless components built on Radix Primitives) and Motion (formerly Framer Motion) for animations.
All theme colors are managed through CSS variables, so switching themes or updating brand colors requires no changes to component code.
Forms & Validation
React Hook Form provides performance-first uncontrolled form management. Zod handles schema declaration and runtime data validation. The two are deeply integrated across MuseMVP, ensuring all user input is validated on both the client and server side with full type safety.
Payments: Stripe, Creem, Dodo, and Waffo
Stripe is the most widely adopted SaaS payment solution globally. Creem is a developer-friendly alternative that doesn't require a US entity—ideal for indie makers. Dodo Payments and Waffo Pancake are additional hosted-checkout options. MuseMVP ships webhook and callback handling for all four gateways. The unified Muse Billing module abstracts the pricing strategy layer so you can swap payment providers without touching business logic.
CMS: Fumadocs MDX
Fumadocs and Fumadocs MDX compile each app’s docs, blog, legal, and changelog sources. Schemas live in app source.config.ts; edit source MDX, not .source/. The current default body has no legacy ProContent paywall overlay.
Internationalization: next-intl
next-intl provides a complete i18n solution for the Next.js App Router, covering routing, message translation, and locale-aware formatting. Every surface in MuseMVP—landing pages, dashboards, docs, and blogs—supports seamless multi-language switching.
Cloudflare Email Sending handles production delivery. Shared React Email templates live in packages/mail/src/templates.
Object Storage
Native R2 uses R2_BUCKET. Avatar and asset access goes through same-origin /files/avatars/* with session and ownership checks.
Analytics
MuseMVP simultaneously integrates Google Analytics (GA4) and Baidu Tongji, connected through a unified useAnalytics hook that sends custom tracking events to both platforms in a single call. Ideal for products targeting both international and Chinese markets.
Route Layers
| Path | Responsibility |
|---|---|
apps/web-cloudflare/src/app/(landing-page)/[locale] | Landing pages composed sequentially in each route file, plus blog, docs, and other marketing/CMS routes |
apps/web-cloudflare/src/app/(saas-page)/app | Authenticated app dashboard and user-facing console |
apps/web-cloudflare/src/app/api/[[...rest]]/route.ts | Next.js → Hono API bridge entry point |
apps/web-cloudflare/src/backend/api/app.ts | Hono router registration and middleware composition |
Module Boundaries
| Directory | Responsibility |
|---|---|
apps/web-cloudflare/src/modules/* | Feature-scoped business modules (UI + logic) |
apps/web-cloudflare/src/backend/* | Hono routes, API client, and app database wrappers |
packages/config | Runtime config: auth, billing, theme, contact delivery |
apps/web-cloudflare/content/docs / apps/web-cloudflare/content/posts | MDX content sources (docs and blog) |
Data & Request Flow
UI components in apps/web-cloudflare/src/modules trigger a user action
React Query hooks in apps/web-cloudflare/src/backend/api-client issue a Hono RPC call
The request enters the corresponding Hono router in apps/web-cloudflare/src/backend/api/routes
The service layer (e.g. muse-billing/lib/orchestrator.ts) or query layer (packages/db/src/queries) handles business logic
The response returns, React Query updates its cache, and the UI re-renders automatically
Quick Reference
| Technology | Docs |
|---|---|
| Next.js | nextjs.org/docs |
| React | react.dev |
| Hono | hono.dev/docs |
| TanStack Query | tanstack.com/query/latest/docs |
| Better Auth | better-auth.com/docs |
| Drizzle ORM | orm.drizzle.team/docs |
| Tailwind CSS | tailwindcss.com/docs |
| shadcn/ui | ui.shadcn.com/docs |
| Radix UI | radix-ui.com/primitives/docs |
| Zod | zod.dev |
| React Hook Form | react-hook-form.com/docs |
| Stripe | stripe.com/docs |
| Creem | creem.io/docs |
| Dodo Payments | docs.dodopayments.com |
| Waffo Pancake | docs.waffo.ai |
| Fumadocs | fumadocs.dev/docs |
| Fumadocs MDX | fumadocs.dev/docs |
| next-intl | next-intl.dev/docs |
| React Email | react.email/docs |
| Motion | framer.com/motion |
Testing and Workspace
Node 22.x, pnpm 10.26.2, Biome, Vitest, and Playwright. Shared logic lives in packages; pages remain full copies checked with pnpm apps:parity. See Testing. Passkey/WebAuthn is not enabled; library capabilities are not automatically template features.