Merge branch 'toakleaf-update-router-docs'

README.md

@@ -8,11 +8,46 @@
 
 # `vinxi`
 
-Compose full stack applications (and frameworks) using [**Vite**](https://github.com/vitejs/vite), the versatile bundler and dev server, and [**Nitro**](https://github.com/unjs/nitro), the universal production server. The core primitive in `vinxi` is a **router**.
+Compose full stack applications (and frameworks) using [**Vite**](https://github.com/vitejs/vite), the versatile bundler and dev server, and [**Nitro**](https://github.com/unjs/nitro), the universal production server. 
 
-Inspired by the [Bun.App](https://bun.sh/blog/bun-bundler#sneak-peek-bun-app) API.
+Inspired by the [Bun.App](https://bun.sh/blog/bun-bundler#sneak-peek-bun-app) API, the core primitive in Vinxi is the **router**, which is simply a brief specification defining how a group of URLs should be handled.
 
-- **Routers** are handlers that tell us how specific URLs should be handled. We support various router modes: "static", "spa", "http", (and new ones can be added). Routers specify the handler file (entrypoint) to use for their `base`-prefixed routes. They can also specify a `dir` and `style` in some router modes to include a file system router that is provided to the handler. Routers specify their bundler configuration, via the `build` property. The routers tell the bundler what entry points to build, what vite plugins to use, etc.
+Vinxi supports many common router types:
+- ['static'](https://vinxi.vercel.app/api/router/static.html) - for serving uncompiled, static assets
+- ['http'](https://vinxi.vercel.app/api/router/http.html) - for creating traditional web servers
+- ['spa'](https://vinxi.vercel.app/api/router/spa.html) - for building and serving single page application assets
+- ['client'](https://vinxi.vercel.app/api/router/client.html) - for building and serving of SSR application assets
+- [custom](https://vinxi.vercel.app/api/router/custom.html) - for adapting Vinxi to your use case
+
+Creating a new router is as simple as adding a specification object to the `routers` array in the `createApp` call:
+
+```ts
+import { createApp } from 'vinxi';
+
+export default createApp({
+  routers: [
+    // A static router serving files from the `public` directory
+    {
+      name: 'public',
+      type: 'static',
+      dir: './public',
+      base: '/',
+    },
+    // A http router for an api
+    {
+      name: 'api',
+      type: 'http',
+      handler: './app/api.ts',
+      base: '/api',
+      plugins: () => [
+        // Vite plugins applying exclusively to `http` router
+      ]
+    }
+  ],
+});
+```
+
+---
 
 There are currently two frameworks actively being developed on `vinxi`:
 - [SolidStart](https://github.com/solidjs/solid-start)

docs/.vitepress/config.mts

@@ -58,9 +58,10 @@ export default defineConfig({
 						link: "/api/router",
 						items: [
 							{ text: `"static"`, link: "/api/router/static" },
-							{ text: `"spa"`, link: "/api/router/spa" },
 							{ text: `"http"`, link: "/api/router/http" },
+							{ text: `"spa"`, link: "/api/router/spa" },
 							{ text: `"client"`, link: "/api/router/client" },
+							{ text: `custom`, link: "/api/router/custom" },
 						],
 					},
 					{ text: "vinxi CLI", link: "/api/cli" },

docs/api/router.md

@@ -1,3 +1,38 @@
 # Router API
 
-(Coming soon)
+Inspired by the [Bun.App](https://bun.sh/blog/bun-bundler#sneak-peek-bun-app) API, the core primitive in Vinxi is the **router**, which is simply a brief specification defining how a group of URLs should be handled.
+
+Vinxi supports many common router types:
+- ['static'](./router/static) - for serving uncompiled, static assets
+- ['http'](./router/http) - for creating traditional web servers
+- ['spa'](./router/spa) - for building and serving single page application assets
+- ['client'](./router/client) - for building and serving of SSR application assets
+- [custom](./router/custom) - for adapting Vinxi to your use case
+
+Creating a new router is as simple as adding a specification object to the `routers` array in the `createApp` call:
+
+```ts
+import { createApp } from 'vinxi';
+
+export default createApp({
+  routers: [
+    // A static router serving files from the `public` directory
+    {
+      name: 'public',
+      type: 'static',
+      dir: './public',
+      base: '/',
+    },
+    // A http router for an api
+    {
+      name: 'api',
+      type: 'http',
+      handler: './app/api.ts',
+      base: '/api',
+      plugins: () => [
+        // Vite plugins applying to exclusively to `http` router
+      ]
+    }
+  ],
+});
+```

docs/api/router/client.md

@@ -1,3 +1,80 @@
 # Client Router API
 
-(Coming soon)
+The `client` router is a wrapper for Vite’s build processes and development server, allowing for easy integration with an `http` router for server-side rendering applications.
+
+## Configuration Options
+
+### type
+
+- Value: `'client'`
+
+### name
+
+- Type: `string`
+- Required: `true`
+
+A unique identifier for the router.
+
+### handler
+
+- Type: `string`
+- Required: `true`
+
+The entry point file for the client application.
+
+### base
+
+- Type: `string`
+- Required: `false`
+- Default value: `'/'`
+
+The base URL path under which the built assets for client application will be served.
+
+::: tip
+As client router is mostly built assets, its good to use `base` for namspacing these assets in order to avoid conflicts, eg. `"/_build"`
+:::
+
+### plugins
+
+- Type: `() => Plugin[]`
+- Required: `false`
+
+A function returning an array of Vite plugins to use during the build process.
+
+[Learn more about configuring Vite plugins](../../guide/vite-plugins.md)
+
+### routes
+
+- Type: `(router: RouterSchemaInput, app: AppOptions) => CompiledRouter`
+- Required: `false`
+
+A function defining the routing logic or structure.
+
+[Learn more about Vinxi's file system routing.](../../guide/file-system-routing.md)
+
+### outDir
+
+- Type: `string`
+- Required: `false`
+
+The output directory for build artifacts.
+
+### root
+
+- Type: `string`
+- Required: `false`
+
+The root directory for resolving paths. Defaults to the application's root directory.
+
+
+## Example Configuration
+
+```ts
+{
+  name: "client",
+  type: "client",
+  handler: "./app/client.tsx",
+  base: "/_build",
+  plugins: () => [ reactRefresh() ],
+}
+```

docs/api/router/custom.md

@@ -0,0 +1,90 @@
+# Custom Router API
+
+The Custom Router allows for defining routers with custom behavior or configurations that don’t fit into the predefined router types. It’s useful for advanced or specialized use cases.
+
+## Configuration Options
+
+### type
+
+- Type: `{ resolveConfig: (router: Router, app: App) => Router }`
+- Required: `true`
+
+Unlike all other routers, rather than a string literal, custom routers are defined by passing defining the `type` as an object with a `resolveConfig` function.
+
+### name
+
+- Type: `string`
+- Required: `true`
+
+A unique identifier for the router.
+
+### handler
+
+- Type: `string`
+- Required: `true`
+
+The entry point file for Nitro server handling HTTP requests.
+
+### target
+
+- Type: `'server'`
+- Required: `true`
+
+Unlike all other routers where `target` is implied by the `type`, for custom routers the string literal `'server'` must be passed explicitly, as is currently the only option.
+
+### base
+
+- Type: `string`
+- Required: `false`
+- Default value: `'/'`
+
+The base URL path under which the client application will be served.
+
+### plugins
+
+- Type: `() => Plugin[]`
+- Required: `false`
+
+A function returning an array of Vite plugins to use during the build process.
+
+[Learn more about configuring Vite plugins](../../guide/vite-plugins.md)
+
+### routes
+
+- Type: `(router: RouterSchemaInput, app: AppOptions) => CompiledRouter`
+- Required: `false`
+
+A function defining the routing logic or structure.
+
+[Learn more about Vinxi's file system routing.](../../guide/file-system-routing.md)
+
+### outDir
+
+- Type: `string`
+- Required: `false`
+
+The output directory for build artifacts.
+
+### root
+
+- Type: `string`
+- Required: `false`
+
+The root directory for resolving paths. Defaults to the application's root directory.
+
+
+## Example Configuration
+
+```ts
+{
+  name: "customRouter",
+  type: {
+    resolveConfig: (router, app) => {
+      // Custom configuration logic
+    },
+  },
+  handler: "./app/customHandler.ts",
+  target: "server",
+}
+```
+

docs/api/router/http.md

@@ -1,3 +1,112 @@
 # HTTP Router API
 
-(Coming soon)
+The `http` router is a wrapper of a Nitro web server, with all the flexibility that entails. Great for server side rendering, websockets, custom API endpoints, etc... 
+
+## Configuration Options
+
+### type
+
+- Value: `'http'`
+
+### name
+
+- Type: `string`
+- Required: `true`
+
+A unique identifier for the router.
+
+:::tip
+The name of the router that the code is currently executing can be imported from `vinxi/manifest`.
+```ts
+import { routerName } from "vinxi/manifest";
+
+export default eventHandler(() => {
+  const serverManifest = getManifest(routerName);
+  const clientManifest = getManifest("react-client");
+});
+```
+:::
+
+### handler
+
+- Type: `string`
+- Required: `true`
+
+The entry point file for Nitro server handling HTTP requests.
+
+### base
+
+- Type: `string`
+- Required: `false`
+- Default value: `'/'`
+
+The base URL path under which the client application will be served.
+
+### plugins
+
+- Type: `() => Plugin[]`
+- Required: `false`
+
+A function returning an array of Vite plugins to use during the build process.
+
+[Learn more about configuring Vite plugins](../../guide/vite-plugins.md)
+
+### routes
+
+- Type: `(router: RouterSchemaInput, app: AppOptions) => CompiledRouter`
+- Required: `false`
+
+A function defining the routing logic or structure.
+
+[Learn more about Vinxi's file system routing.](../../guide/file-system-routing.md)
+
+## middleware
+
+- Type: `string`
+- Required: `false`
+
+Path to server middleware to apply to the router.
+
+### worker
+
+- Type: `boolean`
+- Required: `false`
+- Default value: `false`
+
+Configures the router to run its request-handling in a separate worker thread.
+
+### build
+
+- Type: `boolean`
+- Required: `false`
+- Default value: `true`
+
+Include the router in the build process.
+
+### outDir
+
+- Type: `string`
+- Required: `false`
+
+The output directory for build artifacts.
+
+### root
+
+- Type: `string`
+- Required: `false`
+
+The root directory for resolving paths. Defaults to the application's root directory.
+
+
+## Example Configuration
+
+```ts
+{
+  name: "server",
+  type: "http",
+  handler: "./app/apiHandler.ts",
+  base: "/api",
+  worker: true,
+  plugins: () => [ reactRefresh() ],
+}
+```