Bun + Svelte

A modern full-stack web application built with Bun runtime, Svelte 5 frontend, and Hono backend framework. Features a beautiful dark-themed UI with shadcn-svelte components, real-time health monitoring, and a fully typed TypeScript codebase.

Overview

This project is a modern full-stack application that combines:

• Bun - Fast JavaScript runtime, bundler, and package manager
• Svelte 5 - Modern reactive framework with runes ($state, $derived, etc.)
• Hono - Ultrafast web framework for the Edge
• Vite (Rolldown) - Next-generation frontend build tool
• shadcn-svelte - Beautiful, accessible component library
• Tailwind CSS - Utility-first CSS framework
• Lucide Icons - Beautiful icon library

Project Structure

.
├── client/                    # Svelte 5 client application
│   ├── src/
│   │   ├── App.svelte         # Main application component
│   │   ├── app.css            # Global styles with dark theme
│   │   └── lib/
│   │       ├── components/    # Reusable components
│   │       │   ├── ui/        # shadcn-svelte components
│   │       │   ├── HeaderCard.svelte
│   │       │   ├── TechStackSection.svelte
│   │       │   ├── FeaturesCard.svelte
│   │       │   ├── ProjectStructureCard.svelte
│   │       │   ├── QuickStartCard.svelte
│   │       │   └── HealthStatus.svelte
│   │       ├── Counter.svelte
│   │       └── utils.ts       # Utility functions
│   ├── vite.config.ts         # Vite configuration with API proxy
│   └── package.json
├── server/                     # Hono backend server
│   ├── api/                   # API route handlers
│   │   └── setup.ts           # Setup-related endpoints
│   ├── server.ts              # Main server file with CORS and routing
│   └── package.json
├── shared/                     # Shared TypeScript types
│   ├── src/
│   │   ├── api/               # API type definitions
│   │   │   └── setup.ts       # Setup API types
│   │   └── index.ts           # Main exports
│   └── package.json
├── index.ts                    # Bun server entry point
└── package.json                # Root package with workspace scripts

Tech Stack

Frontend

• Svelte 5 - Latest version with runes ($state, $derived, etc.)
• TypeScript - Type-safe development throughout
• Vite (Rolldown) - Fast build tool and dev server
• shadcn-svelte - Accessible component library
• Tailwind CSS - Utility-first styling
• Lucide Svelte - Icon components
• Tailwind Variants - Component variant management

Backend

• Bun - JavaScript runtime
• Hono - Web framework for API routes and static file serving

Features

• ⚡ Fast development with Bun and Vite
• 🎯 TypeScript support throughout
• 🚀 API endpoint at /api/health with detailed health information
• 📦 Static file serving from built frontend
• 🔥 Hot module replacement for frontend development
• 🎨 Modern dark theme with beautiful UI components
• 🧩 Modular component architecture
• 📊 Real-time health status monitoring
• 🔄 API proxy configuration for seamless development

Getting Started

Prerequisites

• Bun installed on your system

Installation

1. Clone the repository

2. Install all dependencies (workspaces are automatically handled):

   bun install
   

   This will automatically install dependencies for the root, client, and server workspaces.

3. Set up environment variables:

   cp .env.example .env
   

   Edit .env and configure the variables as needed (see Environment Variables section below).

Development

Run both client and server together:

bun run dev

Or run them separately:

Run the client development server:

bun run dev:client

Run the backend server:

bun run dev:server

• Frontend: Available at http://localhost:5173 (Vite dev server)
• Backend: Runs on http://localhost:3000
• API Proxy: Vite automatically proxies /api/* requests to the backend

Production Build

Build the client:

bun run build:client

Start the production server (serves the built frontend):

bun run start

The production server will serve the built frontend from dist (at the project root) and handle API routes.

Available Scripts

• dev - Start both client and server development servers together
• dev:client - Start client development server only
• dev:server - Start backend development server only
• build:client - Build client for production
• build - Alias for build:client
• start - Start production server

API Routes

Setup Endpoints

GET /api/health

Health check endpoint that returns server status and information.

Response:

{
  "status": "ok",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "runtime": "Bun",
  "framework": "Hono"
}

The frontend includes a HealthStatus component that automatically fetches and displays this information using typed API client functions.

Type Safety: Both server and client use shared TypeScript types from the shared workspace for type-safe API communication.

CORS Configuration

The API endpoints are protected with CORS middleware that:

• Development: Allows requests from localhost on any port for flexibility
• Production: Only allows requests from the CLIENT_URL specified in .env
• Supports credentials and standard HTTP methods (GET, POST, PUT, DELETE, OPTIONS)

UI Components

The application uses a modular component architecture with the following main components:

• HeaderCard - Main header with title, description, and counter
• TechStackSection - Displays technology stack cards
• FeaturesCard - Lists project features
• ProjectStructureCard - Visual project structure
• QuickStartCard - Quick start guide and documentation links
• HealthStatus - Real-time API health monitoring

All components use shadcn-svelte for consistent styling and accessibility.

Development Workflow

1. Installation: Run bun install to install all dependencies (workspaces are handled automatically)
2. Development: Run bun run dev to start both servers simultaneously
3. Hot Reload: Frontend changes are automatically reflected via Vite HMR
4. API Development: API routes are automatically proxied from Vite to the backend
5. Production: Build with bun run build:client, then start with bun run start

Environment Variables

The project uses a root .env file for environment configuration. Copy .env.example to .env and configure as needed:

# Server Configuration
PORT=3000
BUN_ENV=development

# Client Configuration (Vite only exposes VITE_ prefixed variables)
VITE_API_URL=http://localhost:3000
CLIENT_URL=http://localhost:5173

Available Variables

• PORT - Server port (default: 3000)
• BUN_ENV - Environment mode (development or production)
• VITE_API_URL - API URL for client-side requests (default: http://localhost:3000)
• CLIENT_URL - Client application URL

Note: Variables prefixed with VITE_ are exposed to the client. Never put sensitive data in VITE_ prefixed variables.

Theme

The application features a modern dark theme with:

• Rich color palette using OKLCH color space
• Smooth animations and transitions
• Glassmorphism effects
• Gradient backgrounds
• Responsive design for all screen sizes

Documentation & Resources

Framework Documentation

• Hono: Official Documentation | LLM-Friendly Full Docs
• Svelte 5: Official Documentation
• Bun: Official Documentation
• shadcn-svelte: Component Library

Project-Specific

• API Routes: See API Routes section above
• Component Architecture: See UI Components section above

License

This project is private and for personal/educational use.