# Runable

> Runable is a Vue framework that adds file-based routing, layouts, SSR, auto-imports, modules, and application tooling on top of Vue and Vite, while letting you keep the backend runtime you already use.

Runable does not provide its own HTTP runtime. Applications run with Express, Fastify, NestJS, AdonisJS, Hono, Koa, Bun, Deno, or a custom server — Runable mounts as the last handler and serves the Vue application.

Generated files under `.app/` and `.output/` are build output. Never edit them directly — change the source files or `runable.config.ts` and rebuild.

## Getting Started

- [Installation](https://runablejs.com/docs/getting-started/installation.md): Install Runable in an existing backend project and prepare a minimal Vue application with Express.
- [Quick Start](https://runablejs.com/docs/getting-started/quickstart.md): Create a Runable application with two pages, a layout, an API route, and server-rendered data.
- [Concepts](https://runablejs.com/docs/getting-started/concepts.md): Understand the backend, Runable engine, Vue application, generated files, and SSR lifecycle.

## CLI

- [CLI](https://runablejs.com/docs/guide/cli/index.md): The runable command line — scaffold, prepare, and build projects, then connect Runable to AI coding tools.
- [runable create](https://runablejs.com/docs/guide/cli/create.md): Scaffold a new Runable project, add Runable to an existing backend, or create a Runable module.
- [runable prepare](https://runablejs.com/docs/guide/cli/prepare.md): Regenerate .app/ — the types, routes, and auto-import registries Runable derives from your project.
- [runable build](https://runablejs.com/docs/guide/cli/build.md): Produce the production client and server bundles Runable serves from .output/.
- [AI Skills](https://runablejs.com/docs/guide/cli/skills.md): Install Runable's Agent Skills — procedural instructions that teach compatible AI coding agents how to work with a Runable project.

## Core Concepts

- [Routing](https://runablejs.com/docs/guide/routing.md): Create application routes from files in app/pages.
- [Layouts](https://runablejs.com/docs/guide/layouts.md): Share an interface structure across pages without duplicating templates.
- [Middleware](https://runablejs.com/docs/guide/middlewares.md): Allow, block, or redirect navigation before displaying a page.
- [Data Fetching](https://runablejs.com/docs/guide/data-fetching.md): Load data with caching, deduplication, cancellation, and SSR hydration.
- [SSR and CSR](https://runablejs.com/docs/guide/rendering-modes.md): Choose the application's rendering mode and isolate browser-only code.
- [Error handling](https://runablejs.com/docs/guide/error-handling.md): Capture Vue, Router, and browser errors in a consistent interface.

## Configuration

- [Configuration](https://runablejs.com/docs/getting-started/configuration.md): Configure directories, SSR, metadata, aliases, modules, and Vite options for your application.
- [runable.config.ts](https://runablejs.com/docs/structure/runable-config.md): Configure conventions, SSR, modules, and Vite from the project's central file.
- [Modules](https://runablejs.com/docs/guide/modules.md): Group and distribute a configurable Runable feature.
- [Runtime configuration](https://runablejs.com/docs/guide/runtime-config.md): Load typed variables without exposing secrets to the browser.
- [.env](https://runablejs.com/docs/structure/env.md): Load typed environment variables and control which values Runable exposes to the browser.

## Extending Runable

- [Plugins](https://runablejs.com/docs/guide/plugins.md): Initialize libraries, provide dependencies, and order Vue application startup.
- [Auto-imports](https://runablejs.com/docs/guide/auto-imports.md): Automatically use application components, composables, and global functions.
- [Inspector](https://runablejs.com/docs/guide/inspector.md): Programmatically inspect how Runable resolves a project — routes, layouts, middleware, plugins, modules, and auto-imports.

## Server Runtimes

- [Express](https://runablejs.com/docs/integrations/express.md): Use Runable as the last middleware in an Express application.
- [Fastify](https://runablejs.com/docs/integrations/fastify.md): Register Runable as a frontend fallback plugin in Fastify.
- [NestJS](https://runablejs.com/docs/integrations/nestjs.md): Register Runable as the catch-all controller of a NestJS application using Express.
- [AdonisJS](https://runablejs.com/docs/integrations/adonisjs.md): Serve the Vue application from an AdonisJS catch-all route.
- [Hono](https://runablejs.com/docs/integrations/hono.md): Use Runable as a fallback after Hono routes.
- [Koa](https://runablejs.com/docs/integrations/koa.md): Add Runable as the last middleware in a Koa application.
- [Bun](https://runablejs.com/docs/integrations/bun.md): Use Runable's Fetch API adapter with Bun.serve().
- [Deno](https://runablejs.com/docs/integrations/deno.md): Use Runable's Fetch API adapter with Deno.serve().
- [h3](https://runablejs.com/docs/integrations/h3.md): Connect h3 to Runable manually with the Node or Fetch API primitives.
- [Custom adapter](https://runablejs.com/docs/integrations/custom.md): Connect Runable to a Node or Fetch API server without a dedicated adapter.

## API

- [useAsyncData](https://runablejs.com/docs/api/composables/use-async-data.md): Load, cache, and hydrate asynchronous data during SSR.
- [useFetch](https://runablejs.com/docs/api/composables/use-fetch.md): Fetch data with reactive options, SSR hydration, caching, and request deduplication.
- [useConfig](https://runablejs.com/docs/api/composables/use-config.md): Read the public part of the Runable configuration in the Vue application.
- [useRuntime](https://runablejs.com/docs/api/composables/use-runtime.md): Access public and private environment variables loaded by Runable.
- [defineVueMiddleware](https://runablejs.com/docs/api/globals/define-vue-middleware.md): Declare one or more typed navigation middleware functions.
- [defineVuePlugin](https://runablejs.com/docs/api/globals/define-vue-plugin.md): Declare a Runable plugin with injections, dependencies, and application hooks.
- [definePageMeta](https://runablejs.com/docs/api/globals/define-page-meta.md): Associate a layout, middleware, and Vue Router metadata with a page.
- [$fetch](https://runablejs.com/docs/api/globals/dollar-fetch.md): Send HTTP requests with the auto-imported ofetch client.
- [RunablePage](https://runablejs.com/docs/api/components/runable-page.md): Display the component associated with the current Vue Router route.
- [RunableLink](https://runablejs.com/docs/api/components/runable-link.md): Create typed links that navigate with Vue Router.
- [RunableLayout](https://runablejs.com/docs/api/components/runable-layout.md): Load and apply the layout selected in the route metadata.

## Resources

- [GitHub repository](https://github.com/runablejs/runable): Source code, issues, and releases.