# <span class="k">Kosmo</span>JS

> KosmoJS - the composable meta-framework

<span class="tagline-container"> <span class="headline text-nowrap">the composable meta-framework</span> <span>Multiple source folders. Directory-based routing.</span> <span>Cascading middleware. Nested layouts.</span> <span>End-to-end validation. Fetch clients. OpenAPI spec.</span> <span>Koa, Hono, SolidJS, React, Vue, MDX and more.</span> </span>

## Table of Contents

### Introduction

- [About KosmoJS](/about.md): KosmoJS - the composable meta-framework. Organize multiple apps with directory-based routing, automatic runtime validation, typed fetch clients, and OpenAPI generation.
- [Features](/features.md): Explore KosmoJS features including multiple source folders, directory-based routing, end-to-end type safety, generated fetch clients, OpenAPI specs, and framework freedom - Koa, Hono, React, Solid, Vue, MDX.
- [Quick Start](/start.md): Get a KosmoJS project running in under five minutes.
- [Tutorial](/tutorial.md): Build a full KosmoJS application step by step - routing, validation, middleware, fetch clients, pages, SSR, and multi-folder architecture.

### Routing

- [Directory-Based Routing](/routing/intro.md): KosmoJS uses directory-based routing to map file system structure directly to URL paths. Folder names become path segments with index files defining endpoints and components.
- [Directory-based nested routing](/routing/rationale.md): Understanding why directory-based routing scales better than file-based routing for organizing large applications with clear navigation, colocalization, and visual hierarchy.
- [Dynamic Route Parameters](/routing/params.md): Handle dynamic URL segments with required [id], optional {id} and splat {...path} parameters. SolidStart-inspired syntax that works identically for API routes and client pages.
- [Auto-Generated Route Content](/routing/generated-content.md): KosmoJS automatically generates boilerplate code for new routes with context-aware templates for API endpoints using defineRoute and framework-specific page components.

### Backend

- [API Server](/backend/intro.md): KosmoJS API layer supports both Koa and Hono frameworks with elegant middleware composition, end-to-end type safety, and flexible route definitions inspired by Sinatra framework.
- [Enhanced Context Object](/backend/context.md): Learn about KosmoJS's enhanced context with unified bodyparser API and ctx.validated for type-safe validated data access
- [Type Safety](/backend/type-safety.md): Refine params/payload/response types in KosmoJS with compile-time TypeScript checking and automatic runtime validation using type arguments
- [Middleware](/backend/middleware.md): Understand middleware chains and Koa/Hono onion model execution pattern. Configure middleware to run only for specific HTTP methods. Override global middleware using slot system.
- [Cascading Middleware](/backend/cascading-middleware.md): Organize middleware hierarchically using use.ts files that wrap route subtrees. Apply authentication, logging, and custom parsers to folders and their descendants without cluttering individual route definitions.
- [Error Handling](/backend/error-handling.md): Handle errors gracefully in KosmoJS with customizable error handlers for Koa and Hono. Learn about default error handling, route-level overrides, and framework differences.
- [Development Workflow](/backend/development-workflow.md): Run multiple KosmoJS source folders independently with separate dev servers, automatic API hot-reload, custom middleware routing, and resource cleanup with teardown handlers.
- [Building for Production](/backend/building-for-production.md): Build and deploy KosmoJS applications to production with independent source folder builds, deployment strategies for containers, serverless, and edge runtimes.

### Frontend

- [Framework Integration](/frontend/intro.md): Integrate KosmoJS directory-based routing with React, SolidJS, Vue, or MDX. Automatic route configuration, type-safe navigation, and optimized lazy loading for modern frontend applications.
- [Application Structure](/frontend/application.md): Generator-produced foundation files for React, SolidJS, Vue and MDX applications - root App component, router configuration, and client entry point with SSR hydration support.
- [Routing](/frontend/routing.md): Watch-based route generation, lazy-loaded components, data loading integration, and nested layout patterns for React, SolidJS, Vue and MDX applications.
- [Nested Layouts](/frontend/layouts.md): Compose shared UI at any level of the route hierarchy using layout files. Navigation, sidebars, auth shells, and data loading scoped to route subtrees for React, SolidJS, Vue and MDX applications.
- [Type-Safe Navigation](/frontend/link-navigation.md): Generated Link component wrapping each framework's native router with compile-time route validation. Autocomplete navigation targets, parameter enforcement, and query string handling for React, SolidJS, Vue and MDX.
- [Data Preloading](/frontend/data-preload.md): Prefetch route data before components render using React Router's loader pattern, SolidJS Router's preload pattern, and Vue Router's navigation guards. Type-safe data availability derived from API endpoint definitions.
- [Server-Side Rendering](/frontend/server-side-render.md): Add SSR capabilities to React, SolidJS, Vue and MDX applications using the KosmoJS SSR generator. String and stream rendering patterns, production builds, and deployment configurations for server-rendered applications.
- [Custom Page Templates](/frontend/custom-templates.md): Override default generated page components for specific routes using glob pattern matching. Create specialized scaffolding for landing pages, admin dashboards, and marketing sections in React, SolidJS, Vue and MDX source folders.
- [MDX Content](/frontend/mdx.md): Create content-focused source folders with MDX - static HTML rendering with Preact, nested layouts, frontmatter-driven head injection, typed navigation, and optional static site generation. No client-side JavaScript by default.

### Runtype Validation

- [Runtime Validation](/validation/intro.md): KosmoJS runtype validation automatically converts TypeScript types into JSON Schema with runtime validators. Write types once, get compile-time and runtime safety without schema duplication.
- [Parameter Validation](/validation/params.md): Validate route parameters at runtime with type refinements using defineRoute type arguments. Convert string URL parameters to validated numbers, integers, or constrained values with VRefine.
- [Payload Validation](/validation/payload.md): Validate request payloads with inline TypeScript types or imported type definitions. Support for nested structures, conditional validation, generics, and complex domain models with VRefine constraints.
- [Response Validation](/validation/response.md): Validate API responses before sending to clients. Catch bugs where handlers return incomplete objects, wrong types, or unexpected structures with automatic runtime checking.
- [VRefine for Type Refinement](/validation/refine.md): Advanced validation constraints with VRefine using JSON Schema keywords. Validate string formats, numeric ranges, array constraints, and custom patterns directly in TypeScript types.
- [Skip Runtime Validation](/validation/skip-validation.md): Set runtimeValidation option to false to keep TypeScript type checking without runtime validation for gradual adoption, performance optimization, or trusted internal endpoints.
- [Validation Error Handler](/validation/error-handling.md): Handle ValidationError instances with detailed error information including scope, error messages, field paths, and structured ValidationErrorEntry data.
- [Validation Naming Conventions](/validation/naming-conventions.md): Avoid TypeScript built-in type names when defining types for validation. Use suffix T or prefix T conventions to prevent runtime validation failures.
- [Validation Performance](/validation/performance.md): Understand KosmoJS validation performance with TypeScript compiler analysis, intelligent caching, and background processing that doesn't impact development workflow.

### Fetch Clients

- [Generated Fetch Clients](/fetch/intro.md): KosmoJS automatically generates fully-typed fetch clients with runtime validation for every API route. End-to-end type safety from frontend to backend with validation schemas and URL utilities.
- [Getting Started with Fetch Client](/fetch/start.md): Import and use KosmoJS generated fetch clients with full TypeScript typing. Access routes directly or through a centralized map with automatic parameter and payload validation.
- [Fetch Client Integration](/fetch/integration.md): Integrate KosmoJS fetch clients with SolidJS createResource, React hooks, and custom state management patterns. Type safety flows through all framework abstractions.
- [Client-Side Validation](/fetch/validation.md): Automatic client-side validation with TypeBox schemas before network requests. Use check, errors, errorMessage methods for form validation with performance optimization patterns.
- [Fetch Client Error Handling](/fetch/error-handling.md): Handle fetch request errors with try-catch blocks, distinguish ValidationError from network errors, and implement defense in depth with client-side and server-side validation.
- [Path Utilities](/fetch/utilities.md): Build URLs with path and href utility functions that handle route parameters, query strings, and base URL configuration for navigation and external references.


### Other

- [OpenAPI Generator](/openapi.md): Automatically generate OpenAPI 3.1 specifications from KosmoJS API routes. Analyzes route structure, TypeScript types, and validation schemas to produce standards-compliant documentation.
- [Untitled](/.vitepress/theme/components/ParamsValidation.md)
- [Untitled](/.vitepress/theme/components/ResponseValidation.md)
- [Untitled](/.vitepress/theme/components/PayloadValidation.md)
- [Untitled](/.vitepress/theme/components/ComposableMiddleware.md)
- [Untitled](/.vitepress/theme/components/CascadingMiddleware.md)