fresh-bun

Single-page web app project template curated for performance, developer experience, and type safety.

🔧 Stack

• Bun - server runtime, package manager, script runner
• Elysia - server framework
• Eden - end-to-end type safety
• React - user interface
• TanStack Router - client-side routing
• TanStack Query, Zustand - state management
• TypeScript, Biome, Lefthook - code quality/style
• Vite - dev server, bundler

✨ Features

• 100% Type-Safe API: Full static type-safety between the server and client. See api.ts and useApi.ts for simple HTTP and WebSocket examples.

• Automatic API Documentation: Interactive Scalar documentation is automatically generated and served at /api/reference. The raw OpenAPI JSON is available at /api/reference/json.

• Progressive Web App Capable: Meets PWA requirements for an installable, native app-like experience. Scores a near-perfect PageSpeed Insights report out of the box.

• Offline Support: A service worker caches static assets and API responses, enabling offline functionality and faster subsequent loads with fewer requests to the server.

• Production Ready: Includes a multi-stage Dockerfile that compiles the app into a standalone binary and runs it in a minimal distroless image. Pre-configured GitHub workflows for continuous integration and deploying to fly.io on pushes to the main branch.

🚧 Scope

The following are not currently implemented, but may be added in the future:

• Server-Side Rendering (SSR) / React Server Components (RSC)
• Database / ORM
• Authentication / Authorization
• CSS Framework / UI Component Library
• Unit / E2E Tests
• Logging / Analytics

🚀 Getting Started

Setup

1. Install Git, Bun, and optionally Docker (useful for testing production builds locally)

2. Clone this repository and install dependencies:

git clone https://github.com/cdleveille/fresh-bun.git
cd fresh-bun
bun install

Local Development

Run the Elysia backend and Vite dev server concurrently:

bun dev

Production Build

Option 1: Bundle client and start server:

bun bundle
bun start

Option 2: Build app and run standalone binary:

bun run build
./bin/main

Option 3: Build Docker image and run in container:

docker build -t fresh-bun .
docker run -p 3000:3000 fresh-bun