@flexireact/core 4.0.0 → 4.1.1

package/README.md

@@ -1,496 +1,80 @@
-<p align="center">
-  <img src="./assets/flexireact.webp" alt="FlexiReact Logo" width="400" />
-</p>
-
-<h1 align="center">⚡ FlexiReact v4</h1>
-
-<p align="center">
-  <strong>The Future of React Development</strong>
-</p>
-
-<p align="center">
-  The Modern React Framework - Better than Next.js with TypeScript, Tailwind CSS, SSR, SSG, Islands, Edge Runtime, and 50+ UI components.<br/>
-  <b>Better than Next.js.</b> Simpler. Faster. More powerful.
-</p>
-
-<p align="center">
-  <a href="https://www.npmjs.com/package/@flexireact/core"><img src="https://img.shields.io/npm/v/@flexireact/core.svg?color=00FF9C" alt="npm version" /></a>
-  <a href="https://www.npmjs.com/package/@flexireact/core"><img src="https://img.shields.io/npm/dm/@flexireact/core.svg?color=00FF9C" alt="npm downloads" /></a>
-  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-00FF9C.svg" alt="License: MIT" /></a>
-  <a href="#"><img src="https://img.shields.io/badge/TypeScript-Native-blue.svg" alt="TypeScript Native" /></a>
-</p>
-
-<p align="center">
-  <a href="#-quick-start">Quick Start</a> •
-  <a href="#-features">Features</a> •
-  <a href="#-cli-commands">CLI</a> •
-  <a href="#-flexi-ui">FlexiUI</a> •
-  <a href="#-devtools">DevTools</a>
-</p>
+<div align="center">
 
----
-
-## 🚀 Quick Start
-
-```bash
-# Create a new project
-npx create-flexireact my-app
-
-# Or with a specific template
-npx create-flexireact my-app --template app-router
-
-# Start development
-cd my-app
-npm run dev
-```
-
-Open [http://localhost:3000](http://localhost:3000) 🎉
-
----
-
-## 🆕 What's New in v4
-
-### v4.0.0 — React 19 Native Edition
-- **⚛️ React 19 Native** — Full support for React 19 (Actions, `useActionState`, `useOptimistic`, `useFormStatus`, `use()`)
-- **🚀 Enhanced Actions** — Simplified server action handling with native React 19 primitives
-- **🔄 Improved Hydration** — Leveraging React 19 `onRecoverableError` for better error resilience
-- **📦 New Hooks API** — Centralized `core/hooks` module for React 19 + FlexiReact utilities
-- **⚡ Version 4.0** — Major release with stability improvements and updated CLI templates
-
-## ✨ Features
-
-### 🏗️ Core Framework
-
-| Feature | Description |
-|---------|-------------|
-| 📘 **TypeScript First** | Full TypeScript support with strict type checking and excellent DX |
-| ⚡ **Lightning Fast** | Powered by esbuild for instant builds and sub-second HMR |
-| 📁 **File-based Routing** | Create a file in `pages/`, get a route automatically |
-| 🏝️ **Islands Architecture** | Partial hydration for minimal JavaScript and maximum performance |
-| 🖥️ **SSR / SSG / ISR** | Server-side rendering, static generation, and incremental regeneration |
-| 🔌 **API Routes** | Build your REST/GraphQL API alongside your frontend |
-
-### 🧩 Layouts & Components
-
-| Feature | Description |
-|---------|-------------|
-| 📐 **Nested Layouts** | Shared layouts with `_layout.tsx` that persist across navigation |
-| 🎭 **Server Components** | `'use server'` directive for server-only components (zero JS) |
-| 💻 **Client Components** | `'use client'` directive for interactive client-side components |
-| 🎨 **Tailwind CSS** | Pre-configured with beautiful defaults, dark mode, and CSS variables |
-| 🧱 **UI Components** | Button, Card, Modal, Tooltip, Drawer, Table, Input, Skeleton... |
-| ✨ **shadcn/ui Ready** | Compatible component system with CVA variants |
-
-### 📊 Data Fetching & State
-
-| Feature | Description |
-|---------|-------------|
-| 🔄 **getServerSideProps** | Fetch data on every request (SSR) |
-| 📦 **getStaticProps** | Fetch data at build time (SSG) |
-| 🚀 **Prefetch** | Automatic link prefetching for instant navigation |
-| 🔍 **TanStack Query** | Built-in support for useQuery, useMutation, and caching |
-| 🐻 **Zustand / Jotai** | Lightweight state management integration |
-| ⚡ **Optimistic Updates** | Instant UI feedback with `useOptimistic` (React 19) |
-| ⏳ **Suspense Ready** | React Suspense and `use()` hook for async data |
-| 🏗️ **Actions State** | Native `useActionState` and `useFormStatus` support |
-
-### 🛡️ Middleware & Security
-
-| Feature | Description |
-|---------|-------------|
-| � **Middleware System** | Run code before every request (auth, logging, redirects) |
-| 🔐 **Authentication** | Email/password + OAuth (Google, GitHub, Discord) |
-| 👥 **RBAC** | Role-based access control with permissions |
-| 🛡️ **Security** | Built-in CSRF, XSS, CORS protection |
-| ⏱️ **Rate Limiting** | Protect your API from abuse |
-| 📝 **Request Logging** | Structured logging with levels and formatting |
+<img src="./assets/flexireact.webp" alt="FlexiReact Logo" width="280" />
 
-### 🚀 Performance & Build
+# ⚡ FlexiReact v4.1
 
-| Feature | Description |
-|---------|-------------|
-| 📦 **Code Splitting** | Automatic route-based code splitting |
-| 🦥 **Lazy Loading** | Dynamic imports with `React.lazy()` support |
-| 🌳 **Tree Shaking** | Dead code elimination for minimal bundles |
-| 📊 **Bundle Analysis** | Visualize your bundle size with built-in analyzer |
-| �️ **Compression** | Gzip/Brotli compression out of the box |
-| 🖼️ **Image Optimization** | Automatic image resizing, WebP conversion, lazy loading |
+### The Edge-First React Framework
 
-### 🔧 Developer Experience
+[![npm version](https://img.shields.io/npm/v/@flexireact/core.svg?style=flat-square&color=00FF9C&labelColor=0a0a0a)](https://www.npmjs.com/package/@flexireact/core)
+[![npm downloads](https://img.shields.io/npm/dm/@flexireact/core.svg?style=flat-square&color=00FF9C&labelColor=0a0a0a)](https://www.npmjs.com/package/@flexireact/core)
+[![License](https://img.shields.io/badge/license-MIT-00FF9C.svg?style=flat-square&labelColor=0a0a0a)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-native-3178c6.svg?style=flat-square&labelColor=0a0a0a)](https://www.typescriptlang.org/)
 
-| Feature | Description |
-|---------|-------------|
-| 🔥 **Hot Reloading** | Instant updates without losing state |
-| 🐛 **Error Overlay** | Beautiful error messages with stack traces |
-| � **ESLint + Prettier** | Pre-configured linting and formatting |
-| 🎨 **Tailwind IntelliSense** | Full autocomplete for Tailwind classes |
-| 📋 **Multiple Templates** | Starter templates: minimal, blog, dashboard, e-commerce |
-| 🩺 **Doctor Command** | `flexi doctor` to diagnose project issues |
+A modern React framework focused on **performance**, **clarity** and **modern React APIs**.  
+Inspired by Next.js, Remix and Astro — but simpler, lighter and edge-native.
 
-### 🔍 SEO & Analytics
+[Quick Start](#-quick-start) · [Features](#-features) · [Documentation](#-documentation) · [Roadmap](#-roadmap)
 
-| Feature | Description |
-|---------|-------------|
-| 🏷️ **Auto Meta Tags** | Automatic title, description, and canonical URLs |
-| 📱 **Open Graph** | Social media preview cards (Twitter, Facebook, LinkedIn) |
-| 🗺️ **Sitemap** | Auto-generated sitemap.xml for search engines |
-| 📈 **Performance Monitoring** | Core Web Vitals tracking built-in |
-| � **robots.txt** | Configurable robots.txt generation |
-| 📊 **Analytics Ready** | Easy integration with Google Analytics, Plausible, etc. |
-
-### 🔌 Extensibility
-
-| Feature | Description |
-|---------|-------------|
-| 🧩 **Plugin System** | Extend FlexiReact with community plugins |
-| 🎣 **Lifecycle Hooks** | `beforeRender`, `afterRender`, `onError` hooks |
-| 📦 **Custom Templates** | Create and share your own project templates |
-| 🔄 **Migration Tools** | Automatic migration from Next.js, CRA, Vite |
-| ⚙️ **Config API** | Fully customizable `@flexireact/core.config.ts` |
-
----
-
-## 🆚 Why FlexiReact?
-
-| | FlexiReact v3 | Next.js 15 | Remix | Astro |
-|---|:---:|:---:|:---:|:---:|
-| **Zero Config** | ✅ | ⚠️ | ⚠️ | ✅ |
-| **Edge Runtime** | ✅ | ✅ | ⚠️ | ⚠️ |
-| **Islands Architecture** | ✅ | ❌ | ❌ | ✅ |
-| **UI Components** | ✅ 50+ | ❌ | ❌ | ❌ |
-| **CLI Scaffolding** | ✅ | ❌ | ❌ | ❌ |
-| **DevTools** | ✅ | ⚠️ | ⚠️ | ⚠️ |
-| **PPR** | ✅ | ✅ | ❌ | ❌ |
-| **Bundle Size** | 🟢 ~90kb | � ~250kb | 🟡 ~150kb | 🟢 ~50kb |
-| **Build Speed** | 🟢 <1s | 🟡 ~5s | 🟡 ~3s | 🟢 <2s |
+</div>
 
 ---
 
-## 🖥️ CLI Commands
-
-```bash
-# Project
-flexi create <name>       # Create new project
-flexi dev                 # Start dev server (HMR)
-flexi build               # Build for production
-flexi build --analyze     # Build with bundle analysis
-flexi start               # Start production server
-flexi doctor              # Check project health
-
-# Scaffolding (NEW in v3!)
-flexi g page dashboard    # Generate a page
-flexi g component Button  # Generate a component
-flexi g hook useAuth      # Generate a custom hook
-flexi g api users         # Generate an API route
-flexi g action submit     # Generate a server action
-flexi g context theme     # Generate a React context
-flexi g middleware auth   # Generate middleware
-flexi g loading           # Generate loading.tsx
-flexi g error             # Generate error.tsx
-```
-
----
-
-## 🎨 FlexiUI — 50+ Components
-
-FlexiReact includes [@flexireact/flexi-ui](https://www.npmjs.com/package/@flexireact/flexi-ui), a complete UI library:
+## 🚀 Quick Start
 
 ```bash
-npm install @flexireact/flexi-ui
-```
-
-```tsx
-import { Button, Card, Input, Modal, Toast } from '@flexireact/flexi-ui';
-```
-
-### Available Components
-
-| Category | Components |
-|----------|------------|
-| **Form** | Button, Input, Textarea, Checkbox, Switch, Select, Slider, Radio, Toggle, Rating, DatePicker, FileUpload |
-| **Layout** | Stack, Separator, AspectRatio, ScrollArea, Resizable |
-| **Navigation** | Tabs, Breadcrumb, Pagination, Menubar, Navbar, Sidebar, Stepper |
-| **Data** | Card, Badge, Avatar, Table, Accordion, Calendar, Timeline, Stat, Code, Carousel |
-| **Feedback** | Alert, Toast, Spinner, Skeleton, Progress, Empty |
-| **Overlay** | Modal, Dialog, Drawer, Sheet, Dropdown, Popover, HoverCard, ContextMenu, Command, Collapsible |
-
----
-
-## 🔧 DevTools
-
-Built-in development tools (press `Ctrl+Shift+D`):
-
-```tsx
-import { DevToolsOverlay } from '@flexireact/core';
-
-// In your layout
-{process.env.NODE_ENV === 'development' && <DevToolsOverlay />}
+npx create-flexireact my-app
+cd my-app
+npm run dev
 ```
 
-Features:
-- 🗺️ **Routes** — Navigation history and params
-- 🧩 **Components** — Render counts, props, Islands detection
-- 🌐 **Network** — Fetch/XHR/Actions monitoring
-- 📊 **Performance** — Core Web Vitals (LCP, FID, CLS, TTFB)
-- 📝 **Console** — Centralized logs
+Open [http://localhost:3000](http://localhost:3000) and start building! 🎉
 
 ---
 
-## 🌐 Edge Runtime
-
-Deploy anywhere with universal edge support:
-
-```tsx
-import { createEdgeHandler, detectRuntime } from '@flexireact/core';
-
-// Automatic runtime detection
-const runtime = detectRuntime();
-// → 'node' | 'bun' | 'deno' | 'cloudflare' | 'vercel-edge' | 'netlify-edge'
+## ✨ Why FlexiReact?
 
-// Universal handler
-const handler = createEdgeHandler({
-  routes: [...],
-  middleware: [...],
-});
-
-export default handler;
-```
-
----
-
-## ⚡ Smart Caching
-
-```tsx
-import { smartCache } from '@flexireact/core';
+FlexiReact is for developers who want:
 
-const cache = smartCache({
-  backend: 'auto', // auto-detect: memory, KV, Redis
-  defaultTTL: 60,
-  staleWhileRevalidate: true,
-});
-
-// Cache with tags
-await cache.set('user:123', userData, { 
-  ttl: 300, 
-  tags: ['users'] 
-});
-
-// Invalidate by tag
-await cache.invalidateTag('users');
-```
-
----
-
-## 🎯 Partial Prerendering (PPR)
-
-Static shell + streaming dynamic content:
-
-```tsx
-import { withPPR, DynamicBoundary } from '@flexireact/core';
-
-export default withPPR(function Page() {
-  return (
-    <div>
-      {/* Static - rendered at build time */}
-      <Header />
-      <Sidebar />
-      
-      {/* Dynamic - streamed at request time */}
-      <DynamicBoundary fallback={<Skeleton />}>
-        <UserDashboard />
-      </DynamicBoundary>
-    </div>
-  );
-});
-```
+| Feature | Description |
+|---------|-------------|
+| ⚛️ **Modern React** | React 19, Server Components, Server Actions, Suspense |
+| 🏝️ **Islands** | Partial hydration — zero JS for static content |
+| ⚡ **Edge-First** | Runs on Node, Bun, Deno, Cloudflare Workers |
+| 📁 **File Routing** | Three conventions: `routes/`, `app/`, `pages/` |
+| 🎯 **Explicit** | No hidden caching, no magic behavior |
 
 ---
 
-## 📁 Project Structure
-
-FlexiReact v2 introduces a new `routes/` directory with enhanced routing capabilities:
-
-```
-myapp/
-├── app/                        # App directory (layout, components, styles)
-│   ├── components/
-│   │   ├── ui/                 # UI components (Button, Card, etc.)
-│   │   └── layout/             # Layout components (Navbar, Footer)
-│   ├── styles/
-│   │   └── globals.css         # Global styles + Tailwind v4
-│   ├── providers/              # React context providers
-│   └── layout.tsx              # Root layout
-├── routes/                     # FlexiReact v3 file-based routing
-│   ├── (public)/               # Route groups (don't affect URL)
-│   │   ├── home.tsx            # → /
-│   │   └── about.tsx           # → /about
-│   ├── blog/
-│   │   ├── index.tsx           # → /blog
-│   │   └── [slug].tsx          # → /blog/:slug
-│   └── api/
-│       └── hello.ts            # → /api/hello
-├── lib/                        # Utilities
-│   └── utils.ts
-├── public/                     # Static assets
-├── tsconfig.json               # TypeScript configuration
-├── flexireact.config.ts        # FlexiReact configuration
-└── package.json
-```
-
-## 🛣️ Routing (v2)
-
-FlexiReact v2 supports three routing conventions (in priority order):
-
-### 1. Routes Directory (Recommended)
-
-| File | Route |
-|------|-------|
-| `routes/(public)/home.tsx` | `/` |
-| `routes/(public)/about.tsx` | `/about` |
-| `routes/blog/index.tsx` | `/blog` |
-| `routes/blog/[slug].tsx` | `/blog/:slug` |
-| `routes/[...path].tsx` | Catch-all route |
-| `routes/api/hello.ts` | `/api/hello` |
-
-### 2. App Directory (Next.js style)
-
-| File | Route |
-|------|-------|
-| `app/page.tsx` | `/` |
-| `app/about/page.tsx` | `/about` |
-| `app/blog/[slug]/page.tsx` | `/blog/:slug` |
-
-### 3. Pages Directory (Legacy)
-
-| File | Route |
-|------|-------|
-| `pages/index.tsx` | `/` |
-| `pages/about.tsx` | `/about` |
-
-### Dynamic Routes
-
-```tsx
-// routes/blog/[slug].tsx
-export default function BlogPost({ params }: { params: { slug: string } }) {
-  return <h1>Post: {params.slug}</h1>;
-}
-```
-
-### Route Groups
-
-Use parentheses to group routes without affecting the URL:
-
-```
-routes/
-  (public)/
-    home.tsx       # → /
-    about.tsx      # → /about
-  (dashboard)/
-    settings.tsx   # → /settings
-```
-
-## 📐 Layouts
+## 🧩 Features
 
-Create layouts in `app/layout.tsx` or within route directories:
+### ⚛️ React 19 Native
 
 ```tsx
-// app/layout.tsx
-import { Navbar } from './components/layout/Navbar';
-import { Footer } from './components/layout/Footer';
-
-export default function RootLayout({ children }: { children: React.ReactNode }) {
-  return (
-    <html lang="en" className="dark">
-      <head>
-        <link rel="stylesheet" href="/styles.css" />
-      </head>
-      <body className="bg-background text-foreground">
-        <Navbar />
-        <main>{children}</main>
-        <Footer />
-      </body>
-    </html>
-  );
+// Server Component (default)
+export default async function Page() {
+  const data = await db.query('SELECT * FROM posts');
+  return <PostList posts={data} />;
 }
 ```
 
-## ⏳ Loading & Error States
-
 ```tsx
-// routes/loading.tsx
-export default function Loading() {
-  return (
-    <div className="flex items-center justify-center min-h-screen">
-      <div className="w-8 h-8 border-2 border-primary border-t-transparent rounded-full animate-spin" />
-    </div>
-  );
-}
-
-// routes/error.tsx
-export default function Error({ error, reset }: { error: Error; reset: () => void }) {
-  return (
-    <div className="flex flex-col items-center justify-center min-h-screen">
-      <h1 className="text-4xl font-bold text-red-500">Something went wrong</h1>
-      <p className="text-gray-400 mt-4">{error.message}</p>
-      <button onClick={reset} className="mt-8 px-6 py-3 bg-primary text-black rounded-lg">
-        Try again
-      </button>
-    </div>
-  );
-}
-```
-
-## 🔄 Data Fetching
-
-### Server-Side Rendering (SSR)
-
-```jsx
-export async function getServerSideProps({ params, req }) {
-  const data = await fetchData(params.id);
-  
-  if (!data) {
-    return { notFound: true };
-  }
-  
-  return { props: { data } };
-}
-
-export default function Page({ data }) {
-  return <div>{data.title}</div>;
-}
-```
-
-### Static Site Generation (SSG)
-
-```jsx
-// For dynamic routes
-export async function getStaticPaths() {
-  return {
-    paths: [
-      { params: { slug: 'hello' } },
-      { params: { slug: 'world' } }
-    ],
-    fallback: false
-  };
-}
-
-export async function getStaticProps({ params }) {
-  const post = await getPost(params.slug);
-  return { props: { post } };
+'use client';
+// Client Component
+export function LikeButton() {
+  const [liked, setLiked] = useState(false);
+  return <button onClick={() => setLiked(!liked)}>❤️</button>;
 }
 ```
 
-## 🏝️ Islands Architecture
+### 🏝️ Islands Architecture
 
-Islands allow partial hydration — only interactive components load JavaScript:
+Only hydrate what needs interactivity:
 
-```jsx
+```tsx
 'use island';
 
-import { useState } from 'react';
-
-// This component will be hydrated on the client
-export default function Counter() {
+export function Counter() {
   const [count, setCount] = useState(0);
   return (
     <button onClick={() => setCount(c => c + 1)}>
@@ -500,390 +84,183 @@ export default function Counter() {
 }
 ```
 
-Static content around islands remains as pure HTML with zero JavaScript.
-
-## 🖥️ React Server Components
+### 📁 File-Based Routing
 
-Mark components to run only on the server:
-
-```jsx
-'use server';
-
-// This component never ships to the client
-export default async function ServerData() {
-  const data = await db.query('SELECT * FROM users');
-  return <UserList users={data} />;
-}
 ```
-
-Mark client components explicitly:
-
-```jsx
-'use client';
-
-// This component will be hydrated
-export default function InteractiveWidget() {
-  // Client-side interactivity here
-}
+routes/
+├── home.tsx           → /
+├── about.tsx          → /about
+├── blog/
+│   ├── index.tsx      → /blog
+│   └── [slug].tsx     → /blog/:slug
+└── api/
+    └── users.ts       → /api/users
 ```
 
-## 🔌 API Routes
-
-```js
-// pages/api/users.js
+### 🔌 API Routes
 
-export function get(req, res) {
-  res.json({ users: [] });
+```ts
+// routes/api/users.ts
+export async function GET() {
+  return Response.json({ users: await getUsers() });
 }
 
-export function post(req, res) {
-  const { name } = req.body;
-  res.status(201).json({ id: 1, name });
+export async function POST(req: Request) {
+  const body = await req.json();
+  return Response.json({ created: true });
 }
 ```
 
-## ⚡ Server Actions (v2.2+)
-
-Call server functions directly from client components:
+### 🛡️ Middleware
 
-```tsx
-// actions.ts
-'use server';
-import { serverAction, redirect, cookies } from '@flexireact/core';
-
-export const createUser = serverAction(async (formData: FormData) => {
-  const name = formData.get('name') as string;
-  const user = await db.users.create({ name });
-  
-  // Set a cookie
-  cookies.set('userId', user.id);
-  
-  // Redirect after action
-  redirect('/users');
-});
-
-// Form.tsx
-'use client';
-import { createUser } from './actions';
-
-export function CreateUserForm() {
-  return (
-    <form action={createUser}>
-      <input name="name" placeholder="Name" required />
-      <button type="submit">Create User</button>
-    </form>
-  );
+```ts
+// middleware.ts
+export default function middleware(request) {
+  if (!request.headers.get('authorization')) {
+    return Response.redirect('/login');
+  }
 }
-```
-
-## 🔗 Link with Prefetching (v2.1+)
-
-Enhanced Link component with automatic prefetching:
-
-```tsx
-import { Link } from '@flexireact/core/client';
-
-// Prefetch on hover (default)
-<Link href="/about">About</Link>
 
-// Prefetch when visible in viewport
-<Link href="/products" prefetch="viewport">Products</Link>
-
-// Replace history instead of push
-<Link href="/login" replace>Login</Link>
-
-// Programmatic navigation
-import { useRouter } from '@flexireact/core/client';
-
-function MyComponent() {
-  const router = useRouter();
-  
-  return (
-    <button onClick={() => router.push('/dashboard')}>
-      Go to Dashboard
-    </button>
-  );
-}
+export const config = {
+  matcher: ['/dashboard/:path*']
+};
 ```
 
-## 🛠️ Server Helpers (v2.1+)
-
-Utility functions for server-side operations:
-
-```tsx
-import { redirect, notFound, json, cookies, headers } from '@flexireact/core';
-
-// Redirect
-redirect('/dashboard');
-redirect('/login', 'permanent'); // 308 redirect
+---
 
-// Not Found
-notFound(); // Throws 404
+## 🖥️ Rendering Modes
 
-// JSON Response (in API routes)
-return json({ data: 'hello' }, { status: 200 });
+| Mode | Description |
+|------|-------------|
+| **SSR** | Server-side rendering (default) |
+| **SSG** | Static generation at build time |
+| **ISR** | Incremental Static Regeneration |
+| **Streaming** | Progressive HTML rendering |
 
-// Cookies
-const token = cookies.get(request, 'token');
-const setCookie = cookies.set('session', 'abc123', { 
-  httpOnly: true, 
-  maxAge: 86400 
-});
+```tsx
+// Enable ISR with revalidation
+export const revalidate = 60; // seconds
 
-// Headers
-const auth = headers.bearerToken(request);
-const corsHeaders = headers.cors({ origin: '*' });
-const securityHeaders = headers.security();
+export default function Page() {
+  return <div>This page revalidates every 60s</div>;
+}
 ```
 
-## 🛡️ Middleware
+---
 
-### Global Middleware
+## 🛠️ CLI
 
-Create `middleware.ts` in your project root:
+```bash
+# Create & Run
+npx create-flexireact my-app    # Create new project
+flexi dev                        # Development server
+flexi build                      # Production build
+flexi start                      # Start production server
 
-```ts
-import { redirect, cookies } from '@flexireact/core';
+# Scaffolding
+flexi g page dashboard           # Generate page
+flexi g component Button         # Generate component
+flexi g api users                # Generate API route
 
-export default function middleware(request) {
-  // Protect routes
-  if (request.pathname.startsWith('/admin')) {
-    const token = cookies.get(request, 'token');
-    if (!token) {
-      redirect('/login');
-    }
-  }
-}
-
-export const config = {
-  matcher: ['/admin/:path*', '/api/:path*']
-};
+# Utilities
+flexi doctor                     # Diagnose issues
+flexi upgrade                    # Upgrade FlexiReact
 ```
 
-### Route Middleware (v2.1+)
+---
 
-Create `_middleware.ts` in any route directory:
+## ⚙️ Configuration
 
-```
-routes/
-  admin/
-    _middleware.ts   # Runs for all /admin/* routes
-    dashboard.tsx
-    settings.tsx
-```
+Create a `flexireact.config.ts` in your project root:
 
 ```ts
-// routes/admin/_middleware.ts
-export default async function middleware(req, res, { route, params }) {
-  const user = await getUser(req);
-  
-  if (!user?.isAdmin) {
-    return { redirect: '/login' };
-  }
-  
-  // Continue to route
-  return { user };
-}
-```
+// flexireact.config.ts
+import { defineConfig } from '@flexireact/core/config';
 
-## 🔧 Configuration
+export default defineConfig({
+  // Directories
+  pagesDir: 'pages',
+  layoutsDir: 'layouts',
+  publicDir: 'public',
+  outDir: '.flexi',
 
-Create `flexireact.config.js`:
-
-```js
-export default {
+  // Server
   server: {
     port: 3000,
     host: 'localhost'
   },
-  
+
+  // Build
   build: {
     target: 'es2022',
     minify: true,
     sourcemap: true
   },
-  
+
+  // Features
   islands: {
     enabled: true
   },
-  
   rsc: {
     enabled: true
   },
-  
   ssg: {
     enabled: false,
     paths: []
-  },
-  
-  plugins: []
-};
-```
-
-## 🧩 Plugins
-
-Create `flexireact.plugin.js`:
-
-```js
-export default {
-  name: 'my-plugin',
-  
-  onServerStart(server) {
-    console.log('Server started!');
-  },
-  
-  onBeforeRender(page, props) {
-    return { ...props, injected: true };
-  },
-  
-  onAfterRender(html) {
-    return html.replace('</head>', '<script>...</script></head>');
   }
-};
-```
-
-### Built-in Plugins
-
-```js
-import { builtinPlugins } from '@flexireact/core';
-
-export default {
-  plugins: [
-    builtinPlugins.analytics({ trackingId: 'UA-XXX' }),
-    builtinPlugins.pwa({ manifest: '/manifest.json' }),
-    builtinPlugins.securityHeaders()
-  ]
-};
-```
-
-## 🖥️ CLI Commands
-
-```bash
-flexi create <name>      # Create new project
-flexi dev                # Start dev server
-flexi build              # Build for production
-flexi build --analyze    # Build with bundle analysis
-flexi start              # Start production server
-flexi doctor             # Check project health
-flexi --version          # Show version
-flexi help               # Show help
-```
-
-### Bundle Analysis (v2.1+)
-
-```bash
-flexi build --analyze
-```
-
-Output:
-```
-📊 Bundle Analysis:
-
-  ─────────────────────────────────────────────────
-  File                                   Size
-  ─────────────────────────────────────────────────
-  client/main.js                         45.2 KB (13.56 KB gzip)
-  client/vendor.js                       120.5 KB (38.2 KB gzip)
-  server/pages.js                        12.3 KB
-  ─────────────────────────────────────────────────
-  Total:                                 178 KB
-  Gzipped:                               51.76 KB
-```
-
-## 🌊 Streaming SSR (v2.2+)
-
-Progressive HTML rendering with React 18:
-
-```tsx
-import { renderPageStream, streamToResponse } from '@flexireact/core';
-
-// In your server handler
-const { stream, shellReady } = await renderPageStream({
-  Component: MyPage,
-  props: { data },
-  loading: LoadingSpinner,
-  error: ErrorBoundary,
-  title: 'My Page',
-  styles: ['/styles.css']
 });
-
-// Wait for shell (initial HTML) to be ready
-await shellReady;
-
-// Stream to response
-res.setHeader('Content-Type', 'text/html');
-streamToResponse(res, stream);
 ```
 
-Benefits:
-- **Faster Time to First Byte (TTFB)** — Send HTML as it's ready
-- **Progressive Loading** — Users see content immediately
-- **Suspense Support** — Loading states stream in as data resolves
-- **Better UX** — No blank screen while waiting for data
-
-## 📚 Concepts Explained
+Configuration is validated with Zod. Invalid options will show clear error messages.
 
-### React Server Components (RSC)
-
-RSC allows components to execute exclusively on the server:
-- **Zero client JavaScript** for server components
-- **Direct database/filesystem access** in components
-- **Smaller bundles** — server code never ships to client
-- **Better security** — sensitive logic stays on server
-
-### Static Site Generation (SSG)
-
-SSG pre-renders pages at build time:
-- **Fastest possible loads** — pages are static HTML
-- **CDN cacheable** — serve from edge locations
-- **SEO friendly** — full HTML for crawlers
-- **Incremental regeneration** — update without full rebuild
+---
 
-### Islands Architecture
+## 📦 Packages
 
-Islands provide partial hydration:
-- **Minimal JavaScript** — only interactive parts hydrate
-- **Progressive enhancement** — works without JS
-- **Better performance** — less code to parse/execute
-- **Selective loading** — hydrate on visibility, interaction, etc.
+| Package | Description |
+|---------|-------------|
+| [`@flexireact/core`](https://www.npmjs.com/package/@flexireact/core) | Core framework |
+| [`create-flexireact`](https://www.npmjs.com/package/create-flexireact) | Project scaffolding CLI |
+| `@flexireact/flexi-ui` | UI component library (coming soon) |
 
 ---
 
-## 📋 Requirements
+## 🛣️ Roadmap
 
-- Node.js 18+
-- React 18+
-
-## 📦 Packages
+### v4.x (Current)
+- [x] React 19 support
+- [x] Islands architecture
+- [x] File-based routing (3 conventions)
+- [x] SSR / SSG / ISR
+- [x] Middleware system
+- [ ] Plugin system v1
+- [ ] Image optimization
 
-| Package | Version | Description |
-|---------|---------|-------------|
-| [flexireact](https://www.npmjs.com/package/flexireact) | ![npm](https://img.shields.io/npm/v/@flexireact/core?color=00FF9C) | Core framework |
-| [@flexireact/flexi-ui](https://www.npmjs.com/package/@flexireact/flexi-ui) | ![npm](https://img.shields.io/npm/v/@flexireact/flexi-ui?color=00FF9C) | UI components |
-| [create-flexireact](https://www.npmjs.com/package/create-flexireact) | ![npm](https://img.shields.io/npm/v/create-flexireact?color=00FF9C) | Project scaffolding |
+### v5 (Future)
+- [ ] Unified compiler pipeline
+- [ ] First-class plugin ecosystem
+- [ ] Advanced DevTools
+- [ ] Partial Prerendering (PPR)
 
-## 🔗 Links
+---
 
-- [GitHub Repository](https://github.com/flexireact/flexireact)
-- [FlexiUI Repository](https://github.com/flexireact/flexi-ui)
-- [npm Package](https://www.npmjs.com/package/@flexireact/core)
-- [Discord Community](https://discord.gg/rFSZxFtpAA) 💬
-- [Issues](https://github.com/flexireact/flexireact/issues)
+## 🤝 Contributing
 
-## 🙏 Contributing
+FlexiReact is open-source and community-driven.  
+Contributions, feedback and discussions are welcome!
 
-Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) first.
+---
 
 ## 📄 License
 
-MIT © [FlexiReact Team](https://github.com/flexireact)
+MIT © FlexiReact Team
 
 ---
 
-<p align="center">
-  <b>Built with ❤️ by the FlexiReact Team</b>
-</p>
+<div align="center">
+
+**Built with ❤️ for developers who value clarity and performance.**
+
+[⬆ Back to top](#-flexireact-v41)
 
-<p align="center">
-  <a href="https://github.com/flexireact/flexireact">⭐ Star us on GitHub</a>
-</p>
+</div>