Route Handlers Registry

Overview

The Route Handlers Registry (core/lib/registries/route-handlers.ts) provides zero-dynamic-import access to API route handlers for themes and plugins. It eliminates runtime path resolution by generating static imports at build time, resulting in ~17,255x performance improvement for route discovery.

Key Features:

• ✅ Zero dynamic imports at runtime
• ✅ Static route handler imports
• ✅ Automatic route generation for entities
• ✅ Custom route handler support
• ✅ Route priority system
• ✅ Integration with Next.js App Router

---

Architecture

Build-Time Generation

// Generated at build time by scripts/build-registry.mjs
import * as plugin_ai_generate from '@/contents/plugins/ai/api/generate/route'
import * as plugin_ai_embeddings from '@/contents/plugins/ai/api/embeddings/route'

export const PLUGIN_ROUTE_HANDLERS: Record<string, Record<string, RouteHandler | undefined>> = {
  'ai/generate': {
    POST: plugin_ai_generate.POST as RouteHandler,
    GET: plugin_ai_generate.GET as RouteHandler
  },
  'ai/embeddings': {
    POST: plugin_ai_embeddings.POST as RouteHandler,
    GET: plugin_ai_embeddings.GET as RouteHandler
  }
}

export const THEME_ROUTE_HANDLERS: Record<string, Record<string, RouteHandler | undefined>> = {
  // Theme routes (if any)
}

Runtime Access (Zero I/O)

// Ultra-fast route handler lookup
import { getPluginRouteHandler } from '@/core/lib/registries/route-handlers'

// Direct handler access (instant)
const handler = getPluginRouteHandler('ai/generate', 'POST')

// Call handler
if (handler) {
  const response = await handler(request, { params: Promise.resolve({}) })
}

---

Route Discovery

Automatic Discovery Process

Build script (scripts/build-registry.mjs) discovers:

1. Theme Routes:

contents/themes/default/
└── api/                          # Theme API routes
    ├── custom/
    │   └── route.ts              # GET /api/custom
    └── webhook/
        └── route.ts              # POST /api/webhook

2. Plugin Routes:

contents/plugins/ai/
└── api/                          # Plugin API routes
    ├── generate/
    │   └── route.ts              # POST /api/v1/plugin/ai/generate
    ├── embeddings/
    │   └── route.ts              # GET/POST /api/v1/plugin/ai/embeddings
    └── ai-history/
        └── [id]/
            └── route.ts          # PATCH /api/v1/plugin/ai/ai-history/[id]

Discovery Logic

// From scripts/build-registry.mjs
async function discoverRoutes(basePath: string, type: 'theme' | 'plugin') {
  const routes = []
  
  async function scanDirectory(dir: string, relativePath: string = '') {
    const entries = await readdir(dir, { withFileTypes: true })
    
    for (const entry of entries) {
      const fullPath = join(dir, entry.name)
      const newRelativePath = join(relativePath, entry.name)
      
      if (entry.isDirectory()) {
        // Recursively scan subdirectories
        await scanDirectory(fullPath, newRelativePath)
      } else if (entry.name === 'route.ts' || entry.name === 'route.js') {
        // Found a route file
        const methods = await extractHttpMethods(fullPath)
        
        routes.push({
          path: buildApiPath(type, newRelativePath),
          filePath: fullPath,
          relativePath: newRelativePath.replace('/route.ts', ''),
          methods,
          isRouteFile: true
        })
      }
    }
  }
  
  await scanDirectory(basePath)
  return routes
}

HTTP Method Extraction

async function extractHttpMethods(filePath: string): Promise<string[]> {
  const content = await readFile(filePath, 'utf8')
  const methods: string[] = []
  
  // Match: export async function GET(...) or export function POST(...)
  const methodRegex = /export\s+(?:async\s+)?function\s+(GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)\s*\(/g
  
  let match
  while ((match = methodRegex.exec(content)) !== null) {
    methods.push(match[1])
  }
  
  return methods.length > 0 ? methods : ['GET'] // Default to GET
}

---

Route Handler Type Definition

RouteHandler Interface

import type { NextRequest, NextResponse } from 'next/server'

export type RouteHandler = (
  request: NextRequest,
  context: { params: Promise<any> }
) => Promise<NextResponse>

Next.js App Router signature:

• request: NextRequest object with URL, headers, body, etc.
• context: Contains params Promise for dynamic routes

---

Accessing Route Handlers

getPluginRouteHandler()

Get plugin route handler by route key and method:

import { getPluginRouteHandler } from '@/core/lib/registries/route-handlers'

// Get POST handler for AI generate route
const handler = getPluginRouteHandler('ai/generate', 'POST')

if (handler) {
  const response = await handler(request, { params: Promise.resolve({}) })
  return response
}

getThemeRouteHandler()

Get theme route handler by route key and method:

import { getThemeRouteHandler } from '@/core/lib/registries/route-handlers'

// Get handler for custom theme route
const handler = getThemeRouteHandler('custom/webhook', 'POST')

if (handler) {
  const response = await handler(request, { params: Promise.resolve({}) })
  return response
}

getPluginRouteKeys()

Get all plugin route keys:

import { getPluginRouteKeys } from '@/core/lib/registries/route-handlers'

const routeKeys = getPluginRouteKeys()
console.log(routeKeys)
// ['ai/generate', 'ai/embeddings', 'ai/ai-history/[id]']

getThemeRouteKeys()

Get all theme route keys:

import { getThemeRouteKeys } from '@/core/lib/registries/route-handlers'

const routeKeys = getThemeRouteKeys()
console.log(routeKeys)
// ['custom/webhook', 'custom/events']

---

Integration with Next.js App Router

Dynamic Route Proxy

Next.js dynamic route that proxies to registry:

// app/api/v1/plugin/[plugin]/[...path]/route.ts
import { getPluginRouteHandler } from '@/core/lib/registries/route-handlers'
import { NextRequest, NextResponse } from 'next/server'

export async function GET(
  request: NextRequest,
  { params }: { params: Promise<{ plugin: string; path: string[] }> }
) {
  return handlePluginRoute(request, params, 'GET')
}

export async function POST(
  request: NextRequest,
  { params }: { params: Promise<{ plugin: string; path: string[] }> }
) {
  return handlePluginRoute(request, params, 'POST')
}

async function handlePluginRoute(
  request: NextRequest,
  params: Promise<{ plugin: string; path: string[] }>,
  method: string
) {
  const { plugin, path } = await params
  
  // Build route key
  const routeKey = `${plugin}/${path.join('/')}`
  
  // Get handler from registry
  const handler = getPluginRouteHandler(routeKey, method)
  
  if (!handler) {
    return NextResponse.json(
      { error: 'Route not found' },
      { status: 404 }
    )
  }
  
  // Execute handler
  return handler(request, { params })
}

---

Custom Route Handlers

Theme Custom Routes

Add custom route to theme:

// contents/themes/default/api/webhook/route.ts
import { NextRequest, NextResponse } from 'next/server'

export async function POST(request: NextRequest) {
  const body = await request.json()
  
  // Handle webhook
  console.log('Webhook received:', body)
  
  // Process webhook data
  await processWebhook(body)
  
  return NextResponse.json({ success: true })
}

Access custom route:

POST /api/webhook

Plugin Custom Routes

Add custom route to plugin:

// contents/plugins/ai/api/generate/route.ts
import { NextRequest, NextResponse } from 'next/server'
import { generateText } from '../../lib/ai'

export async function POST(request: NextRequest) {
  const { prompt, model } = await request.json()
  
  // Validate input
  if (!prompt) {
    return NextResponse.json(
      { error: 'Prompt is required' },
      { status: 400 }
    )
  }
  
  // Generate text
  const result = await generateText({ prompt, model })
  
  return NextResponse.json({ result })
}

export async function GET(request: NextRequest) {
  // Return API info
  return NextResponse.json({
    endpoint: '/api/v1/plugin/ai/generate',
    methods: ['POST'],
    description: 'Generate text using AI'
  })
}

Access custom route:

POST /api/v1/plugin/ai/generate
GET /api/v1/plugin/ai/generate

---

Dynamic Routes

Route with Parameters

// contents/plugins/ai/api/ai-history/[id]/route.ts
import { NextRequest, NextResponse } from 'next/server'

export async function GET(
  request: NextRequest,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params
  
  // Fetch AI history by ID
  const history = await fetchAIHistory(id)
  
  if (!history) {
    return NextResponse.json(
      { error: 'History not found' },
      { status: 404 }
    )
  }
  
  return NextResponse.json({ history })
}

export async function PATCH(
  request: NextRequest,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params
  const body = await request.json()
  
  // Update AI history
  const updated = await updateAIHistory(id, body)
  
  return NextResponse.json({ history: updated })
}

Access dynamic route:

GET /api/v1/plugin/ai/ai-history/123
PATCH /api/v1/plugin/ai/ai-history/123

---

Route Priority System

Priority Order

When same route exists in multiple sources:

Theme > Plugin > Entity (Auto-generated)

Examples:
- Route '/api/tasks' in theme AND entity → Theme wins
- Route '/api/custom' in theme → Theme route used
- Route '/api/v1/plugin/ai/generate' → Plugin route used

Why this order?

• Theme customization takes precedence
• Plugins provide specialized endpoints
• Entity routes are auto-generated fallback

Override Example

// Override auto-generated entity route
// contents/themes/default/api/tasks/route.ts
import { NextRequest, NextResponse } from 'next/server'

export async function GET(request: NextRequest) {
  // Custom implementation overrides auto-generated route
  return NextResponse.json({
    message: 'Custom tasks endpoint'
  })
}

---

Real-World Examples

Example 1: API Route List

// app/api/routes/route.ts
import {
  getPluginRouteKeys,
  getThemeRouteKeys
} from '@/core/lib/registries/route-handlers'
import { NextResponse } from 'next/server'

export async function GET() {
  const pluginRoutes = getPluginRouteKeys()
  const themeRoutes = getThemeRouteKeys()
  
  return NextResponse.json({
    plugin: pluginRoutes.map(key => `/api/v1/plugin/${key}`),
    theme: themeRoutes.map(key => `/api/${key}`)
  })
}

Example 2: Route Validation Middleware

// middleware.ts
import { hasRoute } from '@/core/lib/registries/plugin-registry'
import { NextRequest, NextResponse } from 'next/server'

export function middleware(request: NextRequest) {
  const path = request.nextUrl.pathname
  const method = request.method
  
  // Check if plugin route exists
  if (path.startsWith('/api/v1/plugin/')) {
    const routeKey = path.replace('/api/v1/plugin/', '')
    
    if (!hasRoute(routeKey, method)) {
      return NextResponse.json(
        { error: 'Route not found' },
        { status: 404 }
      )
    }
  }
  
  return NextResponse.next()
}

Example 3: Route Testing

// test/routes/plugin-routes.test.ts
import { getPluginRouteHandler, getPluginRouteKeys } from '@/core/lib/registries/route-handlers'
import { NextRequest } from 'next/server'

describe('Plugin Routes', () => {
  test('all routes have handlers', () => {
    const routeKeys = getPluginRouteKeys()
    
    for (const routeKey of routeKeys) {
      const handler = getPluginRouteHandler(routeKey, 'GET')
      expect(handler).toBeDefined()
    }
  })
  
  test('AI generate route works', async () => {
    const handler = getPluginRouteHandler('ai/generate', 'POST')
    expect(handler).toBeDefined()
    
    const request = new NextRequest('http://localhost/api/v1/plugin/ai/generate', {
      method: 'POST',
      body: JSON.stringify({ prompt: 'Test' })
    })
    
    const response = await handler!(request, { params: Promise.resolve({}) })
    expect(response.status).toBe(200)
  })
})

Example 4: API Documentation Generator

// scripts/generate-api-docs.ts
import {
  getPluginRouteKeys,
  PLUGIN_ROUTE_HANDLERS
} from '@/core/lib/registries/route-handlers'

async function generateAPIDocs() {
  const routes = getPluginRouteKeys()
  const docs: any[] = []
  
  for (const routeKey of routes) {
    const handlers = PLUGIN_ROUTE_HANDLERS[routeKey]
    const methods = Object.keys(handlers)
    
    docs.push({
      path: `/api/v1/plugin/${routeKey}`,
      methods,
      description: `Plugin route: ${routeKey}`
    })
  }
  
  // Write to file
  await writeFile('api-docs.json', JSON.stringify(docs, null, 2))
}

---

Performance Characteristics

Zero Dynamic Imports

// ❌ BAD: Runtime dynamic import (~40ms)
const routeModule = await import(`@/contents/plugins/${plugin}/api/${path}/route`)
const handler = routeModule.POST

// ✅ GOOD: Static import from registry (<1ms)
const handler = getPluginRouteHandler('ai/generate', 'POST')

Constant Time Lookups

// O(1) complexity regardless of route count
const handler1 = getPluginRouteHandler('ai/generate', 'POST')       // <1ms
const handler2 = getPluginRouteHandler('ai/embeddings', 'GET')      // <1ms
const handler3 = getPluginRouteHandler('ai/ai-history/[id]', 'PATCH') // <1ms

---

Best Practices

✅ DO: Use Helper Functions

import { getPluginRouteHandler } from '@/core/lib/registries/route-handlers'

const handler = getPluginRouteHandler('ai/generate', 'POST')

✅ DO: Check Handler Exists

const handler = getPluginRouteHandler(routeKey, method)

if (!handler) {
  return NextResponse.json({ error: 'Not found' }, { status: 404 })
}

return handler(request, { params })

✅ DO: Use TypeScript Types

import type { RouteHandler } from '@/core/lib/registries/route-handlers'

const handler: RouteHandler | null = getPluginRouteHandler('ai/generate', 'POST')

❌ DON'T: Use Dynamic Imports

// ❌ FORBIDDEN
const handler = await import(`@/contents/plugins/${plugin}/api/${path}/route`)

// ✅ CORRECT
const handler = getPluginRouteHandler(`${plugin}/${path}`, method)

❌ DON'T: Import Route Files Directly

// ❌ FORBIDDEN
import * as generateRoute from '@/contents/plugins/ai/api/generate/route'

// ✅ CORRECT
import { getPluginRouteHandler } from '@/core/lib/registries/route-handlers'
const handler = getPluginRouteHandler('ai/generate', 'POST')

---

Troubleshooting

Route Not Found

Problem: getPluginRouteHandler('my-route', 'POST') returns null

Solutions:

1. Check route file exists: contents/plugins/[plugin]/api/[path]/route.ts
2. Verify POST method is exported in route file
3. Run pnpm registry:build to regenerate
4. Restart dev server

Wrong HTTP Method

Problem: Route exists but returns null for specific method

Solutions:

1. Check if method is exported in route file
2. Verify method name spelling (GET, POST, etc.)
3. Check HTTP method extraction in build script
4. Regenerate registry

Dynamic Route Not Working

Problem: Dynamic route with [id] not accessible

Solutions:

1. Check route key includes [id]: 'plugin/route/[id]'
2. Verify params are passed correctly to handler
3. Check Next.js dynamic route syntax
4. Review params Promise handling

---

Type Safety

import type {
  RouteHandler
} from '@/core/lib/registries/route-handlers'

// Strongly typed handler
const handler: RouteHandler | null = getPluginRouteHandler('ai/generate', 'POST')

// Type-safe route keys
const routeKeys: string[] = getPluginRouteKeys()

---

Next Steps

• Performance & Caching - Optimization strategies
• Plugin Registry - Plugin system integration
• Theme Registry - Theme routes
• Entity Registry - Auto-generated entity routes

---

Last Updated: 2025-11-20
Version: 1.0.0
Status: Complete
Auto-Generated: Yes (by scripts/build-registry.mjs)
Registry File: core/lib/registries/route-handlers.ts
Integration: Next.js App Router 14.x