⚡ FluxStack

The Revolutionary Full-Stack TypeScript Framework

Build modern web apps with Bun, Elysia, React, and Eden Treaty

Quick Start • Features • Documentation • Examples

✨ Key Features

🚀 Blazing Fast

• Bun Runtime - 3x faster than Node.js
• Elysia.js - High-performance backend
• Vite 7 - Lightning-fast HMR

🔒 Type-Safe Everything

• Eden Treaty - Automatic type inference
• End-to-End Types - Backend to frontend
• Zero Manual DTOs - Types flow naturally

🛠️ Zero Configuration

• One Command Setup - bunx create-fluxstack
• Hot Reload Built-in - Backend + Frontend
• Swagger Auto-Generated - API docs out of the box

🎯 Production Ready

• Docker Multi-Stage - Optimized containers
• Declarative Config - Environment management
• WebSocket Support - Real-time features

🚀 Quick Start

# Create a new FluxStack app
bunx create-fluxstack my-awesome-app
cd my-awesome-app
bun run dev

That's it! Your full-stack app is running at:

• 🌐 Frontend & Backend: http://localhost:3000
• 📚 API Documentation: http://localhost:3000/swagger
• ⚡ Hot Reload: Automatic on file changes

Alternative Installation

# Create in current directory
mkdir my-app && cd my-app
bunx create-fluxstack .
bun run dev

💎 What You Get

| Layer | Technology | Version | Why? | |-------|-----------|---------|------| | 🏃 Runtime | Bun | 1.2+ | 3x faster than Node.js | | ⚙️ Backend | Elysia.js | 1.4.6 | Ultra-fast API framework | | ⚛️ Frontend | React | 19.1 | Latest React features | | ⚡ Build Tool | Vite | 7.1.7 | Instant dev server | | 💅 Styling | Tailwind CSS | 4.1.13 | Utility-first CSS | | 📘 Language | TypeScript | 5.8.3 | Full type safety | | 🔌 API Client | Eden Treaty | 1.3.2 | Type-safe API calls |

• ✅ Automatic Type Inference - Eden Treaty connects backend types to frontend
• ✅ Coordinated Hot Reload - Backend and frontend reload independently
• ✅ Auto-Generated Swagger - API documentation updates automatically
• ✅ Docker Templates - Production-ready multi-stage builds included
• ✅ AI-Focused Docs - Special documentation for AI assistants (ai-context/)
• ✅ Declarative Config - Laravel-inspired configuration system
• ✅ WebSocket Support - Real-time features built-in
• ✅ Testing Setup - Vitest + React Testing Library ready

🏗️ Architecture Overview

graph TB
    subgraph "🎨 Frontend Layer"
        React[React 19 + Vite]
        Components[Components]
        Hooks[Custom Hooks]
    end

    subgraph "🔌 Communication Layer"
        Eden[Eden Treaty]
        WS[WebSockets]
    end

    subgraph "⚙️ Backend Layer"
        Elysia[Elysia.js]
        Routes[API Routes]
        Controllers[Controllers]
    end

    subgraph "🗄️ Data Layer"
        DB[(Your Database)]
        Cache[(Cache)]
    end

    React --> Eden
    Eden --> Elysia
    Elysia --> Routes
    Routes --> Controllers
    Controllers --> DB
    React --> WS
    WS --> Elysia

📁 Project Structure

FluxStack/
├── 🔒 core/                    # Framework Core (Read-Only)
│   ├── framework/             # FluxStack orchestrator
│   ├── plugins/               # Built-in plugins (Swagger, Vite, etc.)
│   ├── build/                 # Build system & Docker scaffolding
│   ├── cli/                   # CLI commands & generators
│   ├── config/                # Config schema helpers
│   └── utils/                 # Logging, environment, etc.
│
├── 👨‍💻 app/                     # Your Application Code
│   ├── server/                # Backend (Elysia + Bun)
│   │   ├── controllers/       # Business logic
│   │   ├── routes/            # API endpoints + schemas
│   │   ├── types/             # Shared types & App export
│   │   └── live/              # WebSocket components
│   │
│   ├── client/                # Frontend (React + Vite)
│   │   ├── src/
│   │   │   ├── components/    # React components
│   │   │   ├── hooks/         # Custom React hooks
│   │   │   ├── lib/           # Eden Treaty client
│   │   │   └── App.tsx        # Main app
│   │   └── public/            # Static assets
│   │
│   └── shared/                # Shared types & utilities
│
├── ⚙️ config/                  # Application Configuration
│   ├── app.config.ts          # App settings
│   ├── server.config.ts       # Server & CORS
│   ├── logger.config.ts       # Logging
│   └── database.config.ts     # Database
│
├── 🔌 plugins/                 # External Plugins
│   └── crypto-auth/           # Example: Crypto authentication
│
├── 🤖 ai-context/              # AI Assistant Documentation
│   ├── 00-QUICK-START.md      # Quick start for LLMs
│   ├── development/           # Development patterns
│   └── examples/              # Code examples
│
└── 📦 Package Files
    ├── package.json           # Dependencies
    ├── tsconfig.json          # TypeScript config
    └── README.md              # This file

📜 Available Scripts

🔨 Development

# Full-stack development
bun run dev

# Frontend only (port 5173)
bun run dev:frontend

# Backend only (port 3001)
bun run dev:backend

🚀 Production

# Build for production
bun run build

# Start production server
bun run start

🧪 Testing & Quality

# Run tests
bun run test

# Test with UI
bun run test:ui

# Type checking
bunx tsc --noEmit

🛠️ Utilities

# Sync version across files
bun run sync-version

# Run CLI commands
bun run cli

🔒 Type-Safe API Development

FluxStack uses Eden Treaty to eliminate manual DTOs and provide automatic type inference from backend to frontend.

📝 Define Backend Route

// app/server/routes/users.ts
import { Elysia, t } from 'elysia'

export const userRoutes = new Elysia({ prefix: '/users' })
  .get('/', () => ({
    users: listUsers()
  }))
  .post('/', ({ body }) => createUser(body), {
    body: t.Object({
      name: t.String(),
      email: t.String({ format: 'email' })
    }),
    response: t.Object({
      success: t.Boolean(),
      user: t.Optional(t.Object({
        id: t.Number(),
        name: t.String(),
        email: t.String(),
        createdAt: t.Date()
      })),
      message: t.Optional(t.String())
    })
  })

✨ Use in Frontend (Fully Typed!)

// app/client/src/App.tsx
import { api } from '@/app/client/src/lib/eden-api'

// ✅ TypeScript knows all types automatically!
const { data: response, error } = await api.users.post({
  name: 'Ada Lovelace',        // ✅ Type: string
  email: '[email protected]'     // ✅ Type: string (email format)
})

// ✅ response is typed as the exact response schema
if (!error && response?.user) {
  console.log(response.user.name)     // ✅ Type: string
  console.log(response.user.id)       // ✅ Type: number
  console.log(response.user.createdAt) // ✅ Type: Date
}

🎯 Benefits

• ✅ Zero Manual Types - Types flow automatically from backend to frontend
• ✅ Autocomplete - Full IntelliSense in your IDE
• ✅ Type Safety - Catch errors at compile time, not runtime
• ✅ Refactor Friendly - Change backend schema, frontend updates automatically

🎨 Customization Examples

// app/server/routes/posts.ts
import { Elysia, t } from 'elysia'

export const postRoutes = new Elysia({ prefix: '/posts' })
  .get('/', () => ({
    posts: getAllPosts()
  }))
  .post('/', ({ body }) => ({
    post: createPost(body)
  }), {
    body: t.Object({
      title: t.String({ minLength: 3 }),
      content: t.String({ minLength: 10 })
    })
  })

Then register it:

// app/server/index.ts
import { postRoutes } from './routes/posts'

app.use(postRoutes)

// app/server/plugins/audit.ts
import { Elysia } from 'elysia'

export const auditPlugin = new Elysia({ name: 'audit' })
  .derive(({ request }) => ({
    timestamp: Date.now(),
    ip: request.headers.get('x-forwarded-for')
  }))
  .onRequest(({ request, timestamp }) => {
    console.log(`[${new Date(timestamp).toISOString()}] ${request.method} ${request.url}`)
  })
  .onResponse(({ request, timestamp }) => {
    const duration = Date.now() - timestamp
    console.log(`[AUDIT] ${request.method} ${request.url} - ${duration}ms`)
  })

Use it:

import { auditPlugin } from './plugins/audit'

app.use(auditPlugin)

// config/features.config.ts
import { defineConfig, config } from '@/core/utils/config-schema'

const featuresConfigSchema = {
  enableAnalytics: config.boolean('ENABLE_ANALYTICS', false),
  maxUploadSize: config.number('MAX_UPLOAD_SIZE', 5242880), // 5MB
  allowedOrigins: config.array('ALLOWED_ORIGINS', ['http://localhost:3000'])
} as const

export const featuresConfig = defineConfig(featuresConfigSchema)

Use it with full type safety:

import { featuresConfig } from '@/config/features.config'

if (featuresConfig.enableAnalytics) {
  // Type: boolean (not string!)
  trackEvent('user_action')
}

📚 Documentation & Support

📖 Documentation

• AI Context Docs
• Quick Start Guide
• Development Patterns
• CLAUDE.md

💬 Community

• GitHub Issues
• Discussions
• Repository

🔄 Upgrading

bunx create-fluxstack@latest

# Check version
npm list -g create-fluxstack

🤔 Why FluxStack?

🆚 Comparison with Other Stacks

💡 Key Advantages

🚀 Performance

• 3x faster startup with Bun
• Ultra-fast API routing with Elysia
• Instant HMR with Vite 7
• Optimized production builds

🔒 Type Safety

• Automatic type inference
• Zero manual DTO definitions
• End-to-end type checking
• Refactor-friendly architecture

🛠️ Developer Experience

• Zero configuration needed
• One command to start
• Auto-generated documentation
• AI-optimized documentation

🎯 Production Ready

• Docker templates included
• Declarative configuration
• Unified error handling
• Built-in monitoring support

⚙️ Requirements

📦 System Requirements

• Bun ≥ 1.2.0 (required)
• Git (for version control)
• Modern OS: Linux, macOS, or Windows

📥 Install Bun

macOS / Linux:

curl -fsSL https://bun.sh/install | bash

Windows:

powershell -c "irm bun.sh/install.ps1 | iex"

⚠️ Important: FluxStack is designed exclusively for the Bun runtime. Node.js is not supported.

🚀 Ready to Build?

Start your next project in seconds

bunx create-fluxstack my-awesome-app
cd my-awesome-app
bun run dev

Welcome to the future of full-stack development 🎉

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with amazing open-source technologies:

• Bun - Fast all-in-one JavaScript runtime
• Elysia.js - Ergonomic framework for humans
• React - Library for web and native interfaces
• Vite - Next generation frontend tooling
• Tailwind CSS - Utility-first CSS framework
• TypeScript - JavaScript with syntax for types

Made with ❤️ by the FluxStack Team

Star ⭐ this repo if you find it helpful!

Report Bug · Request Feature · Contribute