⚡ KodeX

Ultra-fast React fullstack framework with Vite, SSR, and intelligent SEO by plusKode.

KodeX combines the best of Next.js SSR, Astro SEO, and Remix DX — all powered by Vite's blazing-fast build system.

🌐 Official Documentation

✨ Features

⚙️ Core Architecture

• Vite-based Runtime — Ultra-fast dev server, HMR, and build pipeline
• File-Based Routing — Automatic routes from /src/pages/*.{ts,tsx,js,jsx}
• API Routing — File-based like Next.js (/src/api/*.{ts,js})
• Universal SSR/CSR — Auto-detects render mode based on code
• Auto Hydration — SSR output hydrated client-side seamlessly
• Multiple Adapters — Express, Edge (Cloudflare/Vercel), or Bun

🧠 Metadata & SEO Engine

• Static & Async Metadata — export async function metadata()
• SSR Metadata Injection — Runs server-side even for CSR components
• Inheritance System — Parent layout SEO inherited by children
• Global SEO Defaults — From /config/seo.config.ts
• Dynamic Metadata Fetch — Server fetch via fetchMeta() helper
• Structured Data — JSON-LD support built-in
• SEO Modal — Live SEO completeness checker in dev mode
• CLI SEO Report — Static analysis for all routes

🧱 DX & Productivity

• npx create-hyperroute — Interactive project generator
• TypeScript-first — With JavaScript fallback
• Hot Reload — Instant metadata sync
• Route Manifest Viewer — Dev overlay with route info
• Console Management — Granular control over logging
• Dev Overlay — SEO health, route mode, metadata state
• Rich Error Overlay — Next.js-style error modal with stack traces, code context, and navigation (NEW in v1.0.4)

🔐 Performance & Stability

• Smart Cache System — Memory / File / Edge caching
• ISR Support — Incremental Static Regeneration with revalidate
• Lazy Metadata — Only for active routes
• Prefetching — Preload next route metadata
• Tree-shakable — Unused features dropped from build

🧬 Plugin System

• Vite Plugin Hooks — Extend routing, build, or HMR
• Custom Middleware — Modify req/res globally
• Metadata Hooks — Before/after modify SEO

🚀 Quick Start

Create a New Project

npx create-kodex my-app
cd my-app
npm install
npm run dev

Manual Setup

npm install @pluskode/kodex react react-dom

vite.config.ts:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { kodex } from '@pluskode/kodex/vite';

export default defineConfig({
  plugins: [
    react(),
    kodex({
      config: {
        adapter: 'express',
        devOverlay: true,
      },
    }),
  ],
});

src/pages/index.tsx:

import React from 'react';
import type { Metadata } from '@pluskode/kodex/runtime';

export const metadata: Metadata = {
  title: 'Home - My App',
  description: 'Welcome to my KodeX app',
  keywords: ['react', 'ssr', 'vite'],
  og: {
    title: 'Home',
    description: 'My awesome app',
    image: '/og-image.png',
  },
};

export default function Home() {
  return (
    <div>
      <h1>Welcome to KodeX</h1>
      <p>Ultra-fast React fullstack framework</p>
    </div>
  );
}

Start dev server:

npx kodex dev

📚 Documentation

File-Based Routing

Routes are automatically generated from the /src/pages directory:

src/pages/
├── index.tsx           → /
├── about.tsx           → /about
├── blog/
│   ├── index.tsx       → /blog
│   └── [slug].tsx      → /blog/:slug
└── users/
    └── [id]/
        └── profile.tsx → /users/:id/profile

API Routes

API routes work the same way in /src/api:

src/api/
├── hello.ts            → /api/hello
└── users/
    └── [id].ts         → /api/users/:id

Example API route:

export default async function handler({ req, res, params, query }) {
  const userId = params.id;
  const user = await fetchUser(userId);
  res.json({ user });
}

Metadata System

Static metadata:

export const metadata: Metadata = {
  title: 'My Page',
  description: 'Page description',
};

Async metadata:

export async function metadata() {
  const data = await fetchMeta('/api/seo-data');
  return {
    title: data.title,
    description: data.description,
  };
}

Dynamic with ISR:

export async function metadata() {
  const post = await fetchPost();
  return {
    title: post.title,
    description: post.excerpt,
    revalidate: 60, // Revalidate every 60 seconds
  };
}

Middleware

Global middleware (src/middleware/_global.ts):

export default async function middleware({ req, res, next }) {
  console.log(`Request: ${req.method} ${req.url}`);
  await next();
}

Route-specific middleware (src/middleware/admin/_middleware.ts):

export default async function authMiddleware({ req, res, next }) {
  const token = req.headers.authorization;
  if (!token) {
    return res.status(401).json({ error: 'Unauthorized' });
  }
  await next();
}

Console Management

Configure in kodex.config.ts:

import { defineConfig } from '@pluskode/kodex';

export default defineConfig({
  console: {
    mode: 'filtered', // 'normal' | 'silent' | 'filtered'
    contexts: {
      ssr: true,
      csr: true,
      api: false, // Mute API logs
    },
    methods: {
      debug: false, // Disable debug logs
    },
    filters: [
      /password/i, // Filter out logs with "password"
      /secret/i,
    ],
    logToFile: true,
    logFilePath: 'logs/app.log',
  },
});

Toggle console in dev (Ctrl+Shift+L):

import { setupConsoleToggle } from '@pluskode/kodex/runtime';

setupConsoleToggle(); // In your app entry

Server Adapters

Express:

import { createExpressAdapter } from '@pluskode/kodex/server';

const { app, listen } = createExpressAdapter({
  config: {
    ssr: true,
  },
  port: 3000,
});

listen();

Edge (Cloudflare Workers):

import { createEdgeAdapter } from '@pluskode/kodex/server';

export default createEdgeAdapter({
  config: { ssr: true },
});

Bun:

import { createBunAdapter } from '@pluskode/kodex/server';

const { fetch } = createBunAdapter({ port: 3000 });

Bun.serve({
  port: 3000,
  fetch,
});

🛠️ CLI Commands

# Development
npx kodex dev [--port 3000] [--host localhost]

# Build
npx kodex build [--ssr] [--ssg]

# Preview
npx kodex preview [--port 4173]

# SEO Report
npx kodex seo:report [--output report.json] [--strict]

# Generate Types
npx kodex typegen [--output .kodex/routes.d.ts]

📦 Configuration

kodex.config.ts:

import { defineConfig } from '@pluskode/kodex';

export default defineConfig({
  // Core
  basePath: '/',
  trailingSlash: false,

  // Rendering
  ssr: 'auto',
  adapter: 'express',

  // SEO
  seo: {
    defaultMetadata: {
      author: 'Your Name',
      keywords: ['react', 'hyperroute'],
    },
    strictMode: true, // Fail build on missing SEO
    enableSEOModal: true,
  },

  // Cache
  cache: {
    enabled: true,
    type: 'memory',
    ttl: 60000,
  },

  // Plugins
  plugins: [
    // Your custom plugins
  ],
});

🎨 Example Templates

Minimal

npx create-kodex my-app --template minimal

Blog

npx create-kodex my-blog --template blog

Dashboard

npx create-kodex my-dashboard --template dashboard

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide.

📄 License

MIT © plusKode Team

🔗 Links

• Documentation
• GitHub
• NPM Package
• plusKode Website

Built with ❤️ by plusKode using Vite, React, and TypeScript.