diff --git a/README.md b/README.md index d516d5c..7a2700c 100644 --- a/README.md +++ b/README.md @@ -1,321 +1,100 @@ -
+# FluxStack -# ⚡ FluxStack - -### The Revolutionary Full-Stack TypeScript Framework - -*Build modern web apps with Bun, Elysia, React, and Eden Treaty* +Full-stack TypeScript framework built on Bun, Elysia.js, and React with end-to-end type safety via 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)](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) • [Documentation](#-documentation--support) • [Examples](#-type-safe-api-development) - -
- ---- - -## ✨ 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 - - +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) -### 🎯 **Production Ready** -- **Docker Multi-Stage** - Optimized containers -- **Declarative Config** - Environment management -- **WebSocket Support** - Real-time features - -
- ---- - -## 🚀 Quick Start +## Quick Start ```bash -# Create a new FluxStack app -bunx create-fluxstack my-awesome-app -cd my-awesome-app +bunx create-fluxstack my-app +cd my-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 - -### 🔀 Frontend Routes (React Router v7) - -Default routes in the demo app: - -- `/` Home -- `/counter` Live Counter -- `/form` Live Form -- `/upload` Live Upload -- `/api-test` Eden Treaty API Test +This starts the full-stack dev server: -### 🧭 Router Package +| 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 | -This project now uses **React Router v7** via the `react-router` package (recommended by the v7 docs). -If you are upgrading from an older setup that used `react-router-dom`, update imports to `react-router`. - -### Alternative Installation +### Alternative: scaffold in current directory ```bash -# Create in current directory mkdir my-app && cd my-app bunx create-fluxstack . bun run dev ``` ---- - -## 💎 What You Get - -
-🎨 Modern Tech Stack (2025) - -| 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 | - -
- -
-⚙️ Zero-Config Features - -- ✅ **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** - LLM-optimized documentation (`LLMD/`) -- ✅ **Declarative Config** - Laravel-inspired configuration system -- ✅ **WebSocket Support** - Real-time features built-in -- ✅ **Testing Setup** - Vitest + React Testing Library ready - -
- ---- - -## 🏗️ Architecture Overview - -
- -```mermaid -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 -``` - -
+## Tech Stack -### 📁 Project Structure +| 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 | -
-Click to expand directory structure +## Project Structure -```bash +``` 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 +├── 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 │ -├── ⚙️ config/ # Application Configuration -│ ├── app.config.ts # App settings -│ ├── server.config.ts # Server & CORS -│ ├── logger.config.ts # Logging -│ └── database.config.ts # Database +├── 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) +│ │ └── src/ +│ │ ├── components/ +│ │ ├── pages/ +│ │ ├── live/ # Client-side Live Components +│ │ └── lib/ # Eden Treaty client +│ └── shared/ # Shared type definitions │ -├── 🔌 plugins/ # External Plugins -│ └── crypto-auth/ # Example: Crypto authentication +├── config/ # Declarative configuration +│ ├── system/ # Config files (app, server, db, logger, etc.) +│ ├── fluxstack.config.ts +│ └── index.ts │ -├── 🤖 LLMD/ # LLM-Optimized Documentation -│ ├── INDEX.md # Navigation hub -│ ├── core/ # Framework internals -│ ├── config/ # Configuration system -│ ├── resources/ # Creating routes, controllers -│ ├── patterns/ # Best practices -│ └── reference/ # CLI, hooks, troubleshooting -│ -└── 📦 Package Files - ├── package.json # Dependencies - ├── tsconfig.json # TypeScript config - └── README.md # This file +├── plugins/ # Project plugins (auto-discovered) +├── tests/ # Test suite (unit + integration) +├── LLMD/ # LLM-optimized documentation +├── Dockerfile # Multi-stage production build +└── package.json ``` -
- ---- - -## 📜 Available Scripts - - - - - - - - - - -
+## Features -### 🔨 Development - -```bash -# Full-stack development -bun run dev +### End-to-End Type Safety -# Frontend only (port 5173) -bun run dev:frontend - -# Backend only (port 3001) -bun run dev:backend -``` - - - -### 🚀 Production - -```bash -# Build for production -bun run build +Eden Treaty infers types from Elysia route definitions automatically. No manual DTOs. -# Start production server -bun run start -``` - -
- -### 🧪 Testing & Quality - -```bash -# Run tests -bun run test - -# Test with UI -bun run test:ui - -# Type checking -bunx tsc --noEmit -``` - - - -### 🛠️ Utilities - -```bash -# 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 +**Define a route on the backend:** ```typescript -// app/server/routes/users.ts +// app/server/routes/users.routes.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(), @@ -326,348 +105,211 @@ export const userRoutes = new Elysia({ prefix: '/users' }) user: t.Optional(t.Object({ id: t.Number(), name: t.String(), - email: t.String(), - createdAt: t.Date() - })), - message: t.Optional(t.String()) + email: t.String() + })) }) }) ``` -### ✨ Use in Frontend (Fully Typed!) +**Use it on the frontend with full type inference:** ```typescript -// app/client/src/App.tsx -import { api } from '@/app/client/src/lib/eden-api' +// app/client/src/lib/eden-api.ts +import { api } from './eden-api' -// ✅ TypeScript knows all types automatically! -const { data: response, error } = await api.users.post({ - name: 'Ada Lovelace', // ✅ Type: string - email: 'ada@example.com' // ✅ Type: string (email format) +const { data, error } = await api.users.post({ + name: 'Ada Lovelace', // string + email: 'ada@example.com' // string (email) }) -// ✅ 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 +if (data?.user) { + console.log(data.user.name) // string - fully typed } ``` -### 🎯 Benefits +### Live Components -- ✅ **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 - -
-➕ Add a New API Route +Real-time WebSocket components with automatic state synchronization between server and client. ```typescript -// 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:** -```typescript -// app/server/index.ts -import { postRoutes } from './routes/posts' - -app.use(postRoutes) +// app/server/live/LiveCounter.ts +export class LiveCounter extends LiveComponent<{ count: number }> { + static defaultState = { count: 0 } + + async increment() { + this.state.count++ // auto-syncs to frontend via Proxy + return { success: true } + } +} ``` -
+### Room System -
-🔌 Create a Custom Plugin +Multi-room real-time communication for Live Components. ```typescript -// 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`) - }) +// 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) ``` -**Use it:** -```typescript -import { auditPlugin } from './plugins/audit' +Rooms are also accessible via HTTP for external integrations: -app.use(auditPlugin) +```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 -
-⚙️ Add Environment Configuration +Laravel-inspired config system with schema validation and type inference. ```typescript -// config/features.config.ts +// config/system/app.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']) +const appConfigSchema = { + name: config.string('APP_NAME', 'FluxStack', true), + port: config.number('PORT', 3000, true), + env: config.enum('NODE_ENV', ['development', 'production', 'test'] as const, 'development', true), + debug: config.boolean('DEBUG', false), } as const -export const featuresConfig = defineConfig(featuresConfigSchema) +export const appConfig = defineConfig(appConfigSchema) ``` -**Use it with full type safety:** -```typescript -import { featuresConfig } from '@/config/features.config' +All environment variables are validated at boot time. See [`.env.example`](.env.example) for available options. -if (featuresConfig.enableAnalytics) { - // Type: boolean (not string!) - trackEvent('user_action') -} -``` +### 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) | -## 📚 Documentation & Support +NPM plugins are blocked by default. To add one: - - - - - - -
- -### 📖 **Documentation** -- [LLM Documentation](./LLMD/) ⭐ **NEW** -- [LLMD Index](./LLMD/INDEX.md) - Navigation hub -- [Development Patterns](./LLMD/patterns/project-structure.md) -- [CLI Reference](./LLMD/reference/cli-commands.md) -- [CLAUDE.md](./CLAUDE.md) -- [AI Context (deprecated)](./ai-context/) - - +```bash +bun run cli plugin:add fluxstack-plugin-auth +``` -### 💬 **Community** -- [GitHub Issues](https://github.com/MarcosBrendonDePaula/FluxStack/issues) -- [Discussions](https://github.com/MarcosBrendonDePaula/FluxStack/discussions) -- [Repository](https://github.com/MarcosBrendonDePaula/FluxStack) +This audits the package, installs it, and adds it to the whitelist. - +## Scripts -### 🔄 **Upgrading** ```bash -bunx create-fluxstack@latest - -# Check version -npm list -g create-fluxstack +# 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 ``` -
- ---- - -## 🤔 Why FluxStack? - -### 🆚 **Comparison with Other Stacks** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FeatureFluxStackNext.jsT3 Stack
Runtime✅ Bun (3x faster)❌ Node.js❌ Node.js
Backend Framework✅ Elysia (ultra-fast)⚠️ Next.js API Routes✅ tRPC
Type Safety✅ Eden Treaty (auto-inferred)⚠️ Manual types✅ tRPC
Configuration✅ Declarative with validation⚠️ Manual setup⚠️ Manual setup
API Docs✅ Auto-generated Swagger❌ Manual❌ Manual
WebSockets✅ Built-in⚠️ Third-party⚠️ Third-party
Docker✅ Multi-stage ready⚠️ Manual setup⚠️ Manual setup
- -### 💡 **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:** -```bash -curl -fsSL https://bun.sh/install | bash -``` +## Frontend Routes -**Windows:** -```powershell -powershell -c "irm bun.sh/install.ps1 | iex" -``` +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 | + +## Environment Variables -
+Copy `.env.example` to `.env` and adjust as needed: -> ⚠️ **Important**: FluxStack is designed exclusively for the Bun runtime. Node.js is not supported. +```bash +cp .env.example .env +``` ---- +Key variables: -## 🚀 Ready to Build? +| 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. -### Start your next project in seconds +## Docker ```bash -bunx create-fluxstack my-awesome-app -cd my-awesome-app -bun run dev -``` +# Build +docker build -t fluxstack-app . -### Welcome to the future of full-stack development 🎉 +# Run +docker run -p 3000:3000 fluxstack-app +``` -[![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) +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) -## 📄 License +Install Bun: -This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details. +```bash +# macOS / Linux +curl -fsSL https://bun.sh/install | bash ---- +# Windows +powershell -c "irm bun.sh/install.ps1 | iex" +``` -## 🙏 Acknowledgments +> FluxStack requires Bun. Node.js is not supported as a runtime. -Built with amazing open-source technologies: -- [Bun](https://bun.sh) - Fast all-in-one JavaScript runtime -- [Elysia.js](https://elysiajs.com) - Ergonomic framework for humans -- [React](https://react.dev) - Library for web and native interfaces -- [Vite](https://vite.dev) - Next generation frontend tooling -- [Tailwind CSS](https://tailwindcss.com) - Utility-first CSS framework -- [TypeScript](https://www.typescriptlang.org) - JavaScript with syntax for types +## Documentation ---- +- [`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 -**Made with ❤️ by the FluxStack Team** +1. Fork the repository +2. Create a feature branch (`git checkout -b feature/my-feature`) +3. Commit your changes (`git commit -m 'Add my feature'`) +4. Push to the branch (`git push origin feature/my-feature`) +5. Open a Pull Request -*Star ⭐ this repo if you find it helpful!* +Please open an [issue](https://github.com/MarcosBrendonDePaula/FluxStack/issues) first to discuss larger changes. -[Report Bug](https://github.com/MarcosBrendonDePaula/FluxStack/issues) · [Request Feature](https://github.com/MarcosBrendonDePaula/FluxStack/issues) · [Contribute](https://github.com/MarcosBrendonDePaula/FluxStack/pulls) +## License -
+[MIT](LICENSE) - Marcos Brendon De Paula