create-bun-stack

🎯 Quick Start

# Using bun create
bun create bun-stack

# Or using bunx/npx directly
bunx create-bun-stack

# Or from GitHub directly
bun create jasencarroll/create-bun-stack

🤔 Why create-bun-stack?

Missing that Rails feeling in modern JavaScript? We were too. So we built the generator that brings Rails-like productivity to the Bun ecosystem.

⚡ Bun + Rails Philosophy = Developer Happiness

• Convention over Configuration - Stop bikeshedding, start shipping
• Batteries Included - Auth, database, testing, styling - it's all there
• Zero Config - Works out of the box with sensible defaults
• Type Safety - Full TypeScript with proper types everywhere
• Lightning Fast - Powered by Bun's blazing fast runtime

📊 How It Compares

| Feature | create-bun-stack | create-react-app | Next.js | Vite | | --------------- | ---------------- | ---------------- | ------------- | ---------------- | | Fullstack | ✅ Built-in | ❌ Frontend only | ✅ API routes | ❌ Frontend only | | Database | ✅ Configured | ❌ DIY | ❌ DIY | ❌ DIY | | Auth | ✅ JWT ready | ❌ DIY | ❌ DIY | ❌ DIY | | Testing | ✅ Integrated | ✅ Jest | ✅ Jest | ✅ Vitest | | Type Safety | ✅ End-to-end | ⚠️ Frontend only | ✅ Good | ✅ Good | | Performance | 🚀 Bun speed | 🐌 Webpack | 🏃 Fast | 🏃 Fast | | Setup Time | ⚡ < 30s | 😴 2-3 min | 😴 1-2 min | ⚡ < 1 min |

✨ Features

🏗️ Fullstack Architecture

// API endpoint with type safety
export const users = {
  "/:id": {
    GET: async (req: Request & { params: { id: string } }) => {
      const user = await db.users.findById(req.params.id);
      return Response.json(user);
    }
  }
};

// React component with data fetching
function UserProfile({ id }: { id: string }) {
  const { data: user } = useQuery({
    queryKey: ['user', id],
    queryFn: () => fetch(`/api/users/${id}`).then(r => r.json())
  });

  return <div>Welcome, {user?.name}!</div>;
}

🔐 Authentication Built-in

// Register a new user
const { token, user } = await auth.register({
  email: "[email protected]",
  password: "secure123",
});

// Protected routes just work
const protectedRoute = withAuth(async (req, user) => {
  return Response.json({ message: `Hello ${user.name}!` });
});

🗄️ Dual Database Support

// Works with PostgreSQL in production
DATABASE_URL = "postgresql://...";

// Falls back to SQLite for local dev
// Just works - no config needed!

🧪 Testing That Actually Works

// Real integration tests, no mocks needed
test("creates a user", async () => {
  const response = await fetch("http://localhost:3000/api/users", {
    method: "POST",
    body: JSON.stringify({ name: "Test User" }),
  });

  expect(response.status).toBe(201);
});

🛡️ Security First

• ✅ CSRF Protection
• ✅ Secure Headers (CSP, HSTS, etc.)
• ✅ Input Validation with Zod
• ✅ SQL Injection Protection via Drizzle ORM
• ✅ Bcrypt Password Hashing

🎨 Modern Frontend Stack

• React 18 with Suspense & Error Boundaries
• React Router for client-side routing
• Tailwind CSS for styling
• React Query for server state
• TypeScript everywhere

🚀 Developer Experience

• Hot Reload - See changes instantly
• Type Safety - Catch errors at compile time
• File-based Routing - Intuitive API structure
• Auto-imports - Bun handles your imports
• Built-in Formatter - Prettier & Biome configured

📦 What's Included

my-app/
├── src/
│   ├── app/           # React frontend
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── pages/
│   │   └── main.tsx
│   ├── server/        # Bun backend
│   │   ├── routes/
│   │   ├── middleware/
│   │   └── index.ts
│   ├── db/            # Database layer
│   │   ├── schema.ts
│   │   ├── seed.ts
│   │   └── repositories/
│   └── lib/           # Shared utilities
├── public/            # Static assets
├── tests/             # Test files
└── package.json       # One file to rule them all

🚦 Commands

bun run dev        # Start development server
bun test          # Run tests
bun run build     # Build for production
bun run db:push   # Sync database schema
bun run db:seed   # Seed database
bun run check     # Type check, lint, format

🌍 Deployment

Deploy anywhere Bun runs:

• Railway - One click deploy
• Fly.io - Edge deployments
• Docker - Containerize with Bun's official image
• VPS - Any Linux server with Bun installed

FROM oven/bun:1
COPY . .
RUN bun install
EXPOSE 3000
CMD ["bun", "run", "src/server/index.ts"]

🤝 Contributing

We love contributions! Check out our Contributing Guide to get started.

# Fork and clone
git clone https://github.com/yourusername/create-bun-stack
cd create-bun-app

# Install dependencies
bun install

# Make your changes
bun run test

# Submit a PR!

📚 Documentation

• CLAUDE.md - Implementation details

🐛 Troubleshooting

# Kill the process using port 3000
lsof -ti:3000 | xargs kill -9

# Or use a different port
PORT=3001 bun run dev

# For PostgreSQL issues
psql -U postgres -c "CREATE DATABASE myapp_dev;"

# Or just use SQLite (automatic fallback)
rm .env  # Remove DATABASE_URL
bun run dev

Make sure your server is running:

# In one terminal
bun run dev

# In another terminal
bun test

🔓 Open-Sourced Leverage

Bun Stack is more than a fullstack starter — it's everything you'd build if you had the time.

• ✅ Security defaults (CSRF, JWT, password hashing)
• ✅ End-to-end TypeScript
• ✅ Auth, routing, DB, CI/CD
• ✅ Docker + 1-click Railway deploy
• ✅ Convention-driven structure No yak shaving. No config hell. No architecture debates.

Just code. Just ship.

Built by Jasen

Engineer. Systems thinker. MBA. ADHD-fueled DX evangelist. I built Bun Stack to democratize the leverage that took me 15 years to earn. Now it’s yours. Just ship.

📄 License

MIT © Jasen Carroll