docs changes

docs/.vitepress/config.mts

@@ -23,34 +23,43 @@ export default defineConfig({
 				link: "/guide",
 				items: [
 					{ text: "Why Vinxi", link: "/guide/why-vinxi" },
-					{ text: "Getting Started", link: "/guide/getting-started" },
+					{ text: "Get Started", link: "/guide/getting-started" },
 					{
-						text: "Build Your Own Framework",
-						link: "/guide/build-your-own-framework",
+						text: "Create your first app",
+						link: "/guide/create-your-first-app",
 					},
 					{
-						text: "Core Concepts",
-						items: [
-							{ text: "What is an App", link: "/guide/what-is-an-app" },
-							{ text: "What is a Router", link: "/guide/what-is-a-router" },
-						],
+						text: "Upgrade existing Vite app",
+						link: "/guide/add-to-existing-vite-app",
+					},
+					{
+						text: "Build Your Own Framework",
+						link: "/guide/build-your-own-framework",
 					},
 					{
-						text: "Extending Vinxi",
+						text: "Configuring Vinxi",
 						items: [
 							{ text: "Vite Plugins", link: "/guide/vite-plugins" },
 							{ text: "Path Aliases", link: "/guide/aliases" },
 						],
 					},
-					{ text: "A Story", link: "/guide/a-story" },
-					{ text: "Philosophy", link: "/guide/philosophy" },
 				],
 			},
 			{
 				text: "APIs",
 				link: "/api",
 				items: [
 					{ text: "App API", link: "/api/app" },
+					{
+						text: "Router API",
+						link: "/api/router",
+						items: [
+							{ text: `"static"`, link: "/api/router/static" },
+							{ text: `"spa"`, link: "/api/router/spa" },
+							{ text: `"http"`, link: "/api/router/http" },
+							{ text: `"client"`, link: "/api/router/client" },
+						],
+					},
 					{ text: "vinxi CLI", link: "/api/cli" },
 					{
 						text: "Server API",
@@ -65,6 +74,13 @@ export default defineConfig({
 					{ text: "Manifest API", link: "/api/manifest" },
 				],
 			},
+			{
+				text: "Resources",
+				items: [
+					{ text: "A Story", link: "/guide/a-story" },
+					{ text: "Philosophy", link: "/guide/philosophy" },
+				],
+			},
 		],
 		outline: {
 			level: [2, 3],

docs/api/app.md

@@ -1 +1,178 @@
 # App API
+
+Vinxi is designed primary as a runtime for your server applications. The routers included in the app drive the behavior of the server, but the server is in your control via the `App` API.
+
+## `App` API
+
+### `createApp(config)`
+
+The primary way to use Vinxi is to use `createApp` to create an app,
+
+::: code-group
+
+```ts [app.js]
+import { createApp } from "vinxi";
+
+export default createApp({
+  routers: [
+    {
+      name: "public",
+      type: "static",
+      dir: "./public",
+    },
+    {
+      name: "api",
+      type: "http",
+      handler: "./server.ts",
+      target: "server",
+    },
+    // ... other routers
+  ],
+});
+```
+
+:::
+
+::: info
+
+To learn more about how to describe your app to Vinxi and use `createApp`, see the [App API](/api/app).
+
+:::
+
+The `createApp` function return an instance of `App`. This instance has the following methods that you can use to create your own experience:
+
+### `app.dev()`
+
+Starts the development server for the app.
+
+```ts twoslash
+import { createApp } from "vinxi";
+
+const app = createApp({
+  routers: [
+    // ... routers
+  ],
+});
+
+await app.dev();
+```
+
+### `app.build()`
+
+Builds the app for production.
+
+```ts twoslash
+import { createApp } from "vinxi";
+
+const app = createApp({
+  routers: [
+    // ... routers
+  ],
+});
+
+await app.build();
+```
+
+### `app.getRouter(name)`
+
+Gets a router by name.
+
+```ts twoslash
+import { createApp } from "vinxi";
+
+const app = createApp({
+  routers: [
+    // ... routers
+  ],
+});
+
+const router = app.getRouter("api");
+```
+
+## Running a Vinxi app using `node`
+
+You can run a file that creates a Vinxi app using the regular `node` CLI.
+
+```bash
+node app.js
+```
+
+If you run the app without any additional options, it will just create the `App` and not start the server.
+
+You can use the `--dev` option to start the development server for your application.
+
+```bash
+node app.js --dev
+```
+
+And, you can use the `--build` option to build your application for production.
+
+```bash
+node app.js --build
+```
+
+::: info
+
+The `--dev` and `--build` flags use the underlying [`app.dev()`](#app-dev) and [`app.build()`](#app-build) methods to start the development server and build the app. They are just shortcuts to make it easier to run the app using `node`.
+
+:::
+
+The built application can be started by running the built node server file using `node` or whatever preset you decided the build the app with.
+
+```bash
+node .output/server/index.mjs
+```
+
+## Wrapping Vinxi
+
+You can also wrap Vinxi in your own runtime to add a pre-configured set of routers, middlewares, and other settings. You can also use it to add your own custom logic to the server.
+
+::: code-group
+
+```ts [node_modules/framework]
+import { createApp } from "vinxi";
+
+export function createFrameworkApp() {
+  return createApp({
+    routers: [
+      {
+        name: "public",
+        type: "static",
+        dir: "./public",
+      },
+      {
+        name: "api",
+        type: "http",
+        handler: "./server.ts",
+        target: "server",
+      },
+      // ... other routers
+    ],
+  });
+}
+```
+
+:::
+
+::: code-group
+
+```ts [app.js]
+import { createFrameworkApp } from "framework";
+
+export default createFrameworkApp();
+```
+
+:::
+
+The created app can be used by your own CLI or other runtime to start the development server and build the app
+
+```ts [bin/cli.mjs]
+import { createFrameworkApp } from "framework";
+
+const app = createFrameworkApp();
+if (process.argv.includes("--dev")) {
+  await app.dev();
+} else if (process.argv.includes("--build")) {
+  await app.build();
+}
+```

docs/api/cli.md

@@ -2,8 +2,46 @@
 
 ## `vinxi dev`
 
+Starts Vinxi's development server for your app. By default, it looks for a `app.config.js` file in the current directory for your app description. You can also pass a path to a different app config file using the `--config` option.
+
+```bash
+vinxi dev --config path/to/your-app.js
+```
+
+By default, the dev server starts on port 3000. You can change this using the `--port` option.
+
+```bash
+vinxi dev --port 3001
+```
+
 ## `vinxi build`
 
+Builds your app for production. By default, it looks for a `app.config.js` file in the current directory for your app description. You can also pass a path to a different app config file using the `--config` option.
+
+```bash
+vinxi build --config path/to/your-app.js
+```
+
+By default, we build your app with the `node-server` preset. You can change this using the `--preset` option or the `SERVER_PRESET` environment variable.
+
+```bash
+vinxi build --preset vercel-edge
+
+# OR
+SERVER_PRESET=vercel-edge vinxi build
+```
+
+## `vinxi start` (experimental)
+
+Starts a production server for your app. It looks for your recently built app in the appropriate directory based on the preset. By default, Vinxi uses the `node-server` preset, and looks for your app in the `.output` direction. You can change the preset being used using the `--preset` option or the `SERVER_PRESET` environment variable.
+
+```bash
+vinxi start --preset vercel-edge
+
+# OR
+SERVER_PRESET=vercel-edge vinxi start
+```
+
 ## `vinxi serve`
 
 Starts a static file server to preview the build. Options --dir, --host, --port, --base

docs/api/router.md

@@ -0,0 +1,3 @@
+# Router API
+
+(Coming soon)

docs/api/router/client.md

@@ -0,0 +1,3 @@
+# Client Router API
+
+(Coming soon)

docs/api/router/http.md

@@ -0,0 +1,3 @@
+# HTTP Router API
+
+(Coming soon)

docs/api/router/spa.md

@@ -0,0 +1,3 @@
+# SPA Router API
+
+(Coming soon)

docs/api/router/static.md

@@ -0,0 +1,3 @@
+# Static Router API
+
+(Coming soon)

docs/guide/getting-started.md

@@ -31,5 +31,5 @@ Being a SDK, `vinxi` is a collection of primitives that you can bend to your wil
 But if you don't want to commit to any of those and just want to look around, you can start by reading:
 
 - [Why we built Vinxi](./why-vinxi.md)
-- The core concepts of Vinxi: [App](./what-is-an-app.md) and [Router](./what-is-a-router.md)
+- The core concepts of Vinxi: [App](/api/app) and [Router](/api/router)
 - [Our philosophy behind our decisions](./philosophy.md)