diff --git a/README.md b/README.md index 7a2700c..d4a2616 100644 --- a/README.md +++ b/README.md @@ -1,94 +1,425 @@ -# FluxStack +
-Full-stack TypeScript framework built on Bun, Elysia.js, and React with end-to-end type safety via Eden Treaty. +# ⚡ FluxStack + +### The Full-Stack TypeScript Framework for Real-Time Apps + +*Build modern web apps with Bun, Elysia, React, and Eden Treaty* [![npm version](https://badge.fury.io/js/create-fluxstack.svg)](https://www.npmjs.com/package/create-fluxstack) -[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) +[![Bun](https://img.shields.io/badge/Bun-%23000000.svg?style=flat&logo=bun&logoColor=white)](https://bun.sh) +[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/) +[![React](https://img.shields.io/badge/React-20232A?style=flat&logo=react&logoColor=61DAFB)](https://reactjs.org/) + +[Quick Start](#-quick-start) • [Features](#-key-features) • [Live Components](#-live-components) • [Documentation](#-documentation--support) + +
+ +--- + +## ✨ 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 -## Quick Start +
+ +### ⚡ **Live Components** +- **WebSocket Sync** - Real-time state synchronization +- **Reactive Proxy** - `this.state.count++` auto-syncs +- **Room System** - Multi-room real-time communication + + + +### 🎯 **Production Ready** +- **Docker Multi-Stage** - Optimized containers +- **Declarative Config** - Laravel-inspired config system +- **Plugin Security** - Whitelist-based NPM plugin safety + +
+ +--- + +## 🚀 Quick Start ```bash -bunx create-fluxstack my-app -cd my-app +# Create a new FluxStack app +bunx create-fluxstack my-awesome-app +cd my-awesome-app bun run dev ``` -This starts the full-stack dev server: +**That's it!** Your full-stack app is running: -| Service | URL | -| ---------------- | ---------------------------- | -| Backend API | http://localhost:3000 | -| Frontend (Vite) | http://localhost:5173 | -| Swagger Docs | http://localhost:3000/swagger | -| Health Check | http://localhost:3000/api/health | +| Service | URL | +|---------|-----| +| 🌐 **Frontend** | http://localhost:5173 | +| ⚙️ **Backend API** | http://localhost:3000 | +| 📚 **Swagger Docs** | http://localhost:3000/swagger | +| 🩺 **Health Check** | http://localhost:3000/api/health | -### Alternative: scaffold in current directory +### Alternative Installation ```bash +# Create in current directory mkdir my-app && cd my-app bunx create-fluxstack . bun run dev ``` -## Tech Stack +--- + +## 💎 Tech Stack + + + + + + + + + + + + +
+
+Bun +
Runtime
+Bun >= 1.2 +

+		 +
+Elysia +
Backend
+Elysia.js 1.4 +

+		 +
+React +
Frontend
+React 19 +

+		 +
+Vite +
Build
+Vite 7 +

+		 +
+Tailwind +
Styling
+Tailwind CSS 4 +

+		 +
+TypeScript +
Language
+TypeScript 5.8 +

+		 +
+Eden Treaty +
API Client
+Eden Treaty 1.3 +

+		 +
+Vitest +
Testing
+Vitest 3 +

+
+ +--- + +## 🏗️ Architecture Overview + +
+ +```mermaid +graph TB + subgraph "🎨 Frontend Layer" + React[React 19 + Vite] + LiveClient[Live Components Client] + Eden[Eden Treaty] + end + + subgraph "🔌 Communication" + HTTP[HTTP / REST] + WS[WebSocket] + end + + subgraph "⚙️ Backend Layer" + Elysia[Elysia.js] + Routes[API Routes] + LiveServer[Live Components Server] + Rooms[Room System] + end + + React --> Eden + Eden --> HTTP + HTTP --> Elysia + Elysia --> Routes + LiveClient --> WS + WS --> LiveServer + LiveServer --> Rooms +``` -| Component | Technology | Version | -| ------------ | --------------------- | ------- | -| Runtime | [Bun](https://bun.sh) | >= 1.2 | -| Backend | [Elysia.js](https://elysiajs.com) | 1.4 | -| Frontend | [React](https://react.dev) | 19 | -| Build | [Vite](https://vite.dev) | 7 | -| Styling | [Tailwind CSS](https://tailwindcss.com) | 4 | -| Language | [TypeScript](https://www.typescriptlang.org) | 5.8 | -| API Client | [Eden Treaty](https://elysiajs.com/eden/overview) | 1.3 | -| Testing | [Vitest](https://vitest.dev) | 3 | +
-## Project Structure +### 📁 Project Structure -``` +
+Click to expand directory structure + +```bash FluxStack/ -├── core/ # Framework internals (read-only) -│ ├── framework/ # Server/client orchestration -│ ├── server/ # Elysia plugins, middleware, live components -│ ├── client/ # Vite integration -│ ├── cli/ # CLI commands & generators -│ ├── plugins/ # Built-in plugin system -│ ├── types/ # Framework type definitions -│ └── utils/ # Logger, config schema, errors +├── 🔒 core/ # Framework Core (Read-Only) +│ ├── framework/ # FluxStack orchestrator +│ ├── server/ # Elysia plugins, middleware, live engine +│ ├── client/ # Vite integration, Live hooks, providers +│ ├── cli/ # CLI commands & generators +│ ├── plugins/ # Built-in plugins (Swagger, Vite, etc.) +│ ├── types/ # Framework type definitions +│ └── utils/ # Logger, config schema, errors │ -├── app/ # Application code -│ ├── server/ # Backend -│ │ ├── controllers/ # Business logic -│ │ ├── routes/ # API endpoints -│ │ ├── live/ # Live Components (WebSocket) -│ │ └── app.ts # Elysia app instance (Eden Treaty export) -│ ├── client/ # Frontend (React + Vite) +├── 👨‍💻 app/ # Your Application Code +│ ├── server/ # Backend (Elysia + Bun) +│ │ ├── controllers/ # Business logic +│ │ ├── routes/ # API endpoints + schemas +│ │ ├── live/ # Live Components (server-side) +│ │ └── app.ts # Elysia app instance (Eden Treaty export) +│ │ +│ ├── client/ # Frontend (React + Vite) │ │ └── src/ -│ │ ├── components/ -│ │ ├── pages/ -│ │ ├── live/ # Client-side Live Components -│ │ └── lib/ # Eden Treaty client -│ └── shared/ # Shared type definitions +│ │ ├── components/ # React components +│ │ ├── pages/ # Route pages +│ │ ├── live/ # Live Components (client-side) +│ │ └── lib/ # Eden Treaty client +│ │ +│ └── shared/ # Shared type definitions │ -├── config/ # Declarative configuration -│ ├── system/ # Config files (app, server, db, logger, etc.) -│ ├── fluxstack.config.ts -│ └── index.ts +├── ⚙️ config/ # Declarative Configuration +│ ├── system/ # Config files (app, server, db, logger, etc.) +│ ├── fluxstack.config.ts # FluxStack config +│ └── index.ts # Centralized exports │ -├── plugins/ # Project plugins (auto-discovered) -├── tests/ # Test suite (unit + integration) -├── LLMD/ # LLM-optimized documentation -├── Dockerfile # Multi-stage production build -└── package.json +├── 🔌 plugins/ # Project Plugins (auto-discovered) +├── 🧪 tests/ # Test suite (unit + integration) +├── 🤖 LLMD/ # LLM-Optimized Documentation +└── 🐳 Dockerfile # Multi-stage production build ``` -## Features +
-### End-to-End Type Safety +--- -Eden Treaty infers types from Elysia route definitions automatically. No manual DTOs. +## ⚡ Live Components -**Define a route on the backend:** +Real-time WebSocket components with **automatic state synchronization** between server and client. Define state and logic on the server, interact with it from React — updates sync instantly via WebSocket. + + + + + + +
+ +### 🖥️ Server Side + +```typescript +// app/server/live/LiveCounter.ts +import { LiveComponent } from '@/core/server' + +export class LiveCounter extends LiveComponent<{ + count: number +}> { + static defaultState = { count: 0 } + + async increment() { + this.state.count++ // auto-syncs via Proxy + return { success: true } + } + + async decrement() { + this.state.count-- + return { success: true } + } + + async reset() { + this.state.count = 0 + return { success: true } + } +} +``` + + + +### ⚛️ Client Side + +```tsx +// app/client/src/live/CounterDemo.tsx +import { Live } from '@/core/client' +import { LiveCounter } from '@server/live/LiveCounter' + +export function CounterDemo() { + const counter = Live.use(LiveCounter, { + room: 'global-counter', + initialState: LiveCounter.defaultState + }) + + return ( +
+ {counter.$state.count} + + + + + + + {counter.$connected ? '🟢' : '🔴'} + +
+ ) +} +``` + +
+ +### 🔑 Client Proxy API + +The `Live.use()` hook returns a Proxy object with full access to server state and actions: + +```typescript +const component = Live.use(MyComponent) + +// State access +component.$state // Full state object +component.myProp // Direct property access via Proxy +component.$connected // Boolean - WebSocket connected? +component.$loading // Boolean - action in progress? +component.$error // Error message or null + +// Actions +await component.myAction() // Call server method (type-safe) +component.$set('key', val) // Set a single property + +// Form field binding + + +await component.$sync() // Manual sync for deferred fields + +// Room events +component.$room.emit('event', data) +component.$room.on('message', handler) +``` + +### 🏠 Room System + +Multi-room real-time communication for Live Components — users in the same room share events. + + + + + + +
+ +**Server: join rooms and emit events** + +```typescript +// app/server/live/ChatRoom.ts +export class ChatRoom extends LiveComponent { + + async joinRoom(payload: { roomId: string }) { + this.$room(payload.roomId).join() + + this.$room(payload.roomId).on('message:new', (msg) => { + this.setState({ + messages: [...this.state.messages, msg] + }) + }) + + return { success: true } + } + + async sendMessage(payload: { text: string }) { + const message = { id: Date.now(), text: payload.text } + this.setState({ + messages: [...this.state.messages, message] + }) + this.$room('chat').emit('message:new', message) + return { success: true } + } +} +``` + + + +**HTTP API for external integrations** + +```bash +# Send a message to a room via API +curl -X POST \ + http://localhost:3000/api/rooms/general/messages \ + -H "Content-Type: application/json" \ + -d '{"user": "Bot", "text": "Hello from API!"}' + +# Emit a custom event to a room +curl -X POST \ + http://localhost:3000/api/rooms/tech/emit \ + -H "Content-Type: application/json" \ + -d '{ + "event": "notification", + "data": {"type": "alert", "msg": "Deploy done!"} + }' +``` + +Rooms are accessible both from Live Components (WebSocket) and via REST API for webhooks, bots, and external services. + +
+ +--- + +## 🔒 Type-Safe API Development + +**Eden Treaty infers types from Elysia route definitions automatically. No manual DTOs.** + + + + + + +
+ +### 📝 Define Backend Route ```typescript // app/server/routes/users.routes.ts @@ -111,65 +442,41 @@ export const userRoutes = new Elysia({ prefix: '/users' }) }) ``` -**Use it on the frontend with full type inference:** + + +### ✨ Use in Frontend (Fully Typed!) ```typescript // app/client/src/lib/eden-api.ts import { api } from './eden-api' +// TypeScript knows all types automatically! const { data, error } = await api.users.post({ - name: 'Ada Lovelace', // string - email: 'ada@example.com' // string (email) + name: 'Ada Lovelace', // ✅ string + email: 'ada@example.com' // ✅ string (email) }) if (data?.user) { - console.log(data.user.name) // string - fully typed + console.log(data.user.name) // ✅ string + console.log(data.user.id) // ✅ number } ``` -### Live Components - -Real-time WebSocket components with automatic state synchronization between server and client. +
-```typescript -// app/server/live/LiveCounter.ts -export class LiveCounter extends LiveComponent<{ count: number }> { - static defaultState = { count: 0 } +**Benefits:** +- ✅ **Zero Manual Types** — Types flow automatically from backend to frontend +- ✅ **Full Autocomplete** — IntelliSense in your IDE +- ✅ **Refactor Friendly** — Change backend schema, frontend updates automatically - async increment() { - this.state.count++ // auto-syncs to frontend via Proxy - return { success: true } - } -} -``` +--- -### Room System +## ⚙️ Declarative Configuration -Multi-room real-time communication for Live Components. - -```typescript -// Join a room and listen for events -this.$room('chat-room').join() -this.$room('chat-room').on('message:new', (msg) => { - this.setState({ messages: [...this.state.messages, msg] }) -}) - -// Emit to all other users in the room -this.$room('chat-room').emit('message:new', message) -``` - -Rooms are also accessible via HTTP for external integrations: - -```bash -# Send a message to a room -curl -X POST http://localhost:3000/api/rooms/general/messages \ - -H "Content-Type: application/json" \ - -d '{"user": "Bot", "text": "Hello from API!"}' -``` - -### Declarative Configuration - -Laravel-inspired config system with schema validation and type inference. +Laravel-inspired config system with schema validation and full type inference. ```typescript // config/system/app.config.ts @@ -183,65 +490,102 @@ const appConfigSchema = { } as const export const appConfig = defineConfig(appConfigSchema) +// appConfig.port → number, appConfig.env → "development" | "production" | "test" ``` All environment variables are validated at boot time. See [`.env.example`](.env.example) for available options. -### Plugin System +--- + +## 🔌 Plugin System Three-layer plugin architecture with security-first design: -| Layer | Location | Auto-discovered | Trusted by default | -| -------------- | ----------------- | --------------- | ------------------ | -| Built-in | `core/plugins/` | No (manual) | Yes | -| Project | `plugins/` | Yes | Yes | -| NPM | `node_modules/` | No (opt-in) | No (whitelist) | +| Layer | Location | Auto-discovered | Trusted | +|-------|----------|-----------------|---------| +| 🔒 **Built-in** | `core/plugins/` | No (manual `.use()`) | ✅ Yes | +| 📁 **Project** | `plugins/` | ✅ Yes | ✅ Yes | +| 📦 **NPM** | `node_modules/` | ❌ No (opt-in) | 🔒 Whitelist required | -NPM plugins are blocked by default. To add one: +NPM plugins are **blocked by default**. To add one safely: ```bash bun run cli plugin:add fluxstack-plugin-auth +# Audits the package, installs it, and adds it to the whitelist +``` + +--- + +## 📜 Available Scripts + + + + + + + + + + +
+ +### 🔨 Development + +```bash +bun run dev # Full-stack with hot reload +bun run dev:frontend # Frontend only (port 5173) +bun run dev:backend # Backend only (port 3001) ``` -This audits the package, installs it, and adds it to the whitelist. + -## Scripts +### 🚀 Production ```bash -# Development -bun run dev # Full-stack with hot reload -bun run dev:frontend # Frontend only (port 5173) -bun run dev:backend # Backend only (port 3001) - -# Build & Production -bun run build # Production build -bun run start # Start production server - -# Testing & Quality -bun run test # Run tests (Vitest) -bun run test:ui # Vitest with browser UI -bun run test:coverage # Coverage report -bun run typecheck:api # Strict TypeScript check - -# CLI & Generation -bun run cli # CLI interface -bun run make:component # Generate a Live Component -bun run sync-version # Sync version across files +bun run build # Production build +bun run start # Start production server ``` -## Frontend Routes +
+ +### 🧪 Testing & Quality + +```bash +bun run test # Run tests (Vitest) +bun run test:ui # Vitest with browser UI +bun run test:coverage # Coverage report +bun run typecheck:api # Strict TypeScript check +``` + + + +### 🛠️ CLI & Utilities + +```bash +bun run cli # CLI interface +bun run make:component # Generate a Live Component +bun run sync-version # Sync version across files +``` + +
+ +--- + +## 🔀 Frontend Routes Default routes included in the demo app (React Router v7): -| Route | Page | -| ------------- | ----------------- | -| `/` | Home | -| `/counter` | Live Counter | -| `/form` | Live Form | -| `/upload` | Live Upload | -| `/api-test` | Eden Treaty Demo | +| Route | Page | +|-------|------| +| `/` | Home | +| `/counter` | Live Counter | +| `/form` | Live Form | +| `/upload` | Live Upload | +| `/api-test` | Eden Treaty Demo | + +--- -## Environment Variables +## 🔧 Environment Variables Copy `.env.example` to `.env` and adjust as needed: @@ -249,22 +593,27 @@ Copy `.env.example` to `.env` and adjust as needed: cp .env.example .env ``` -Key variables: +
+Key variables -| Variable | Default | Description | -| ------------------ | ---------------- | ------------------------ | -| `PORT` | `3000` | Backend server port | -| `HOST` | `localhost` | Server host | -| `FRONTEND_PORT` | `5173` | Vite dev server port | -| `NODE_ENV` | `development` | Environment | -| `LOG_LEVEL` | `info` | Logging level | -| `CORS_ORIGINS` | `localhost:3000,localhost:5173` | Allowed CORS origins | -| `SWAGGER_ENABLED` | `true` | Enable Swagger UI | -| `SWAGGER_PATH` | `/swagger` | Swagger UI path | +| Variable | Default | Description | +|----------|---------|-------------| +| `PORT` | `3000` | Backend server port | +| `HOST` | `localhost` | Server host | +| `FRONTEND_PORT` | `5173` | Vite dev server port | +| `NODE_ENV` | `development` | Environment | +| `LOG_LEVEL` | `info` | Logging level | +| `CORS_ORIGINS` | `localhost:3000,localhost:5173` | Allowed CORS origins | +| `SWAGGER_ENABLED` | `true` | Enable Swagger UI | +| `SWAGGER_PATH` | `/swagger` | Swagger UI path | See [`.env.example`](.env.example) for the full list. -## Docker +
+ +--- + +## 🐳 Docker ```bash # Build @@ -274,33 +623,137 @@ docker build -t fluxstack-app . docker run -p 3000:3000 fluxstack-app ``` -The Dockerfile uses a multi-stage build (dependencies -> build -> production) with `oven/bun:1.2-alpine` and runs as a non-root user. - -## Requirements - -- **Bun >= 1.2.0** (required runtime) - -Install Bun: - +The Dockerfile uses a multi-stage build with `oven/bun:1.2-alpine` and runs as a non-root user. + +--- + +## 🤔 Why FluxStack? + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FeatureFluxStackNext.jsT3 Stack
Runtime✅ Bun (3x faster)❌ Node.js❌ Node.js
Backend✅ Elysia (ultra-fast)⚠️ API Routes✅ tRPC
Type Safety✅ Eden Treaty (auto)⚠️ Manual types✅ tRPC
Real-Time✅ Live Components built-in⚠️ Third-party⚠️ Third-party
API Docs✅ Auto-generated Swagger❌ Manual❌ Manual
Config System✅ Declarative + validation⚠️ Manual⚠️ Manual
Docker✅ Multi-stage ready⚠️ Manual⚠️ Manual
+ +--- + +## ⚙️ Requirements + + + + + + +
+ +### 📦 System Requirements +- **Bun** >= 1.2.0 (required runtime) +- **Git** (for version control) +- Linux, macOS, or Windows + + + +### 📥 Install Bun + +**macOS / Linux:** ```bash -# macOS / Linux curl -fsSL https://bun.sh/install | bash +``` -# Windows +**Windows:** +```powershell powershell -c "irm bun.sh/install.ps1 | iex" ``` -> FluxStack requires Bun. Node.js is not supported as a runtime. +
-## Documentation +> ⚠️ **Important**: FluxStack requires Bun. Node.js is not supported as a runtime. -- [`LLMD/INDEX.md`](./LLMD/INDEX.md) - Documentation hub -- [`LLMD/core/`](./LLMD/core/) - Framework internals -- [`LLMD/resources/`](./LLMD/resources/) - Routes, controllers, plugins, Live Components -- [`LLMD/patterns/`](./LLMD/patterns/) - Best practices and anti-patterns -- [`LLMD/reference/`](./LLMD/reference/) - CLI commands, plugin hooks, troubleshooting +--- -## Contributing +## 📚 Documentation & Support + + + + + + + +
+ +### 📖 Documentation +- [LLMD Index](./LLMD/INDEX.md) — Navigation hub +- [Framework Lifecycle](./LLMD/core/framework-lifecycle.md) +- [Live Components](./LLMD/resources/live-components.md) +- [Live Rooms](./LLMD/resources/live-rooms.md) +- [Routes & Eden Treaty](./LLMD/resources/routes-eden.md) +- [CLI Reference](./LLMD/reference/cli-commands.md) +- [Troubleshooting](./LLMD/reference/troubleshooting.md) + + + +### 💬 Community +- [GitHub Issues](https://github.com/MarcosBrendonDePaula/FluxStack/issues) +- [Discussions](https://github.com/MarcosBrendonDePaula/FluxStack/discussions) +- [Repository](https://github.com/MarcosBrendonDePaula/FluxStack) + + + +### 🔄 Upgrading +```bash +bunx create-fluxstack@latest +``` + +
+ +--- + +## 🤝 Contributing 1. Fork the repository 2. Create a feature branch (`git checkout -b feature/my-feature`) @@ -310,6 +763,23 @@ powershell -c "irm bun.sh/install.ps1 | iex" Please open an [issue](https://github.com/MarcosBrendonDePaula/FluxStack/issues) first to discuss larger changes. -## License +--- + +## 📄 License [MIT](LICENSE) - Marcos Brendon De Paula + +--- + +
+ +**Made with ❤️ by the FluxStack Team** + +*Star ⭐ this repo if you find it helpful!* + +[![GitHub Repo](https://img.shields.io/badge/GitHub-FluxStack-blue?style=for-the-badge&logo=github)](https://github.com/MarcosBrendonDePaula/FluxStack) +[![npm](https://img.shields.io/badge/npm-create--fluxstack-red?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/create-fluxstack) + +[Report Bug](https://github.com/MarcosBrendonDePaula/FluxStack/issues) · [Request Feature](https://github.com/MarcosBrendonDePaula/FluxStack/issues) · [Contribute](https://github.com/MarcosBrendonDePaula/FluxStack/pulls) + +