create-fluxstack 1.5.4 → 1.7.0

package/README.md

@@ -1,96 +1,126 @@
-# ⚡ create-fluxstack
+# create-fluxstack
 
-> Create modern full-stack TypeScript applications with zero configuration
+Create modern full-stack TypeScript applications with zero configuration.
 
 [![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-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## 🚀 Quick Start
+---
+
+## Quick Start
 
 ```bash
-# Create a new FluxStack app
+# scaffold a new FluxStack app
 bunx create-fluxstack my-awesome-app
 
-# Navigate and start developing
+# enter the project and start developing
 cd my-awesome-app
 bun run dev
 ```
 
-**That's it!** Your full-stack TypeScript app is ready at:
-- 🚀 **Backend**: http://localhost:3000
-- ⚛️ **Frontend**: http://localhost:5173  
-- 📋 **API Docs**: http://localhost:3000/swagger
+Your development environment will be available at:
 
-## ✨ What You Get
+- **Backend**: http://localhost:3000  
+- **Frontend (proxied)**: http://localhost:3000/  
+- **API Docs**: http://localhost:3000/swagger
 
-### 🔥 Modern Tech Stack
-- **⚡ Bun Runtime** - 3x faster than Node.js
-- **🚀 Elysia.js** - Ultra-fast backend framework
-- **⚛️ React 19** - Latest React with modern features
-- **🎨 Tailwind CSS v4** - Latest styling framework
-- **📦 Vite 7** - Lightning-fast dev server
-- **🔒 TypeScript 5** - Full type safety end-to-end
+---
 
-### 🛠️ Zero Configuration Features
-- **✅ Type Safety** - Eden Treaty for API communication with automatic type inference
-- **✅ Hot Reload** - Backend + Frontend coordinated development
-- **✅ Auto Documentation** - Swagger UI generated from your API
-- **✅ Git Ready** - Repository initialized with proper .gitignore
-- **✅ Production Ready** - Optimized build scripts included
-- **✅ AI Context** - Complete documentation for AI assistants
+## What You Get
 
-## 📁 Project Structure
+### Modern Tech Stack
+- Bun runtime (3x faster than Node.js)
+- Elysia.js backend
+- React 19 + Vite 7 frontend
+- Tailwind CSS v4 styling
+- TypeScript 5 end-to-end typing
+
+### Zero-Config Features
+- Automatic Eden Treaty type inference
+- Coordinated hot reload (backend + frontend)
+- Swagger documentation out of the box
+- Production-ready build scripts and Docker templates
+- AI-focused documentation (`ai-context/`)
+
+---
+
+## Architecture Overview
 
 ```
-my-awesome-app/
-├── core/                    # FluxStack framework (don't modify)
-│   ├── server/             # Framework server components  
-│   ├── config/             # Configuration system
-│   ├── plugins/            # Built-in plugins (logger, swagger, etc)
-│   └── cli/                # Development CLI tools
-├── app/                     # Your application code
-│   ├── server/             # Backend API routes
-│   │   ├── controllers/    # Business logic
-│   │   └── routes/         # API endpoints  
-│   ├── client/             # Frontend React app
-│   │   ├── src/            # React components
-│   │   └── public/         # Static assets
-│   └── shared/             # Shared types and utilities
-├── ai-context/              # AI assistant documentation
-├── package.json            # Dependencies and scripts
-├── CLAUDE.md               # AI instructions
-└── README.md               # Project documentation
+┌─────────────────────────────────────────────────────────────┐
+│                     FluxStack Monorepo                      │
+├─────────────────────────────────────────────────────────────┤
+│ app/                                                        │
+│  ├─ Frontend (React + Vite)                                 │
+│  ├─ Backend (Elysia + Bun)                                  │
+│  └─ Shared Types / Utils                                    │
+├─────────────────────────────────────────────────────────────┤
+│ core/                                                       │
+│  ├─ Server Framework                                        │
+│  ├─ Plugin System                                           │
+│  └─ Build System                                            │
+├─────────────────────────────────────────────────────────────┤
+│ Communication Layer (Eden Treaty, WebSockets)               │
+├─────────────────────────────────────────────────────────────┤
+│ Configuration Management                                    │
+└─────────────────────────────────────────────────────────────┘
 ```
 
-## 🎯 Available Scripts
+```
+FluxStack/
+├─ core/                    # framework internals (read-only)
+│  ├─ framework/            # FluxStackFramework (Elysia orchestrator)
+│  ├─ plugins/              # built-in plugins (swagger, vite, static, monitoring)
+│  ├─ build/                # bundler, optimizer, Docker scaffolding
+│  ├─ cli/                  # flux CLI commands and generators
+│  ├─ config/               # declarative schema helpers
+│  └─ utils/                # logging, environment helpers, etc.
+├─ app/                     # your editable application code
+│  ├─ server/               # API routes, controllers, services, live components
+│  │  ├─ controllers/       # business logic
+│  │  ├─ routes/            # endpoints + schemas
+│  │  ├─ types/             # shared types and App export for Eden Treaty
+│  │  └─ live/              # WebSocket live components
+│  ├─ client/               # React SPA (components, pages, hooks, store)
+│  └─ shared/               # cross-layer types/utilities
+├─ config/                  # project-specific config built on the schema
+├─ plugins/                 # optional external plugins (e.g. crypto-auth)
+├─ ai-context/              # documentation tailored for assistants
+└─ package.json / README.md # project metadata
+```
+
+---
+
+## Available Scripts
 
 ```bash
-# Development
-bun run dev              # Start full-stack development
-bun run dev:clean        # Clean output (no Elysia HEAD logs)
-bun run dev:frontend     # Frontend only (port 5173)
-bun run dev:backend      # Backend only (port 3001)
-
-# Production
-bun run build            # Build for production
-bun run start            # Start production server
-
-# Utilities
-bun run typecheck        # Check TypeScript
-bun run test             # Run test suite
+# development
+bun run dev              # full stack with proxy + vite
+bun run dev              # logs are automatically filtered in development
+bun run dev:frontend     # only the frontend (port 5173, no proxy)
+bun run dev:backend      # only the backend (port 3001)
+
+# production
+bun run build            # build backend + frontend + manifest
+bun run start            # start production bundle
+
+# utilities
+bun run typecheck        # run TypeScript type checking
+bun run test             # execute Vitest suite
 ```
 
-## 🔧 Type-Safe API Development
+---
+
+## Type-Safe API Development
 
-FluxStack provides automatic type inference between your backend and frontend using Eden Treaty:
+FluxStack uses Eden Treaty to eliminate manual DTOs.
 
-### Backend API (Elysia.js)
-```typescript
-// app/server/routes/users.ts
+### Backend Route (Elysia)
+```ts
 import { Elysia, t } from 'elysia'
 
 export const userRoutes = new Elysia({ prefix: '/users' })
-  .get('/', () => ({ users: getAllUsers() }))
+  .get('/', () => ({ users: listUsers() }))
   .post('/', ({ body }) => createUser(body), {
     body: t.Object({
       name: t.String(),
@@ -108,105 +138,27 @@ export const userRoutes = new Elysia({ prefix: '/users' })
   })
 ```
 
-### Frontend with Type Safety
-```typescript
-// app/client/src/components/Users.tsx
-import { api } from '../lib/eden-api'
-
-export function UsersList() {
-  const [users, setUsers] = useState<User[]>([])
-
-  const createUser = async (userData: CreateUserData) => {
-    // ✨ Fully typed - no manual type definitions needed!
-    const { data, error } = await api.users.post(userData)
-    
-    if (!error) {
-      setUsers(prev => [...prev, data.user]) // ✅ TypeScript knows the shape
-    }
-  }
-
-  return (
-    <div>
-      {users.map(user => (
-        <UserCard key={user.id} user={user} />
-      ))}
-    </div>
-  )
-}
-```
-
-## 🌍 Environment & Configuration
+### Frontend Usage (React)
+```tsx
+import { api } from '@/app/client/src/lib/eden-api'
 
-### Environment Variables
-```bash
-# .env (auto-generated from .env.example)
-NODE_ENV=development
-PORT=3000
-HOST=localhost
-VITE_PORT=5173
-VITE_API_URL=http://localhost:3000
-
-# Add your own variables
-DATABASE_URL=postgresql://localhost:5432/myapp
-JWT_SECRET=your-secret-key
-```
-
-### Frontend Environment
-```typescript
-// Only VITE_* variables are exposed to frontend
-const apiUrl = import.meta.env.VITE_API_URL
-const appName = import.meta.env.VITE_APP_NAME
-```
-
-## 🚀 Deployment
-
-### Single Server (Recommended)
-```bash
-# Build everything
-bun run build
-
-# Start production server
-bun run start
-```
-
-### Separate Deploy
-```bash
-# Backend
-bun run build:backend
-bun dist/index.js
-
-# Frontend  
-bun run build:frontend
-# Deploy dist/ folder to CDN
-```
-
-### Docker
-```bash
-# Use included Dockerfile
-docker build -t my-app .
-docker run -p 3000:3000 my-app
-```
+const { data: response, error } = await api.users.post({
+  name: 'Ada Lovelace',
+  email: 'ada@example.com'
+})
 
-## 🔧 Requirements
-
-- **Bun** >= 1.2.0 (required)
-
-### Install Bun
-```bash
-# macOS/Linux
-curl -fsSL https://bun.sh/install | bash
-
-# Windows
-powershell -c "irm bun.sh/install.ps1|iex"
+if (!error && response?.user) {
+  console.log(response.user.name)
+}
 ```
 
-> **Note**: FluxStack is built specifically for Bun runtime. Node.js is not supported.
+---
 
-## 🎨 Customization
+## Customisation Highlights
 
-### Adding API Routes
-```typescript
-// app/server/routes/posts.ts  
+### Add a Route
+```ts
+// app/server/routes/posts.ts
 import { Elysia, t } from 'elysia'
 
 export const postRoutes = new Elysia({ prefix: '/posts' })
@@ -220,96 +172,101 @@ export const postRoutes = new Elysia({ prefix: '/posts' })
 
 // app/server/index.ts
 import { postRoutes } from './routes/posts'
-
 app.use(postRoutes)
 ```
 
-### Custom Plugins
-```typescript
-// app/server/plugins/auth.ts
+### Create a Plugin
+```ts
+// app/server/plugins/audit.ts
 import { Elysia } from 'elysia'
 
-export const authPlugin = new Elysia({ name: 'auth' })
-  .derive(({ headers }) => ({
-    user: getUserFromToken(headers.authorization)
-  }))
-  .guard({
-    beforeHandle({ user, set }) {
-      if (!user) {
-        set.status = 401
-        return { error: 'Unauthorized' }
-      }
-    }
+export const auditPlugin = new Elysia({ name: 'audit' })
+  .onRequest(({ request }) => {
+    console.log(`[AUDIT] ${request.method} ${request.url}`)
   })
 ```
 
-## 📚 Documentation & AI Support
+---
+
+## Documentation & Support
 
-FluxStack includes comprehensive documentation for both developers and AI assistants:
+- Full documentation lives in `ai-context/`.
+- Assistant guidelines: `CLAUDE.md`.
+- Quick start for AI agents: `ai-context/00-QUICK-START.md`.
+- Example apps and guides included in `examples/` and `ai-context/`.
 
-- **📖 Full Documentation**: Check the `ai-context/` folder
-- **🤖 AI Instructions**: See `CLAUDE.md` for AI assistant guidance
-- **⚡ Quick Start**: `ai-context/00-QUICK-START.md`
-- **🎯 Examples**: Complete CRUD examples included
+---
+
+## Community
 
-## 🛟 Support & Community
+- **Issues**: [GitHub Issues](https://github.com/MarcosBrendonDePaula/FluxStack/issues)
+- **Docs**: [Repository Docs](https://github.com/MarcosBrendonDePaula/FluxStack)
+- **Discussions**: [GitHub Discussions](https://github.com/MarcosBrendonDePaula/FluxStack/discussions)
 
-- **🐛 Issues**: [Report bugs](https://github.com/MarcosBrendonDePaula/FluxStack/issues)
-- **📖 Documentation**: [Full docs](https://github.com/MarcosBrendonDePaula/FluxStack)
-- **💬 Discussions**: [GitHub Discussions](https://github.com/MarcosBrendonDePaula/FluxStack/discussions)
+---
 
-## 🔄 Upgrading
+## Upgrading
 
 ```bash
-# Get the latest version
+# pull the latest scaffold
 bunx create-fluxstack@latest my-new-app
 
-# Check current version
+# check current global version
 npm list -g create-fluxstack
 ```
 
-## 🌟 Why FluxStack?
+---
+
+## Why FluxStack?
+
+### Developer Experience
+- Zero configuration – start coding immediately.
+- Type-safe from controllers to components.
+- Hot reload with backend/frontend coordination.
+- Swagger documentation generated automatically.
 
-### ✅ **Developer Experience**
-- **Zero Config**: Just create and start coding
-- **Type Safety**: End-to-end without manual work
-- **Hot Reload**: Backend and frontend in sync
-- **Auto Docs**: Swagger generated from your code
+### Performance
+- Bun runtime for fast startup and low memory.
+- Elysia for high-performance API routing.
+- Vite for instant dev server and optimized builds.
+- React 19 for modern UI primitives.
 
-### ✅ **Performance**
-- **Bun Runtime**: 3x faster than Node.js
-- **Elysia**: One of the fastest TypeScript frameworks
-- **Vite**: Instant HMR and optimized builds
-- **React 19**: Latest performance improvements
+### Production Ready
+- Docker multi-stage builds out of the box.
+- Declarative configuration with environment overrides.
+- Unified error handling and logging support.
+- Optional monitoring plugin for metrics/exporters.
 
-### ✅ **Production Ready**
-- **Docker**: Optimized containers included
-- **Environment**: Robust configuration system
-- **Error Handling**: Consistent error responses
-- **Monitoring**: Built-in observability features
+### Modern Stack
+- TypeScript 5, React 19, Tailwind v4, Eden Treaty.
+- Shared types everywhere.
+- WebSocket live components built in.
+
+---
 
-### ✅ **Modern Stack**
-- **TypeScript 5**: Latest language features
-- **React 19**: Concurrent features, Server Components ready
-- **Tailwind v4**: Latest CSS framework
-- **Eden Treaty**: Revolutionary type-safe API client
+## Requirements
 
-## 🎊 Get Started Now!
+- **Bun** ≥ 1.2.0
 
+### Install Bun
 ```bash
-bunx create-fluxstack my-dream-app
-cd my-dream-app
-bun run dev
+# macOS / Linux
+curl -fsSL https://bun.sh/install | bash
+
+# Windows
+powershell -c "irm bun.sh/install.ps1 | iex"
 ```
 
-**Welcome to the future of full-stack development!** ⚡🚀
+> FluxStack targets the Bun runtime. Node.js is not supported.
 
 ---
 
-<div align="center">
-  
-**Built with ❤️ by the FluxStack Team**
+## Ready to Build?
 
-[⭐ Star on GitHub](https://github.com/MarcosBrendonDePaula/FluxStack) • [📦 NPM Package](https://www.npmjs.com/package/create-fluxstack)
+```bash
+bunx create-fluxstack my-dream-app
+cd my-dream-app
+bun run dev
+```
 
-</div>
+Welcome to the future of full-stack development.

package/app/client/src/App.tsx

@@ -1,14 +1,14 @@
 import { useState, useEffect } from 'react'
 import { api, getErrorMessage } from './lib/eden-api'
-import { 
-  FaRocket, FaReact, FaLink, FaDocker, FaFlask, FaPalette,
-  FaCheckCircle, FaTimesCircle, FaSpinner, FaSync,
-  FaUsers, FaTrash, FaPlus, FaBook, FaCode, FaCog,
-  FaServer, FaDatabase, FaShieldAlt, FaBolt, FaLock,
-  FaBullseye, FaGlobe,  FaFileAlt,
-  FaClipboardList, FaFire, FaFlask as FaTest, 
+import {
+  FaRocket,
+  FaCheckCircle, FaTimesCircle, FaBook, FaShieldAlt, FaBolt,
+  FaClipboardList, FaFire, FaFlask as FaTest,
 } from 'react-icons/fa'
-import { BrowserRouter, Routes, Route, Link } from 'react-router-dom'
+import { Routes, Route, Link } from 'react-router-dom'
+
+// Live Components Provider - Singleton WebSocket Connection for All Live Components
+import { LiveComponentsProvider } from '@/core/client'
 
 // Import page components
 import { OverviewPage } from './pages/Overview'
@@ -17,7 +17,6 @@ import { HybridLivePage } from './pages/HybridLive'
 import { ApiDocsPage } from './pages/ApiDocs'
 import { CryptoAuthPage } from './pages/CryptoAuthPage'
 import { MainLayout } from './components/MainLayout'
-import { LiveClock } from './components/LiveClock'
 
 // State management is now handled by Zustand stores directly
 
@@ -25,7 +24,22 @@ interface User {
   id: number
   name: string
   email: string
-  createdAt: string
+  createdAt: string | Date
+}
+
+interface UsersResponse {
+  users: User[]
+}
+
+interface UserCreateResponse {
+  success: boolean
+  user?: User
+  message?: string
+}
+
+interface UserDeleteResponse {
+  success: boolean
+  message?: string
 }
 
 function AppContent() {
@@ -44,7 +58,7 @@ function AppContent() {
 
   const checkApiStatus = async () => {
     try {
-      const { data, error } = await api.health.get()
+      const { error } = await api.health.get()
       if (error) {
         setApiStatus('offline')
       } else {
@@ -65,7 +79,7 @@ function AppContent() {
         return
       }
       
-      setUsers(data.users || [])
+      setUsers((data as UsersResponse).users || [])
     } catch (error) {
       showMessage('error', getErrorMessage(error))
     } finally {
@@ -89,13 +103,14 @@ function AppContent() {
         return
       }
       
-      if (result.success && result.user) {
-        setUsers(prev => [...prev, result.user])
+      const createResult = result as UserCreateResponse
+      if (createResult.success && createResult.user) {
+        setUsers(prev => [...prev, createResult.user!])
         setName('')
         setEmail('')
         showMessage('success', `Usuário ${name} adicionado com sucesso!`)
       } else {
-        showMessage('error', result.message || 'Erro ao criar usuário')
+        showMessage('error', createResult.message || 'Erro ao criar usuário')
       }
     } catch (error) {
       showMessage('error', getErrorMessage(error))
@@ -115,11 +130,12 @@ function AppContent() {
         return
       }
       
-      if (result.success) {
+      const deleteResult = result as UserDeleteResponse
+      if (deleteResult.success) {
         setUsers(prev => prev.filter(user => user.id !== userId))
         showMessage('success', `Usuário ${userName} removido com sucesso!`)
       } else {
-        showMessage('error', result.message || 'Erro ao deletar usuário')
+        showMessage('error', deleteResult.message || 'Erro ao deletar usuário')
       }
     } catch (error) {
       showMessage('error', getErrorMessage(error))
@@ -297,9 +313,19 @@ function AppContent() {
   )
 }
 
-// Main App component - Zustand stores are available globally
+// Main App component - Wrapped with LiveComponentsProvider for single WebSocket connection
 function App() {
-  return <AppContent />
+  return (
+    <LiveComponentsProvider
+      autoConnect={true}
+      reconnectInterval={1000}
+      maxReconnectAttempts={5}
+      heartbeatInterval={30000}
+      debug={false}
+    >
+      <AppContent />
+    </LiveComponentsProvider>
+  )
 }
 
 export default App

package/app/client/src/components/FluxStackConfig.tsx

@@ -1,7 +1,7 @@
 // 🔥 FluxStack Configuration Viewer Component
 
 import { useState } from 'react'
-import { useHybridLiveComponent } from 'fluxstack'
+import { useHybridLiveComponent } from '@/core/client'
 import { 
   FaCog, 
   FaServer, 

package/app/client/src/components/HybridLiveCounter.tsx

@@ -1,6 +1,6 @@
 // 🔥 Simple Hybrid Live Counter - Server-Driven with Zustand
 
-import { useHybridLiveComponent } from 'fluxstack'
+import { useHybridLiveComponent } from '@/core/client'
 
 interface CounterState {
   count: number

package/app/client/src/components/LiveClock.tsx

@@ -1,6 +1,6 @@
 // 🔥 LiveClock - Real-time Clock Client Component
 import React, { useState } from 'react';
-import { useHybridLiveComponent } from 'fluxstack';
+import { useHybridLiveComponent } from '@/core/client';
 import { 
   FaClock, 
   FaCog, 

package/app/client/src/components/MainLayout.tsx

@@ -6,7 +6,6 @@ import { UserProfile } from './UserProfile'
 import { SystemMonitor } from './SystemMonitor'
 import { FluxStackConfig } from './FluxStackConfig'
 import { FaHome, FaCog, FaFolder, FaChartBar, FaRocket, FaServer } from 'react-icons/fa'
-import { Teste } from './Teste'
 
 // Temporary placeholder components for other pages
 function Dashboard() {
@@ -128,7 +127,6 @@ function Dashboard() {
           </ul>
         </div>
       </div>
-      <Teste></Teste>
     </div>
   )
 }

package/app/client/src/components/SidebarNavigation.tsx

@@ -1,6 +1,6 @@
 // 🔥 Sidebar Navigation Component
 
-import { useHybridLiveComponent } from 'fluxstack'
+import { useHybridLiveComponent } from '@/core/client'
 import { 
   FaHome, 
   FaUser,