create-fluxstack 1.0.9 → 1.0.11

package/.claude/settings.local.json

@@ -63,7 +63,9 @@
       "Read(/C:\\Users\\Marcos\\Documents\\GitHub\\aviso-projeto\\test-cli-update\\ai-context/**)",
       "Read(/C:\\Users\\Marcos\\Documents\\GitHub\\aviso-projeto\\test-cli-update/**)",
       "Read(/C:\\Users\\Marcos\\Documents\\GitHub\\aviso-projeto\\test-cli-update/**)",
-      "Read(/C:\\Users\\Marcos\\Documents\\GitHub\\aviso-projeto\\test-gitignore/**)"
+      "Read(/C:\\Users\\Marcos\\Documents\\GitHub\\aviso-projeto\\test-gitignore/**)",
+      "Read(/C:\\Users\\Marcos\\Documents\\GitHub\\aviso-projeto\\test-plugins-guide/**)",
+      "Read(/C:\\Users\\Marcos\\Documents\\GitHub\\aviso-projeto\\test-plugins-guide\\ai-context\\development/**)"
     ],
     "deny": []
   }

package/ai-context/development/plugins-guide.md

@@ -0,0 +1,568 @@
+# 🔌 FluxStack Plugins Guide
+
+> Complete guide for adding and creating plugins in FluxStack applications
+
+## 🎯 Overview
+
+FluxStack provides a powerful plugin system that allows developers to extend their applications with custom functionality. Plugins can hook into various parts of the application lifecycle and provide reusable features.
+
+## 📦 Built-in Plugins
+
+FluxStack comes with several built-in plugins:
+
+- **🪵 Logger Plugin**: Structured logging with customizable levels
+- **📋 Swagger Plugin**: Auto-generated API documentation  
+- **🌐 Static Plugin**: Serves static files in production
+- **⚡ Vite Plugin**: Dev server integration with hot reload
+- **📊 Monitoring Plugin**: Performance metrics and health checks
+
+## 🚀 Using Built-in Plugins
+
+### Basic Plugin Usage
+
+```typescript
+// app/server/index.ts
+import { 
+  FluxStackFramework, 
+  loggerPlugin, 
+  swaggerPlugin,
+  staticPlugin,
+  vitePlugin 
+} from "@/core/server"
+
+const app = new FluxStackFramework({ /* config */ })
+
+// Add built-in plugins
+app.use(loggerPlugin)
+app.use(swaggerPlugin)
+
+// Conditional plugin loading
+if (isDevelopment()) {
+  app.use(vitePlugin)
+} else {
+  app.use(staticPlugin)
+}
+```
+
+### Plugin Configuration
+
+```typescript
+// Configure plugins with options
+app.use(loggerPlugin, {
+  level: 'debug',
+  format: 'pretty',
+  timestamp: true
+})
+
+app.use(swaggerPlugin, {
+  title: 'My API',
+  version: '2.0.0',
+  description: 'Custom API documentation'
+})
+```
+
+## 🛠️ Creating Custom Plugins
+
+### 1. Simple Plugin Structure
+
+Create plugins in your application directory:
+
+```typescript
+// app/server/plugins/auth.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' }
+      }
+    }
+  })
+
+// Usage in app/server/index.ts
+import { authPlugin } from './plugins/auth'
+app.use(authPlugin)
+```
+
+### 2. Advanced Plugin with Lifecycle Hooks
+
+```typescript
+// app/server/plugins/database.ts
+import { Elysia } from 'elysia'
+import type { PluginContext, FluxStackPlugin } from '@/core/plugins/types'
+
+export interface DatabaseConfig {
+  url: string
+  poolSize?: number
+  ssl?: boolean
+}
+
+export const createDatabasePlugin = (config: DatabaseConfig): FluxStackPlugin => ({
+  name: 'database',
+  version: '1.0.0',
+  dependencies: [],
+  
+  setup: async (context: PluginContext) => {
+    context.logger.info('Setting up database connection', { url: config.url })
+    
+    // Initialize database connection
+    const db = await connectToDatabase(config)
+    
+    return {
+      db,
+      query: db.query.bind(db),
+      transaction: db.transaction.bind(db)
+    }
+  },
+
+  onServerStart: async (context: PluginContext) => {
+    context.logger.info('Database plugin started')
+    // Run migrations, health checks, etc.
+  },
+
+  onServerStop: async (context: PluginContext) => {
+    context.logger.info('Closing database connections')
+    // Clean up connections
+  },
+
+  plugin: new Elysia({ name: 'database' })
+    .derive(() => ({
+      // Provide database utilities to routes
+      db: context.db
+    }))
+})
+
+// Usage
+import { createDatabasePlugin } from './plugins/database'
+
+const databasePlugin = createDatabasePlugin({
+  url: process.env.DATABASE_URL!,
+  poolSize: 10,
+  ssl: process.env.NODE_ENV === 'production'
+})
+
+app.use(databasePlugin)
+```
+
+### 3. Plugin with Configuration Schema
+
+```typescript
+// app/server/plugins/cache.ts
+import { Elysia } from 'elysia'
+import type { FluxStackPlugin } from '@/core/plugins/types'
+
+export interface CacheConfig {
+  provider: 'redis' | 'memory'
+  ttl: number
+  maxSize?: number
+  redis?: {
+    host: string
+    port: number
+    password?: string
+  }
+}
+
+export const createCachePlugin = (config: CacheConfig): FluxStackPlugin => {
+  const cache = config.provider === 'redis' 
+    ? new RedisCache(config.redis!)
+    : new MemoryCache({ maxSize: config.maxSize })
+
+  return {
+    name: 'cache',
+    version: '1.0.0',
+    
+    setup: async (context) => {
+      await cache.connect()
+      context.logger.info('Cache plugin initialized', { provider: config.provider })
+      
+      return { cache }
+    },
+
+    plugin: new Elysia({ name: 'cache' })
+      .derive(() => ({
+        cache: {
+          get: (key: string) => cache.get(key),
+          set: (key: string, value: any, ttl = config.ttl) => 
+            cache.set(key, value, ttl),
+          del: (key: string) => cache.del(key),
+          flush: () => cache.flush()
+        }
+      }))
+  }
+}
+
+// Usage in routes
+// app/server/routes/posts.routes.ts
+export const postsRoutes = new Elysia({ prefix: '/posts' })
+  .get('/', async ({ cache }) => {
+    const cached = await cache.get('posts:all')
+    if (cached) return cached
+
+    const posts = await getAllPosts()
+    await cache.set('posts:all', posts, 300) // 5 minutes
+    return posts
+  })
+```
+
+## 🎨 Plugin Patterns
+
+### 1. Middleware Plugin
+
+```typescript
+// app/server/plugins/cors.ts
+import { Elysia } from 'elysia'
+
+export interface CorsConfig {
+  origins: string[]
+  methods: string[]
+  headers: string[]
+}
+
+export const createCorsPlugin = (config: CorsConfig) => 
+  new Elysia({ name: 'cors' })
+    .onBeforeHandle(({ set, request }) => {
+      const origin = request.headers.get('origin')
+      
+      if (config.origins.includes(origin || '')) {
+        set.headers['Access-Control-Allow-Origin'] = origin
+        set.headers['Access-Control-Allow-Methods'] = config.methods.join(', ')
+        set.headers['Access-Control-Allow-Headers'] = config.headers.join(', ')
+      }
+    })
+```
+
+### 2. Validation Plugin
+
+```typescript
+// app/server/plugins/validation.ts
+import { Elysia } from 'elysia'
+import { z } from 'zod'
+
+export const validationPlugin = new Elysia({ name: 'validation' })
+  .macro(({ onBeforeHandle }) => ({
+    validate: (schema: z.ZodSchema) => onBeforeHandle(({ body, set }) => {
+      try {
+        return schema.parse(body)
+      } catch (error) {
+        set.status = 400
+        return { error: 'Validation failed', details: error.errors }
+      }
+    })
+  }))
+
+// Usage
+const userSchema = z.object({
+  name: z.string().min(2),
+  email: z.string().email()
+})
+
+export const usersRoutes = new Elysia({ prefix: '/users' })
+  .use(validationPlugin)
+  .post('/', ({ body }) => {
+    // body is now validated and typed
+    return createUser(body)
+  }, {
+    validate: userSchema
+  })
+```
+
+### 3. Rate Limiting Plugin
+
+```typescript
+// app/server/plugins/rate-limit.ts
+import { Elysia } from 'elysia'
+
+interface RateLimitConfig {
+  max: number
+  window: number // milliseconds
+  keyGenerator?: (request: Request) => string
+}
+
+export const createRateLimitPlugin = (config: RateLimitConfig) => {
+  const requests = new Map<string, { count: number; resetTime: number }>()
+
+  return new Elysia({ name: 'rate-limit' })
+    .onBeforeHandle(({ request, set }) => {
+      const key = config.keyGenerator?.(request) ?? 
+        request.headers.get('x-forwarded-for') ?? 'default'
+      
+      const now = Date.now()
+      const record = requests.get(key)
+
+      if (!record || now > record.resetTime) {
+        requests.set(key, { count: 1, resetTime: now + config.window })
+        return
+      }
+
+      if (record.count >= config.max) {
+        set.status = 429
+        return { error: 'Rate limit exceeded' }
+      }
+
+      record.count++
+    })
+}
+
+// Usage
+const rateLimitPlugin = createRateLimitPlugin({
+  max: 100,
+  window: 60 * 1000, // 1 minute
+  keyGenerator: (req) => req.headers.get('x-api-key') ?? 'anonymous'
+})
+
+app.use(rateLimitPlugin)
+```
+
+## 📂 Plugin Organization
+
+### Recommended Structure
+
+```
+app/server/plugins/
+├── auth/
+│   ├── index.ts          # Main auth plugin
+│   ├── strategies/       # Different auth strategies
+│   │   ├── jwt.ts
+│   │   └── oauth.ts
+│   └── middleware/       # Auth-related middleware
+├── database/
+│   ├── index.ts          # Database plugin
+│   ├── migrations/       # Database migrations
+│   └── seeds/           # Database seeds
+├── cache/
+│   ├── index.ts          # Cache plugin
+│   ├── providers/       # Different cache providers
+│   │   ├── redis.ts
+│   │   └── memory.ts
+└── monitoring/
+    ├── index.ts          # Monitoring plugin
+    ├── metrics.ts        # Custom metrics
+    └── health.ts         # Health checks
+```
+
+### Plugin Registration
+
+```typescript
+// app/server/plugins/index.ts
+export { authPlugin } from './auth'
+export { createDatabasePlugin } from './database'
+export { createCachePlugin } from './cache'
+export { monitoringPlugin } from './monitoring'
+
+// app/server/index.ts
+import {
+  authPlugin,
+  createDatabasePlugin,
+  createCachePlugin,
+  monitoringPlugin
+} from './plugins'
+
+// Register plugins in order of dependency
+app.use(createDatabasePlugin({ url: env.DATABASE_URL }))
+app.use(createCachePlugin({ provider: 'redis', ttl: 300 }))
+app.use(authPlugin)
+app.use(monitoringPlugin)
+```
+
+## 🔧 Plugin Configuration
+
+### Environment-based Plugin Loading
+
+```typescript
+// app/server/index.ts
+import { env } from '@/core/utils/env-runtime-v2'
+
+// Conditional plugin loading based on environment
+if (env.ENABLE_AUTH) {
+  app.use(authPlugin)
+}
+
+if (env.ENABLE_CACHE) {
+  app.use(createCachePlugin({
+    provider: env.CACHE_PROVIDER,
+    ttl: env.CACHE_TTL
+  }))
+}
+
+if (env.ENABLE_MONITORING) {
+  app.use(monitoringPlugin)
+}
+```
+
+### Plugin Configuration File
+
+```typescript
+// app/server/config/plugins.ts
+import type { PluginConfig } from '@/core/plugins/types'
+
+export const pluginConfig: PluginConfig = {
+  auth: {
+    enabled: true,
+    strategy: 'jwt',
+    secret: process.env.JWT_SECRET,
+    expiresIn: '24h'
+  },
+  cache: {
+    enabled: true,
+    provider: 'redis',
+    redis: {
+      host: process.env.REDIS_HOST,
+      port: parseInt(process.env.REDIS_PORT || '6379'),
+      password: process.env.REDIS_PASSWORD
+    },
+    ttl: 300
+  },
+  monitoring: {
+    enabled: process.env.NODE_ENV === 'production',
+    metrics: true,
+    healthChecks: true,
+    profiling: false
+  }
+}
+```
+
+## 🧪 Testing Plugins
+
+### Plugin Unit Tests
+
+```typescript
+// app/server/plugins/__tests__/auth.test.ts
+import { describe, it, expect } from 'bun:test'
+import { Elysia } from 'elysia'
+import { authPlugin } from '../auth'
+
+describe('Auth Plugin', () => {
+  const app = new Elysia().use(authPlugin)
+
+  it('should authenticate valid token', async () => {
+    const response = await app.handle(
+      new Request('http://localhost/protected', {
+        headers: { Authorization: 'Bearer valid-token' }
+      })
+    )
+    
+    expect(response.status).toBe(200)
+  })
+
+  it('should reject invalid token', async () => {
+    const response = await app.handle(
+      new Request('http://localhost/protected', {
+        headers: { Authorization: 'Bearer invalid-token' }
+      })
+    )
+    
+    expect(response.status).toBe(401)
+  })
+})
+```
+
+### Integration Testing
+
+```typescript
+// tests/integration/plugins.test.ts
+import { describe, it, expect } from 'bun:test'
+import { FluxStackFramework } from '@/core/server'
+import { authPlugin, createCachePlugin } from '@/app/server/plugins'
+
+describe('Plugin Integration', () => {
+  const app = new FluxStackFramework()
+    .use(authPlugin)
+    .use(createCachePlugin({ provider: 'memory', ttl: 100 }))
+
+  it('should work with multiple plugins', async () => {
+    // Test plugin interactions
+  })
+})
+```
+
+## 🚀 Best Practices
+
+### 1. Plugin Design Principles
+
+- **Single Responsibility**: Each plugin should have a clear, focused purpose
+- **Minimal Dependencies**: Avoid heavy dependencies when possible
+- **Configuration**: Make plugins configurable rather than hardcoded
+- **Error Handling**: Graceful error handling and fallbacks
+- **Logging**: Proper logging for debugging and monitoring
+
+### 2. Performance Considerations
+
+```typescript
+// Good: Lazy loading of heavy dependencies
+export const createDatabasePlugin = (config: DatabaseConfig) => {
+  let db: Database | null = null
+
+  return {
+    name: 'database',
+    setup: async () => {
+      if (!db) {
+        db = await import('./database').then(m => m.connect(config))
+      }
+      return { db }
+    }
+  }
+}
+
+// Good: Efficient middleware
+export const createAuthPlugin = () => new Elysia()
+  .derive(({ headers }) => {
+    // Only parse token if Authorization header exists
+    const auth = headers.authorization
+    return auth ? { user: parseToken(auth) } : { user: null }
+  })
+```
+
+### 3. Type Safety
+
+```typescript
+// Define strong types for plugin configuration
+export interface DatabasePluginConfig {
+  readonly url: string
+  readonly poolSize?: number
+  readonly ssl?: boolean
+  readonly timeout?: number
+}
+
+// Use branded types for better type safety
+type UserId = string & { readonly brand: unique symbol }
+type DatabaseConnection = object & { readonly brand: unique symbol }
+
+export const createDatabasePlugin = (
+  config: DatabasePluginConfig
+): FluxStackPlugin<{ db: DatabaseConnection }> => {
+  // Implementation with strong typing
+}
+```
+
+## 📚 Plugin Examples
+
+### Real-world Plugin Examples
+
+See the built-in plugins for reference:
+- **Logger Plugin**: `core/plugins/built-in/logger/index.ts`
+- **Swagger Plugin**: `core/plugins/built-in/swagger/index.ts`  
+- **Static Plugin**: `core/plugins/built-in/static/index.ts`
+- **Vite Plugin**: `core/plugins/built-in/vite/index.ts`
+- **Monitoring Plugin**: `core/plugins/built-in/monitoring/index.ts`
+
+## 🎯 Summary
+
+FluxStack's plugin system provides:
+
+1. **🔌 Easy Integration**: Simple API for adding functionality
+2. **🎨 Flexible Architecture**: Support for various plugin patterns
+3. **⚡ Performance**: Efficient plugin loading and execution
+4. **🔒 Type Safety**: Full TypeScript support
+5. **🧪 Testability**: Easy unit and integration testing
+6. **📦 Built-in Plugins**: Ready-to-use common functionality
+
+Start with built-in plugins, then create custom ones as your application grows!
+
+---
+
+**Need help with plugins? Check the troubleshooting guide or FluxStack documentation.**

package/create-fluxstack.ts

@@ -43,7 +43,7 @@ program
       process.exit(1)
     }
     
-    console.log(chalk.cyan(`\\n🚀 Creating FluxStack project: ${chalk.bold(projectName)}`))
+    console.log(chalk.cyan(`\n🚀 Creating FluxStack project: ${chalk.bold(projectName)}`))
     console.log(chalk.gray(`📁 Location: ${projectPath}`))
     
     // Create project directory
@@ -160,10 +160,57 @@ ${projectName}/
 - **🎨 Modern UI** - React 19 + Tailwind CSS v4
 - **📋 Auto Documentation** - Swagger UI generated
 - **🔄 Hot Reload** - Backend + Frontend
+- **🔌 Plugin System** - Extensible with custom plugins
+
+## 🔌 Adding Plugins
+
+### Built-in Plugins
+FluxStack includes several built-in plugins that are ready to use:
+
+\`\`\`typescript
+// app/server/index.ts
+import { loggerPlugin, swaggerPlugin, staticPlugin } from "@/core/server"
+
+// Add built-in plugins
+app.use(loggerPlugin)
+app.use(swaggerPlugin)
+\`\`\`
+
+### Custom Plugin Example
+
+\`\`\`typescript
+// app/server/plugins/auth.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' }
+      }
+    }
+  })
+
+// Use in app/server/index.ts
+import { authPlugin } from './plugins/auth'
+app.use(authPlugin)
+\`\`\`
+
+### Available Plugin Hooks
+- \`setup\` - Initialize plugin resources
+- \`onServerStart\` - Run when server starts
+- \`onRequest\` - Process incoming requests
+- \`onResponse\` - Process outgoing responses
+- \`onError\` - Handle errors
 
 ## 📖 Learn More
 
-Visit the [FluxStack Documentation](https://fluxstack.dev) to learn more!
+- **Plugin Guide**: Check \`ai-context/development/plugins-guide.md\`
+- **FluxStack Docs**: Visit the [FluxStack Repository](https://github.com/MarcosBrendonDePaula/FluxStack)
 
 ---
 
@@ -230,15 +277,15 @@ Built with ❤️ using FluxStack
       }
       
       // Success message
-      console.log(chalk.green('\\n🎉 Project created successfully!'))
-      console.log(chalk.cyan('\\nNext steps:'))
+      console.log(chalk.green('\n🎉 Project created successfully!'))
+      console.log(chalk.cyan('\nNext steps:'))
       console.log(chalk.white(`  cd ${projectName}`))
       if (!options.install) {
         console.log(chalk.white(`  bun install`))
       }
       console.log(chalk.white(`  bun run dev`))
-      console.log(chalk.magenta('\\nHappy coding with the divine Bun runtime! ⚡🔥'))
-      console.log(chalk.gray('\\nVisit http://localhost:3000 when ready!'))
+      console.log(chalk.magenta('\nHappy coding with the divine Bun runtime! ⚡🔥'))
+      console.log(chalk.gray('\nVisit http://localhost:3000 when ready!'))
       
     } catch (error) {
       spinner.fail('❌ Failed to create project')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-fluxstack",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "description": "⚡ Modern full-stack TypeScript framework with Elysia + React + Bun",
   "keywords": ["framework", "full-stack", "typescript", "elysia", "react", "bun", "vite"],
   "author": "FluxStack Team",