Project Setup

The SavvySolve platform is built on Next.js 16 with Bun as the JavaScript runtime. This foundation provides fast development cycles, native TypeScript support, and modern React features through the App Router.

Why Bun?

Bun was chosen over Node.js for several practical reasons. It executes TypeScript natively without a separate compilation step, which eliminates an entire category of configuration complexity. Package installation is significantly faster, and the built-in test runner (which we'll use later) integrates cleanly with the rest of the toolchain.

For a platform where solver experience matters, these developer experience improvements translate directly to faster iteration and fewer frustrations.

Project Structure

The application follows Next.js App Router conventions with additional directories for server-side code and shared utilities:

savvysolve/
├── app/                    # Next.js App Router pages and layouts
│   ├── docs/              # Documentation routes (Fumadocs)
│   ├── layout.tsx         # Root layout with providers
│   ├── page.tsx           # Landing page
│   └── globals.css        # Global styles and Tailwind imports
├── content/
│   └── docs/              # MDX documentation files
├── lib/                   # Shared utilities and configurations
│   ├── source.ts          # Fumadocs content loader
│   └── utils.ts           # Common helpers (cn function)
├── server/                # Server-side code (tRPC routers, db)
├── components/            # React components
│   └── ui/                # shadcn/ui components
├── source.config.ts       # Fumadocs MDX configuration
├── next.config.ts         # Next.js configuration
├── tsconfig.json          # TypeScript configuration
└── package.json           # Dependencies and scripts

TypeScript Configuration

Type safety is enforced through strict compiler options. The configuration goes beyond the default strict: true to catch additional categories of bugs:

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "forceConsistentCasingInFileNames": true
  }
}

The noUncheckedIndexedAccess option is particularly valuable - it forces explicit handling of potentially undefined array and object accesses, preventing a common source of runtime errors.

Path aliases simplify imports throughout the codebase:

// Instead of relative paths like:
import { cn } from "../../../lib/utils";

// Use the alias:
import { cn } from "@/lib/utils";

Core Dependencies

The foundation includes the essential packages for building the tRPC-based API:

{
  "dependencies": {
    "@trpc/client": "^11.8.1",
    "@trpc/react-query": "^11.8.1", 
    "@trpc/server": "^11.8.1",
    "@tanstack/react-query": "^5.90.17",
    "superjson": "^2.2.6",
    "zod": "^4.3.5",
    "drizzle-orm": "^0.45.1",
    "@neondatabase/serverless": "^1.0.2"
  }
}

tRPC v11 provides end-to-end type safety between client and server without code generation. When you define a procedure on the server, TypeScript automatically knows the input and output types on the client.

Zod handles runtime validation - essential because TypeScript types disappear at runtime. Every tRPC procedure validates its inputs with Zod schemas, ensuring data integrity even when called from external sources.

Development Scripts

The project includes standard scripts for development workflow:

The typecheck script runs tsc --noEmit, which validates types without producing output files. This is used in CI to catch type errors before deployment.

Next.js Configuration

The Next.js configuration is minimal, focusing on strict type checking and MDX support for documentation:

import { createMDX } from "fumadocs-mdx/next";
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  reactStrictMode: true,
  typescript: {
    ignoreBuildErrors: false,
  },
};

const withMDX = createMDX();
export default withMDX(nextConfig);

Setting ignoreBuildErrors: false ensures that production builds fail if there are type errors - type safety is enforced at deploy time, not just during development.

Verification

To verify the setup is working correctly:

# Install dependencies
bun install

# Run type checking (should pass with no errors)
bun run typecheck

# Run linting (should pass)
bun run lint

# Start development server
bun run dev

The development server runs at http://localhost:3000 with Turbopack for fast refresh during development.