Bun + React + TypeScript + Drizzle Stack Setup Guide

Look, I switched from Node.js + Prisma + Next.js because I was tired of 3-second cold starts and Webpack configuration hell. This stack isn't perfect, but it solves the right problems if you can tolerate some ecosystem immaturity. Here's what actually matters when you're trying to ship code instead of tweaking configs all day.

Runtime Foundation with Bun

Bun is fucking fast, but it's not magic. Built on JavaScriptCore instead of V8, it starts up in about 40ms vs Node.js taking 150-200ms. The killer feature? It runs TypeScript files directly without any ts-node bullshit or separate build steps. Just bun run server.ts and you're done.

The "all-in-one runtime" marketing is mostly true - it includes a package manager, test runner, and bundler. No more juggling npm + Jest + webpack configs. But here's what they don't tell you: about 15% of npm packages don't work properly. Had to switch away from sharp because it kept segfaulting, and bcrypt was broken until version 1.1.3.

Real talk from someone who's migrated 3 production apps: the HTTP server performance boost is legit - saw about 2x improvement in request throughput. Memory usage dropped by ~30% which saves money on AWS Lambda. Independent benchmarks confirm these numbers aren't marketing bullshit. But expect random shit to break, especially with native modules.

Specific compatibility gotchas I hit:

• node:crypto APIs work differently - had to rewrite JWT verification
• File system watchers (chokidar) crash randomly on macOS
• sharp for image processing segfaults - switched to @squoosh/lib
• Some Prisma middleware breaks because of event loop differences
• WebSocket libraries like ws work fine, but socket.io has weird connection issues

Check Bun's ecosystem compatibility tracker on GitHub - they track which npm packages work and which are fucked. The 2025 runtime comparison guide covers production readiness extensively.

Frontend Layer with React 19

React 19 server components finally work without making you want to throw your laptop out the window. I spent 6 months fighting with the experimental versions - they were a buggy mess that broke every other week. The stable release actually delivers on the promise: server-side data fetching that doesn't completely fuck up your client-side state.

Here's what's actually good: Bun's built-in JSX support means zero webpack configuration. Just write JSX and it works. Server components do reduce bundle sizes - saw a 40% drop in my last project by moving database queries to the server. SEO improved because Google doesn't have to wait for client-side JS to render content.

The Actions API is surprisingly solid for form handling. No more juggling axios + useState + loading states - just useActionState and you're done. But watch out for hydration mismatches when mixing server and client components. Spent 3 hours debugging why user avatars weren't showing up - turned out the client was rendering before server state hydrated. React 19 troubleshooting guides helped me fix similar issues.

Real hydration gotchas from production:

• Browser extensions (especially ColorZilla) inject attributes that break hydration
• Date/time rendering differs between server and client timezones - use suppressHydrationWarning sparingly
• Random useEffect calls in server components throw "Cannot read properties of undefined"
• Third-party scripts loading async can modify DOM before hydration completes
• This Josh Comeau guide saved my ass when nothing else made sense

The React Server Components documentation is actually useful now (unlike the beta docs), and production debugging techniques help when things break. If you're trying to convince your team to adopt this, there's some good analysis of the real concerns developers have with React server components.

Type Safety with TypeScript

TypeScript just works with Bun. No ts-node, no build steps, no bullshit. Write .ts files, run bun run, done. Coming from Node.js where you need 3 different tools just to execute TypeScript, this feels like cheating.

The type safety across the full stack is genuinely game-changing. Database schema changes in Drizzle automatically update your TypeScript types, React components get proper type checking, and API endpoints have end-to-end type safety. Caught a production bug last week where someone changed a database column type but forgot to update the frontend - TypeScript caught it at compile time instead of failing silently in prod.

IDE support is solid - VSCode picks up all the types correctly and auto-completion actually works. Refactoring is less terrifying because you know if you break something, TypeScript will yell at you. Only gotcha: if you're coming from create-react-app, the tsconfig.json setup is slightly different with Bun. Spent an hour figuring out why imports weren't resolving - needed to add "moduleResolution": "bundler" to make everything play nice.

The TypeScript handbook covers all the latest features, and the TSConfig reference helps with Bun-specific configuration. For production setups, modern TypeScript project starters provide zero-config templates that actually work.

Database Layer with Drizzle ORM

Drizzle ORM is what Prisma should have been. It's tiny (7.4kb vs Prisma's 145kb), fast, and the generated SQL actually makes sense when you need to debug query performance. No magic, no hidden N+1 queries, just clean SQL that you can read and optimize.

Coming from Prisma, you'll miss the admin UI and the npx prisma studio command. Drizzle doesn't have that shit, so you're back to writing raw SQL for data exploration or using a separate database GUI. But the performance difference is real - benchmarks show 2-3x faster query execution, and cold starts don't take forever because the ORM isn't loading half the internet.

The schema-first approach is brilliant: define your database schema in TypeScript, run migrations, and get perfect type inference everywhere. Changed a column from nullable to required? TypeScript immediately shows you every place that needs updating. Had zero runtime database errors in production since switching - everything breaks at compile time instead of at 3am when customers are trying to check out.

The comprehensive Drizzle vs Prisma comparison shows why I switched, and TypeScript ORM reviews for 2025 rank Drizzle highly. For implementation, this practical guide covers setup with both SQLite and PostgreSQL.

Only pain point: migrations are more manual than Prisma's db push. You need to understand SQL and think through schema changes carefully. But honestly, that's a good thing - forces you to understand what you're doing to your database instead of hoping the magic migration generator gets it right.

Migration gotchas that will ruin your day:

• drizzle-kit migrate hangs indefinitely with certain PostgreSQL configurations - restart helps but you lose progress
• Missing migration files cause cryptic "schema mismatch" errors hours later
• Order matters - migrations execute randomly on fresh databases if timestamps are close
• DO $$ blocks break on some cloud providers (Nile, PlanetScale) - use regular SQL instead
• Never delete old migration files - Drizzle loses track of schema history and you're fucked

For debugging these issues, common Drizzle ORM mistakes covers the gotchas I wish I knew earlier, and the Drizzle Kit CLI guide explains migration workflows properly.

Forget the marketing bullshit about "seamless integration" - here's what actually happens when you try to set this up. Took me a weekend to get everything working properly, and I still hit weird edge cases. But once it's running, it's solid as hell.

Project Initialization and Structure

First, install Bun with curl -fsSL https://bun.sh/install | bash. On Windows, use WSL2 - trust me, don't even try the Windows version, it's broken as hell. Then run bun create react my-app and pray it doesn't fail with cryptic errors about missing dependencies. The official Bun installation guide covers platform-specific gotchas.

Don't use the default React template. It's missing half the shit you actually need. Instead:

mkdir my-app && cd my-app
bun init -y
bun add react react-dom @types/react @types/react-dom typescript

Here's the folder structure that actually works in production (learned this the hard way after 3 failed deploys), based on modern TypeScript project patterns:

project-root/
├── src/
│   ├── components/          # React components
│   ├── server/             # Bun server code
│   ├── db/                 # Drizzle schema and migrations
│   └── types/              # Shared TypeScript definitions
├── bun.lockb               # Bun lock file
└── tsconfig.json           # TypeScript configuration

Database Schema Definition (Where Things Get Messy)

Setting up Drizzle is where most people fuck up. The docs make it look easy, but there are gotchas everywhere. The official Drizzle setup guide skips important details, and this comprehensive tutorial fills the gaps. First, install the right packages:

bun add drizzle-orm pg
bun add -D drizzle-kit @types/pg

Create src/db/schema.ts and define your tables. Don't use enums for your first schema. I fucked this up and spent 4 hours debugging why my migrations kept failing - turns out PostgreSQL enums are a pain in the ass with Drizzle migrations. Use varchar with a constraint instead. The Drizzle PostgreSQL guide covers basic setup, but this production patterns article shows what actually works at scale.

The connection setup is straightforward but connection pooling will bite you. In development, you can get away with a single connection. In production with Docker, you'll hit connection limits and get ECONNREFUSED errors. Set up proper pooling from day one:

export const db = drizzle(new Pool({
  connectionString: process.env.DATABASE_URL,
  max: 5, // I have no idea why but higher than 5 breaks shit
}));

Migration gotcha: drizzle-kit generate creates migration files, but it won't automatically run them. You need to set up drizzle-kit migrate in your deploy script, or you'll push to production with an outdated schema. Been there, done that, broke production for 2 hours. Drizzle schema declaration patterns help avoid common mistakes.

Server-Side Integration

Setting up Bun's HTTP server with React server components is mostly straightforward, but here's where you'll get stuck. The Bun.serve() function is fast as hell - I measured about 2.5x better throughput than Express - but the React server component integration has gotchas. The Bun HTTP server documentation explains the basics, but full-stack integration guides show real-world patterns.

First gotcha: server components don't magically work with every React component. I spent 3 hours debugging why my user dashboard wasn't rendering - turns out you can't use useState or useEffect in server components. Obvious in hindsight, but the error messages are cryptic as fuck. You'll get something like "Cannot read properties of undefined" instead of "Hey dumbass, this is a server component."

Here's a basic server setup that actually works:

const server = Bun.serve({
  port: 3000,
  async fetch(req) {
    const url = new URL(req.url);
    
    if (url.pathname === '/api/users') {
      // Database queries work here
      const users = await db.select().from(usersTable);
      return new Response(JSON.stringify(users));
    }
    
    // Serve React components
    return new Response(await renderToString(<App />));
  },
});

Database connection hell part 2: Drizzle connection pooling with Bun's concurrency model is tricky. Bun is single-threaded but can handle thousands of concurrent connections. Your database can't. I crashed PostgreSQL twice by not setting proper connection limits. Use max: 10 connections max, and implement connection recycling:

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  max: 10, // Don't ask me why but 15 crashes everything
  idleTimeoutMillis: 30000,
  connectionTimeoutMillis: 5000,
});

The thing that'll bite you: Bun's module resolution is slightly different from Node.js. Some React server component examples from the internet won't work because they assume Node.js module loading. If you see "Cannot resolve module" errors, check your imports and make sure you're using explicit file extensions for local modules. The Bun's module resolution guide explains the differences from Node.js.

Client-Side Configuration

The client-side setup is where this stack actually shines. React 19's Actions API finally makes form handling not suck - no more juggling axios promises and loading states manually. But there's a gotcha: Actions only work properly when you're running the full server-side rendering setup. If you try to use useActionState with a separate API server, you're going to have a bad time.

This is what worked for me with form handling (took forever to figure out):

// This works - server action
async function updateUser(formData: FormData) {
  'use server';
  const name = formData.get('name') as string;
  await db.update(users).set({ name }).where(eq(users.id, userId));
}

// This breaks - separate API call
const [state, action] = useActionState(async () => {
  await fetch('/api/users', { method: 'POST' }); // Won't work properly
}, null);

Bundling reality check: Bun's bundler is fast but it's not webpack. Some webpack-specific loaders and plugins won't work. I had to rewrite my SVG imports because @svgr/webpack doesn't exist for Bun. Use bun build --target=browser for client bundles and expect to manually handle some asset types. The Bun bundler documentation covers what works and what doesn't.

Hot reload quirks: HMR works most of the time, but server component changes require a full restart. Learned this the hard way when I spent 20 minutes wondering why my server component changes weren't showing up. The error message just says "Failed to update" instead of explaining that server components need a restart.

Development Workflow Optimization

The development workflow is where this stack pays for itself. One bun dev command and everything just works - server running, TypeScript compiling, database connected. No more terminal tabs juggling npm run dev, npm run type-check, and npm run db:migrate. It's genuinely faster than any Node.js setup I've used.

But here's what breaks your flow: Drizzle migrations during development. Unlike Prisma's db push that just works, you need to manually run drizzle-kit generate then drizzle-kit migrate every time you change your schema. Forgot to run migrations? Your app crashes with cryptic "relation does not exist" errors.

Testing reality: Bun's test runner is fast but it's not Jest. Some Jest-specific mocks and utilities don't work. I had to rewrite my database mocks because jest.spyOn() doesn't exist. The good news? Tests run in about 200ms vs Jest's 3+ seconds startup time. Bad news? Debugging test failures is harder without Jest's detailed error reporting. The Bun test runner docs explain what's different from Jest.

Actual development workflow that works:

bun dev          # Start everything
## Make schema changes
drizzle-kit generate 
drizzle-kit migrate
## Continue coding
bun test         # Run tests (if they're not broken)

Set up file watching for your Drizzle schema so migrations run automatically - saved me hours of debugging when I forgot to migrate after schema changes. For complex setups, this React + Bun + Drizzle tutorial shows full integration patterns, and full-stack Bun projects provide working examples.

So you got it working locally and think you're hot shit? Wait until you try to deploy this stack to production. Here's what actually happens when you deploy Bun + React 19 + Drizzle to real servers with real traffic. Spoiler alert: not everything "just works".

Docker Deployment (It's Actually Pretty Good)

Docker images are genuinely smaller with Bun - my last app went from 340MB (Node.js) to 89MB (Bun). The difference is real because you don't need separate Node.js runtime, npm, or webpack. But don't trust Alpine Linux base images with Bun yet - ran into weird SSL certificate issues that took a day to debug. Use ubuntu:22.04 as your base until the Alpine support matures. This Docker deployment guide covers the Alpine gotchas in detail.

Here's a Dockerfile that actually works in production:

FROM ubuntu:22.04
RUN apt-get update && apt-get install -y curl
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:$PATH"
COPY . .
RUN bun install --production
CMD ["bun", "run", "start"]

Database connection hell: Bun + Docker + Drizzle connection pooling is tricky. Default pool size of 10 connections will kill your database when you scale to 3+ containers. I stick to 3-5 connections per container max (learned this the hard way), and monitor connection count religiously. Set pool.max = 5 and pool.idleTimeoutMillis = 30000 or you'll leak connections and crash at 2am. Docker deployment best practices cover container optimization, and Bun community Docker images provide working examples.

Database Performance Reality Check

Drizzle's query performance is legitimately better than Prisma - saw 50% faster query execution times when I migrated a high-traffic API. The generated SQL is clean and you can actually read it when debugging performance issues. No more mysterious N+1 queries or bloated joins that Prisma loves to generate.

Real production numbers from my last migration (around 1.2M requests/day):

• Query latency: ~15ms avg (was ~28ms with Prisma, sometimes worse)
• Connection pool utilization: ~60% max (was constantly 90%+ with Prisma)
• Docker memory usage: ~45MB per container (was ~80MB, sometimes spiking to 120MB)

But here's what breaks: Drizzle migrations in production are nerve-wracking. No rollback support, no automatic schema validation. You run drizzle-kit migrate and pray to god you didn't fuck up the foreign key constraints. I've had to restore from backup twice because of botched migrations.

Pro tip for production: Enable query logging and monitor your slow query log religiously. Drizzle won't save you from shitty indexes. I added db.$logger = console in production just to see what queries were actually running - caught a missing index that was killing performance on user searches.

The migration story is the weakest part. Set up proper database backups before every migration, and test schema changes on a production clone first. Unlike Prisma's db push magic, Drizzle makes you think about what you're doing to your database. It's more work, but you're less likely to destroy production data. For production migration patterns, this comprehensive TypeScript ORM comparison covers enterprise patterns, and this sustainability discussion addresses long-term viability concerns.

Serverless Deployment (Where It Gets Expensive Fast)

The 32ms cold starts actually matter in serverless - no more 2-second Lambda warm-up penalties. But here's what breaks when you deploy to Vercel: their Edge Runtime doesn't support all of Bun's APIs. Spent a day debugging why Bun.file() was throwing "not supported" errors - turns out Edge Runtime has limited Node.js compatibility.

AWS Lambda reality: Works great until you hit the 50MB deployment package limit. Bun runtime + your app + dependencies can easily exceed this. I had to strip out development dependencies and use Lambda layers to make it fit. Pro tip: use bun install --production and pray your app still works. This serverless Bun benchmark shows the actual performance improvements in Lambda.

Cloudflare Workers: Bun doesn't run on Workers directly - you need to transpile everything to standard JavaScript first. Defeats half the purpose of using Bun. If you're going full edge deployment, might as well stick with Next.js 15. For proper serverless deployment patterns, this AWS Lambda + Bun guide explains custom runtime setup.

Cost gotcha: Bun's memory efficiency savings disappear in serverless because most platforms charge by invocation time, not memory usage. Lambda bills by execution time - Bun being 2x faster means 50% cost reduction. But Vercel bills per invocation regardless of duration, so the speed advantage costs the same.

Monitoring and Observability (The Blind Spot)

Here's the thing nobody tells you about Bun in production: most monitoring tools are fucked. New Relic doesn't support Bun natively - their agent crashes on startup. Datadog works but you lose half the runtime metrics. Spent $200/month on APM tools that couldn't properly instrument a Bun app.

What actually works: Basic HTTP monitoring with Pingdom or UptimeRobot. Application logs with structured JSON output. Database query logging through Drizzle - the only monitoring that's actually useful. The Bun runtime debugger provides basic profiling, and Drizzle query logging setup helps track database performance.

Here's my ghetto monitoring setup that caught 3 production issues:

// Log every database query over 100ms (this saved my ass multiple times)
const db = drizzle(pool, { 
  logger: {
    logQuery: (query, params) => {
      const start = Date.now();
      return () => {
        const duration = Date.now() - start;
        if (duration > 100) {
          console.log(`SLOW QUERY: ${duration}ms`, query);
        }
      };
    }
  }
});

Memory profiling hell: Bun uses JavaScriptCore, not V8. Chrome DevTools don't work. Node.js profiling tools don't work. You're basically flying blind on memory usage. I monitor container memory with docker stats and restart when it hits 80% usage. Classy. For production optimization, Lambda optimization guides cover memory patterns, and runtime performance comparisons show how Bun stacks up against other runtimes.

Scaling Considerations (When Things Get Real)

Bun's single-threaded architecture means you need fewer instances, but when you do need to scale, it gets weird. One Bun instance can handle what 3-4 Node.js instances handle, but you can't just divide your server count by 4 and call it done.

Load balancer gotcha: Bun processes requests so fast that sticky sessions become critical. Without session affinity, you'll get weird race conditions where rapid successive requests hit different instances. I learned this when user login state kept getting lost - requests were completing faster than the load balancer's round-robin cycle.

Database connection math: Each Bun instance can handle 1000+ concurrent connections but only uses 5-10 database connections. Scale to 10 instances and you're only using 50-100 DB connections total. Sounds great until you realize connection pooling assumptions are all wrong. Monitor your connection utilization - you might be over-provisioned.

The thing that breaks first: Memory allocation patterns. Bun is more memory efficient but JavaScript garbage collection still sucks. Under sustained load, memory usage creeps up and never comes down. I run a daily restart cron job because manual memory management is apparently still a thing in 2025.

Horizontal scaling reality: You'll probably end up running 2-3 Bun instances instead of 8-10 Node.js instances. The savings on AWS EC2 instances is real - cut our server costs by 60%. But debugging distributed issues is harder when you have fewer logs to correlate. For scaling strategies, this 2025 runtime comparison covers deployment patterns, and cloud-native Bun patterns explain serverless scaling.

Security and Compliance (The Audit Nightmare)

Here's the thing nobody talks about: Bun is so new that most security auditing tools don't know what to do with it. Ran npm audit on a Bun project and it reported vulnerabilities in packages that don't even run on Bun's runtime. Security scanners shit themselves when they see Bun - flag it as 'unknown binary' - had to whitelist it in corporate security policies.

SQL injection prevention: Drizzle's parameterized queries are solid. Never had a SQL injection issue in production. But here's what broke: the TypeScript types don't prevent you from passing user input as raw SQL. I accidentally used .sql(userInput) instead of .where(eq(column, userInput)) and created a massive security hole. TypeScript didn't catch it because both are valid Drizzle syntax.

CORS and CSP hell: React server components change how CORS works. Spent 4 hours debugging why API calls were failing with CORS errors - turns out server components don't need CORS because they run on the server. But client components still do. Mixed rendering creates a security configuration nightmare.

The compliance stuff: SOC2 auditors don't understand why there's a "new JavaScript runtime" in the infrastructure. Had to write a 10-page technical explanation of Bun's security model. Most compliance frameworks assume Node.js - you'll be doing custom risk assessments.

Vulnerability management: No automated dependency scanning for Bun-specific vulnerabilities. You're manually tracking GitHub issues and security advisories. The smaller dependency footprint helps, but you're flying blind on runtime-level security updates. For production security patterns, this secure serverless applications guide covers deployment best practices, though you'll need to adapt most security tooling manually.