Vinxi

https://vinxi.vercel.app/
Admin
Vinxi is a full-stack JavaScript SDK designed to help developers build JavaScript applications and...
Tokens:49,272
Snippets:285
Trust Score:7.8
Update:1 year ago
Show doc for...
Tokens:
Raw
### Start Development Server (Bash)

Source: https://vinxi.vercel.app/guide/a-story

This bash command starts the Vinxi development server. It allows for rapid development and testing of the application by providing hot-reloading and other development-centric features.

```bash
npm run dev
```

--------------------------------

### Example Static HTML File (HTML)

Source: https://vinxi.vercel.app/guide/a-story

This HTML snippet represents a basic 'index.html' file that can be placed in the 'public' directory to be served by the static file server. It includes a simple heading.

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Hello World</title>
  </head>
  <body>
    <h1>Hello World</h1>
  </body>
</html>
```

--------------------------------

### Install Dependencies (Bash)

Source: https://vinxi.vercel.app/guide/a-story

This bash command installs all the project dependencies listed in the package.json file. It is a standard step after initializing a new project or modifying dependencies.

```bash
npm install
```

--------------------------------

### Initialize Project with package.json (JSON)

Source: https://vinxi.vercel.app/guide/a-story

This JSON snippet defines the project's name, type, private status, scripts for development, building, and starting, and lists Vinxi as a dependency. It is essential for managing project dependencies and build processes.

```json
{
  "name": "my-app",
  "type": "module",
  "private": true,
  "scripts": {
    "dev": "vinxi dev",
    "build": "vinxi build",
    "start": "vinxi start"
  },
  "dependencies": {
    "vinxi": "0.3.8"
  }
}
```

--------------------------------

### Basic App Configuration (TypeScript)

Source: https://vinxi.vercel.app/guide/a-story

This TypeScript code initializes a new Vinxi application. It's the minimal configuration required to start a Vinxi app and serves as a foundation for further customization.

```typescript
import { createApp } from "vinxi";

export default createApp();
```

--------------------------------

### Start Vinxi Production Server

Source: https://vinxi.vercel.app/api/cli

Starts a production server for a built application. Supports specifying the preset used for building via the `--preset` option or the `SERVER_PRESET` environment variable.

```bash
vinxi start --preset vercel-edge

# OR
SERVER_PRESET=vercel-edge vinxi start
```

--------------------------------

### Install and Use External JavaScript Library

Source: https://vinxi.vercel.app/guide/a-story

This example shows how to install an external JavaScript library using npm, yarn, or pnpm, and then import and use it in your project. It also highlights the need to specify the script type as 'module' for imports to work.

```bash
npm install canvas-confetti
```

```bash
yarn add canvas-confetti
```

```bash
pnpm add canvas-confetti
```

```javascript
import confetti from "canvas-confetti";

document.getElementById("my-button").addEventListener("click", () => {
  confetti();
});
```

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Hello World</title>
    <link rel="stylesheet" href="/app.css" />
  </head>
  <body>
    <h1>Hello World</h1>
    <button id="my-button">Click Me</button>
    <script type="module" src="/app.js"></script>
  </body>
</html>
```

--------------------------------

### Start Vinxi Production Server CLI

Source: https://context7.com/context7/vinxi_vercel_app/llms.txt

Starts the production server for a Vinxi application. This command is experimental and supports specifying presets and serving static files. It allows for controlled deployment of your built application.

```bash
# Start production server (experimental)
vinxi start

# Start with specific preset
vinxi start --preset vercel-edge

# Serve static files
vinxi serve --dir .output/public --base /my-repo
```

--------------------------------

### Run Vinxi App with Node.js CLI (Bash)

Source: https://vinxi.vercel.app/api/app

Provides examples of how to execute a Vinxi application file directly using the Node.js command-line interface. It covers starting the development server (`--dev`), building for production (`--build`), and running a pre-built application.

```bash
node app.js
```

```bash
node app.js --dev
```

```bash
node app.js --build
```

```bash
node .output/server/index.mjs
```

--------------------------------

### Start Vinxi Development Server Programmatically

Source: https://context7.com/context7/vinxi_vercel_app/llms.txt

Programmatically starts the Vinxi development server using the `createApp` API. This allows for more control over server initialization within your application code.

```typescript
import { createApp } from "vinxi";

const app = createApp({
  routers: [
    {
      name: "api",
      type: "http",
      handler: "./server.ts",
      target: "server",
    },
  ],
});

// Start development server
await app.dev();
```

--------------------------------

### Install Vinxi using Package Managers

Source: https://context7.com/context7/vinxi_vercel_app/llms.txt

Installs the Vinxi SDK using various package managers like pnpm, npm, yarn, and bun. Ensure you have one of these package managers installed and configured in your project.

```bash
# Using pnpm
pnpm install vinxi

# Using npm
npm install vinxi

# Using yarn
yarn add vinxi

# Using bun
bun install vinxi
```

--------------------------------

### Start Vinxi Development Server

Source: https://vinxi.vercel.app/api/cli

Starts Vinxi's development server. It can take a custom config file path using the `--config` option and a custom port using the `--port` option.

```bash
vinxi dev --config path/to/your-app.js
vinxi dev --port 3001
```

--------------------------------

### Custom Server Listener with Vinxi

Source: https://vinxi.vercel.app/api/cli

Manually starts a server listener using `vinxi/listen` and `vinxi/http`. This allows for more control over the server setup, including specifying the port.

```typescript
import { eventHandler, toNodeListener } from "vinxi/http";
import { listen } from "vinxi/listen";

const handler = eventHandler(async (event) => {
  return {
    body: "Hello World",
  };
});

await listen(toNodeListener(handler), { port: 3000 });
```

--------------------------------

### Serve Static Files with Vinxi

Source: https://vinxi.vercel.app/api/cli

Starts a static file server to preview a build. Supports options for directory, host, port, and base URL.

```bash
vinxi serve --dir .output/public --base /my-repo
```

--------------------------------

### Vinxi Custom Server Listener Script

Source: https://context7.com/context7/vinxi_vercel_app/llms.txt

An advanced example using Vinxi to set up a custom HTTP server listener. It combines `eventHandler` for request handling and `toNodeListener` to adapt it for Node.js environments, using `vinxi/listen` to start the server.

```typescript
// script.ts - Custom server listener
import { eventHandler, toNodeListener } from "vinxi/http";
import { listen } from "vinxi/listen";

const handler = eventHandler(async (event) => {
  return {
    body: "Hello World",
  };
});

await listen(toNodeListener(handler), { port: 3000 });
```

--------------------------------

### Custom Router Configuration Example

Source: https://vinxi.vercel.app/api/router/custom

This example demonstrates how to configure a custom router in Vinxi. It includes the essential `name`, `type` (with a `resolveConfig` function), `handler`, and `target` properties, showcasing a basic custom router setup.

```typescript
{
  name: "customRouter",
  type: {
    resolveConfig: (router, app) => {
      // Custom configuration logic
    },
  },
  handler: "./app/customHandler.ts",
  target: "server",
}
```

--------------------------------

### Start Vinxi Development Server CLI

Source: https://context7.com/context7/vinxi_vercel_app/llms.txt

Starts the Vinxi development server. It can be configured to use a custom config file or run on a specific port. The default configuration file it looks for is 'app.config.js'.

```bash
# Start dev server (looks for app.config.js by default)
vinxi dev

# Start dev server with custom config
vinxi dev --config path/to/your-app.js

# Start dev server on custom port
vinxi dev --port 3001
```

--------------------------------

### Client Router Configuration Example (TypeScript)

Source: https://vinxi.vercel.app/api/router/client

An example demonstrating how to configure the client router in TypeScript. It specifies the router's name, type, entry point handler, base URL for assets, and Vite plugins.

```typescript
{
  name: "client",
  type: "client",
  handler: "./app/client.tsx",
  base: "/_build",
  plugins: () => [ reactRefresh() ]
}
```

--------------------------------

### Initialize Framework App in JS

Source: https://context7.com/context7/vinxi_vercel_app/llms.txt

Initializes the custom framework application created by `createFrameworkApp`. This is a basic setup for bootstrapping the application.

```javascript
import { createFrameworkApp } from "framework";

export default createFrameworkApp();
```

--------------------------------

### Add Event Listener with JavaScript

Source: https://vinxi.vercel.app/guide/a-story

This example demonstrates how to add an event listener to an HTML element using JavaScript. When the button is clicked, a message is logged to the console.

```javascript
document.getElementById("my-button").addEventListener("click", () => {
  console.log("Hello World");
});
```

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Hello World</title>
  </head>
  <body>
    <h1>Hello World</h1>
    <button id="my-button">Click Me</button>
    <script src="/app.js"></script>
  </body>
</html>
```

--------------------------------

### Import CSS and Use Client-Side Libraries in Vinxi App

Source: https://vinxi.vercel.app/guide/a-story

Demonstrates importing a CSS file and a client-side JavaScript library (canvas-confetti) within a Vinxi application. This example shows how Vite, integrated with Vinxi, handles CSS processing and client-side module imports for immediate browser reflection without manual refreshes.

```typescript
import confetti from "canvas-confetti";

import "./app.css";

document.getElementById("my-button").addEventListener("click", () => {
  confetti();
});
```

--------------------------------

### Vinxi App Configuration

Source: https://vinxi.vercel.app/guide/a-story

Configures the Vinxi application with different routers for static files, single-page applications, and HTTP handlers.

```APIDOC
## Vinxi App Configuration

### Description
This configuration sets up the Vinxi application with multiple routers to handle different types of requests.

### Method
N/A (Configuration)

### Endpoint
N/A (Configuration)

### Parameters
N/A

### Request Example
```typescript
import { createApp } from "vinxi";

export default createApp({
  routers: [
    {
      name: "public",
      type: "static",
      dir: "./public",
      base: "/",
    },
    {
      name: "app",
      type: "spa",
      file: "./index.html",
      base: "/",
    },
  ],
});
```

### Response
N/A (Configuration)
```

--------------------------------

### Example Route Object Structure

Source: https://vinxi.vercel.app/guide/file-system-routing

Illustrates the structure of a route object as returned by a file system router. This example shows a route with a `path` and a `$component` dependency, specifying the source file and how to import the default export. This is a basic representation of how routes are defined in Vinxi.

```typescript
export default [
  {
    path: "/hello",
    $component: {
      src: "app/routes/hello.tsx?pick=default",
      import: async () => {
        return await import("app/routes/hello.tsx?pick=default");
      },
    },
  },
];
```

--------------------------------

### Example HTTP Router Configuration - TypeScript

Source: https://vinxi.vercel.app/api/router/http

An example configuration object for the Vinxi HTTP router. This showcases common options such as name, type, handler, base URL, enabling worker threads, and specifying Vite plugins.

```typescript
{
  name: "server",
  type: "http",
  handler: "./app/apiHandler.ts",
  base: "/api",
  worker: true,
  plugins: () => [ reactRefresh() ],
}
```

--------------------------------

### SPA Mode Configuration

Source: https://vinxi.vercel.app/guide/a-story

Configures a router to serve a single-page application (SPA) from a specified HTML file.

```APIDOC
## SPA Mode Configuration

### Description
Configures a router in SPA mode, where all routes map to a single HTML file. This is useful for front-end frameworks.

### Method
N/A (Configuration)

### Endpoint
N/A (Configuration)

### Parameters
N/A

### Request Example
```typescript
import { createApp } from "vinxi";

export default createApp({
  routers: [
    {
      name: "app",
      type: "spa",
      file: "./index.html",
      base: "/",
    },
  ],
});
```

### Response
N/A (Configuration)
```

--------------------------------

### Install Vinxi with npm

Source: https://vinxi.vercel.app/guide/add-to-existing-vite-app

Installs the Vinxi package using npm for adding server-side functionality to Vite projects. This is the initial step to enable Vinxi's features.

```bash
npm install vinxi
```

--------------------------------

### Start Vinxi Development Server (TypeScript)

Source: https://vinxi.vercel.app/api/app

Shows how to initiate the development server for a Vinxi application instance. This method is used internally by the `--dev` flag when running a Vinxi app with Node.js.

```typescript
import { createApp } from "vinxi";

const app = createApp({
  routers: [
    // ... routers
  ],
});

await app.dev();
```

--------------------------------

### Display Vinxi Version Information

Source: https://vinxi.vercel.app/api/cli

Displays the currently installed versions of Vinxi, Vite, Nitro, and H3.

```bash
vinxi version
```

--------------------------------

### Install vite-tsconfig-paths plugin

Source: https://vinxi.vercel.app/guide/aliases

Provides the necessary npm, yarn, pnpm, and bun commands to install the `vite-tsconfig-paths` package as a development dependency. This plugin is crucial for bundler support of tsconfig path aliases.

```bash
npm install vite-tsconfig-paths -D
```

```bash
yarn add vite-tsconfig-paths -D
```

```bash
pnpm install vite-tsconfig-paths -D
```

```bash
bun install vite-tsconfig-paths -D
```

--------------------------------

### Add Basic JavaScript to HTML

Source: https://vinxi.vercel.app/guide/a-story

This snippet shows how to create a simple JavaScript file and link it to an HTML file. The JavaScript code will be executed by the browser when the HTML page loads.

```javascript
console.log("Hello World");
```

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Hello World</title>
  </head>
  <body>
    <h1>Hello World</h1>
    <script src="/app.js"></script>
  </body>
</html>
```

--------------------------------

### Check Vinxi and Dependencies Version CLI

Source: https://context7.com/context7/vinxi_vercel_app/llms.txt

Displays the version information for Vinxi, Vite, Nitro, and H3. This command is useful for verifying installations and compatibility.

```bash
# Show versions of vinxi, vite, nitro and h3
vinxi version
```

--------------------------------

### Example of simplified import with path alias

Source: https://vinxi.vercel.app/guide/aliases

Shows how to use the configured path alias (`@/`) to import components, significantly reducing the length and complexity of the import statement.

```typescript
import Button from "@/components/atoms/Button/Button";
```

--------------------------------

### POST /api/send-email

Source: https://vinxi.vercel.app/guide/a-story

An API endpoint configured to send an email using nodemailer. This handler is executed on the server.

```APIDOC
## POST /api/send-email

### Description
This endpoint handles email sending requests. It uses the nodemailer package to send an email and returns a success message.

### Method
POST

### Endpoint
/api/send-email

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A (The request body is not explicitly defined in the example, but the handler prepares to send an email).

### Request Example
```typescript
// This code would be in your client-side JavaScript
fetch("/api/send-email", {
  method: "POST",
});
```

### Response
#### Success Response (200)
- **string**: A confirmation message, e.g., "done".

#### Response Example
```json
"done"
```
```

--------------------------------

### Using Custom Framework App with Node.js Logic (TypeScript)

Source: https://vinxi.vercel.app/api/app

Demonstrates how to use a custom framework app created with Vinxi and incorporate conditional logic for starting the development server or building the application based on command-line arguments.

```typescript
import { createFrameworkApp } from "framework";

const app = createFrameworkApp();
if (process.argv.includes("--dev")) {
  await app.dev();
} else if (process.argv.includes("--build")) {
  await app.build();
}
```

--------------------------------

### HTTP Handler Router Configuration

Source: https://vinxi.vercel.app/guide/a-story

Configures a router in 'http' mode to handle requests on the server, typically used for API endpoints.

```APIDOC
## HTTP Handler Router Configuration

### Description
Sets up a router in 'handler' mode, allowing custom server-side logic to handle requests. This is used for creating API endpoints or other server functionalities.

### Method
N/A (Configuration)

### Endpoint
N/A (Configuration)

### Parameters
N/A

### Request Example
```typescript
import { createApp } from "vinxi";

export default createApp({
  routers: [
    {
      name: "send-email",
      type: "http",
      handler: "./api/send-email.ts",
      base: "/api/send-email",
      build: {
        target: "server",
      },
    },
  ],
});
```

### Response
N/A (Configuration)
```

--------------------------------

### Getting Request Information API

Source: https://context7.com/context7/vinxi_vercel_app/llms.txt

This API provides access to various details about the incoming request, including URL, host, protocol, and IP address.

```APIDOC
## Getting Request Information API

### Description
Retrieve comprehensive information about the incoming HTTP request, such as the full URL, hostname, protocol, and the client's IP address.

### Method
GET, POST, etc. (Implicit within eventHandler)

### Endpoint
/

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { eventHandler, getRequestURL, getRequestHost, getRequestProtocol, getRequestIP } from "vinxi/http";

export default eventHandler(async (event) => {
  // Get full URL
  const url = getRequestURL(event);
  // url.protocol = "http"
  // url.hostname = "localhost"
  // url.port = "3000"
  // url.pathname = "/products"
  // url.search = "?category=shoes"
  // url.href = "http://localhost:3000/products?category=shoes"

  // Get host
  const host = getRequestHost(event);

  // Get protocol
  const protocol = getRequestProtocol(event);

  // Get IP address
  const ip = getRequestIP(event);

  return { url: url.href, host, protocol, ip };
});
```

### Response
#### Success Response (200)
- **url** (string) - The full URL of the request.
- **host** (string) - The host of the request (e.g., `localhost:3000`).
- **protocol** (string) - The protocol used (e.g., `http` or `https`).
- **ip** (string) - The IP address of the client making the request.

#### Response Example
```json
{
  "url": "http://localhost:3000/api/users?id=1",
  "host": "localhost:3000",
  "protocol": "http",
  "ip": "127.0.0.1"
}
```
```

--------------------------------

### Link CSS File to HTML

Source: https://vinxi.vercel.app/guide/a-story

This snippet illustrates how to link an external CSS file to an HTML document. This allows for styling the elements within the HTML page.

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Hello World</title>
    <link rel="stylesheet" href="/app.css" />
  </head>
  <body>
    <h1>Hello World</h1>
    <button id="my-button">Click Me</button>
    <script src="/app.js"></script>
  </body>
</html>
```

```css
body {
  background-color: #000022;
  color: #fff;
}
```

--------------------------------

### HTTP Event Handler with Vinxi

Source: https://vinxi.vercel.app/api/cli

Exports an HTTP event handler from a script using `vinxi/http` to automatically start a server. The handler function receives an event object and returns a response.

```typescript
import { eventHandler } from "vinxi/http";

export default eventHandler(async (event) => {
  return {
    body: "Hello World",
  };
});
```

--------------------------------

### Get Client Manifest and Assets

Source: https://vinxi.vercel.app/api/manifest

Demonstrates how to retrieve the client manifest and its associated assets. This is often used to match server-side rendered content with client-side hydration by preloading the necessary assets.

```APIDOC
## Get Client Manifest and Assets

### Description
This example shows how to obtain the client-side manifest and then fetch the assets associated with the client handler. These assets are typically required for server-side rendering (SSR) hydration, ensuring that the client has all necessary resources to render the page consistently with the server.

### Method
`GET` (Implicit through the `getManifest` function and asset retrieval)

### Endpoint
`vinxi/manifest` (for `getManifest`)

### Usage

```typescript
import { getManifest } from "vinxi/manifest";
import { eventHandler } from "vinxi/http";

export default eventHandler(async () => {
	const clientManifest = getManifest("client");
	// Assuming clientManifest.handler refers to the main client entry point
	const assets = await clientManifest[clientManifest.handler].assets();

	// Function to render the page with preload links, using the obtained assets
	return renderPageWithPreloadLinks({
		assets,
	});
});

// Example of how to use assets for hydration (client-side):
/*
import { getManifest } from "vinxi/manifest";

const clientManifest = getManifest("client");
const assets = await clientManifest[clientManifest.handler].assets();

// Use 'assets' for hydration logic on the client
*/

// Placeholder for the rendering function
function renderPageWithPreloadLinks(options: { assets: any[] }) {
	console.log("Rendering page with assets:", options.assets);
	// Actual rendering logic would go here
	return "<html><body>Page Content</body></html>";
}
```

### Response Example (Conceptual)

The `assets` variable would contain an array of objects, each representing an asset (like script or link tags) needed for the client.

```json
[
  {
    "tag": "script",
    "attrs": {
      "href": "/_build/client/assets/index.js"
    }
  },
  {
    "tag": "link",
    "attrs": {
      "rel": "stylesheet",
      "href": "/_build/client/assets/style.css"
    }
  }
]
```
```

--------------------------------

### Write Early Hints (TypeScript)

Source: https://vinxi.vercel.app/api/server/response

Allows writing early hints to the client before the main response is sent. This can improve perceived performance by allowing the browser to start fetching resources sooner.

```typescript
export function writeEarlyHints(
  event: HTTPEvent,
  hints: string | string[] | Record<string, string | string[]>,
  cb?: () => void,
): void;

```

--------------------------------

### Get and Update Sessions using Vinxi

Source: https://context7.com/context7/vinxi_vercel_app/llms.txt

Illustrates a more granular approach to session management with Vinxi, using `getSession` to retrieve an existing session and `updateSession` to modify its data. Requires session configuration, including a password.

```typescript
import { eventHandler, getSession, updateSession } from "vinxi/http";

export default eventHandler(async (event) => {
  const config = {
    password: "your-secret-password-at-least-32-characters-long",
  };

  // Get session
  const session = await getSession(event, config);

  // Update session
  await updateSession(event, config, { lastAccess: Date.now() });

  return { session };
});
```

--------------------------------

### Get HTTP Request Information in Vinxi

Source: https://context7.com/context7/vinxi_vercel_app/llms.txt

Illustrates how to retrieve various pieces of information about an incoming HTTP request using functions like `getRequestURL`, `getRequestHost`, `getRequestProtocol`, and `getRequestIP` from 'vinxi/http'.

```typescript
import { eventHandler, getRequestURL, getRequestHost, getRequestProtocol, getRequestIP } from "vinxi/http";

export default eventHandler(async (event) => {
  // Get full URL
  const url = getRequestURL(event);
  // url.protocol = "http"
  // url.hostname = "localhost"
  // url.port = "3000"
  // url.pathname = "/products"
  // url.search = "?category=shoes"
  // url.href = "http://localhost:3000/products?category=shoes"

  // Get host
  const host = getRequestHost(event);

  // Get protocol
  const protocol = getRequestProtocol(event);

  // Get IP address
  const ip = getRequestIP(event);

  return { url: url.href, host, protocol, ip };
});
```

--------------------------------

### Vinxi Default Function Export Script

Source: https://context7.com/context7/vinxi_vercel_app/llms.txt

An example of a TypeScript script for Vinxi that exports a default async function. This function can be executed directly using the `vinxi run` command.

```typescript
// script.ts - Export default function
export default async function () {
  console.log("Hello World");
}
```

--------------------------------

### Configure Vinxi Routers for SPA and Static Files

Source: https://vinxi.vercel.app/guide/a-story

Sets up the basic Vinxi application with routers for serving static files from a directory and a single-page application (SPA) from an HTML entry point. This configuration is a foundational step for web applications managed by Vinxi.

```typescript
import {
  createApp
} from "vinxi";

export default createApp({
  routers: [
    {
      name: "public",
      type: "static",
      dir: "./public",
      base: "/",
    },
    {
      name: "app",
      type: "spa",
      file: "./index.html",
      base: "/",
    },
  ],
});
```

--------------------------------

### Run Vinxi App with Node CLI

Source: https://context7.com/context7/vinxi_vercel_app/llms.txt

Demonstrates executing a Vinxi application file directly using the Node.js CLI. This allows for starting the development server, building the app, or performing other actions based on command-line arguments.

```bash
# Create app without starting server
node app.js

# Start development server
node app.js --dev

# Build for production
node app.js --build
```

--------------------------------

### Install Nodemailer for email functionality

Source: https://vinxi.vercel.app/guide/add-to-existing-vite-app

Installs the Nodemailer package, a popular Node.js module for sending emails. This is required for implementing server-side email sending capabilities within the Vinxi application.

```bash
npm install nodemailer
```

```bash
yarn add nodemailer
```

```bash
pnpm add nodemailer
```

--------------------------------

### Create Basic Vinxi App Configuration

Source: https://context7.com/context7/vinxi_vercel_app/llms.txt

Defines a basic Vinxi application configuration using `createApp`. It sets up two routers: one for static assets and another for HTTP handlers, specifying their directories and target environments.

```typescript
// 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",
    },
  ],
});
```

--------------------------------

### Access Request Router Parameters (TypeScript)

Source: https://vinxi.vercel.app/api/server/response

Functions to retrieve parameters from the URL path defined by a router. `getRouterParams` gets all parameters, `getRouterParam` gets a specific one, and validated versions are also available.

```typescript
getRouterParams(event, { decode? })

```

```typescript
getRouterParam(event, name, { decode? })

```

```typescript
getValidatedRouterParams(event, validate, { decode? })

```

--------------------------------

### File System Router with Multiple Dependencies

Source: https://context7.com/context7/vinxi_vercel_app/llms.txt

This example illustrates a file system router capable of handling multiple types of dependencies for a route. It demonstrates how to specify dynamically imported handlers and data loaders (for code-splitting) alongside statically imported configurations. This allows for fine-grained control over code bundling and loading.

```typescript
class MyFileSystemRouter extends BaseFileSystemRouter {
  toPath(filePath) {
    return filePath.replace(/\.js$/, "");
  }

  toRoute(filePath) {
    return {
      path: this.toPath(filePath),
      // Dynamically imported handler (code-split)
      $handler: {
        src: filePath,
        pick: ["default"]
      },
      // Statically imported config (bundled with main)
      $$config: {
        src: filePath,
        pick: ["config"]
      },
      // Dynamically imported data loader (code-split)
      $data: {
        src: filePath.replace(/\.js$/, ".data.ts"),
        pick: ["default"]
      }
    };
  }
}
```

--------------------------------

### Build Vinxi Application

Source: https://vinxi.vercel.app/api/cli

Builds the application for production. Allows specifying a custom config file with `--config` and a build preset with `--preset` or the `SERVER_PRESET` environment variable.

```bash
vinxi build --config path/to/your-app.js
vinxi build --preset vercel-edge

# OR
SERVER_PRESET=vercel-edge vinxi build
```

--------------------------------

### Build Vinxi App for Production CLI

Source: https://context7.com/context7/vinxi_vercel_app/llms.txt

Builds the Vinxi application for production. Supports specifying build presets like 'vercel-edge' and setting environment variables for configuration. The default preset is 'node-server'.

```bash
# Build app for production (default: node-server preset)
vinxi build

# Build with specific preset
vinxi build --preset vercel-edge

# Using environment variable
SERVER_PRESET=vercel-edge vinxi build
```

--------------------------------

### Create Solid SSR App with Vinxi

Source: https://vinxi.vercel.app/guide/create-your-first-app

This snippet shows how to set up a server-side rendered (SSR) Solid application using Vinxi. It includes configuration for static file serving, client-side rendering, and SSR, utilizing the `vite-plugin-solid` for SolidJS integration. The `ssr: true` option is crucial for enabling SSR with Solid.

```typescript
import { createApp } from "vinxi";
import solid from "vite-plugin-solid";

export default createApp({
  routers: [
    {
      name: "public",
      type: "static",
      dir: "./public",
    },
    {
      name: "client",
      type: "client",
      handler: "./app/client.tsx",
      plugins: () => [solid({ ssr: true })],
      base: "/_build",
    },
    {
      name: "ssr",
      type: "http",
      handler: "./app/server.tsx",
      plugins: () => [solid({ ssr: true })],
    },
  ],
});
```

--------------------------------

### Request Headers API

Source: https://vinxi.vercel.app/api/server/response

APIs for getting request headers.

```APIDOC
## Request Headers API

### Description
Provides functions to retrieve information about incoming request headers.

### Endpoints

#### `getRequestHeaders(event)`
- **Description**: Get all request headers.
- **Method**: `GET` (conceptually)
- **Endpoint**: Not applicable (function call)
- **Parameters**: None
- **Response Example**: `{
  "user-agent": "Mozilla/5.0"
}`

#### `getRequestHeader(event, name)`
- **Description**: Get a specific request header by name.
- **Method**: `GET` (conceptually)
- **Endpoint**: Not applicable (function call)
- **Parameters**:
  - `name` (HTTPHeaderName) - Required - The name of the header to retrieve.
- **Response Example**: `"Mozilla/5.0"`

```

--------------------------------

### Get Cookie API

Source: https://vinxi.vercel.app/api/server/cookies

Retrieves the value of a specific cookie by its name.

```APIDOC
## `getCookie`

### Description
Gets a cookie value by name.

### Method
N/A (Utility function)

### Endpoint
N/A (Utility function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { eventHandler, getCookie } from "vinxi/http"

export default eventHandler(async (event) => {
  const authorization = getCookie(event, "Authorization")
  if (authorization) {
    // ...
  }
})
```

### Response
#### Success Response (N/A)
- **cookieValue** (string | undefined) - The value of the requested cookie, or undefined if not found.

#### Response Example
```json
"cookieValue"
```
```

--------------------------------

### Cookie Utilities

Source: https://vinxi.vercel.app/api/server/response

Utilities for parsing, getting, setting, and deleting cookies.

```APIDOC
## parseCookies

### Description
Parses the `Cookie` header from the request and returns an object of cookie name-value pairs.

### Method
Various (overloaded)

### Endpoint
N/A (Functionality within an event handler)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```ts
const cookies = parseCookies(event);
```

### Response
#### Success Response
- **Record<string, string>** - An object where keys are cookie names and values are cookie values.

#### Response Example
```json
{
  "session_id": "abc123xyz",
  "user_prefs": "theme=dark"
}
```

## getCookie

### Description
Retrieves the value of a specific cookie by its name.

### Method
Various (overloaded)

### Endpoint
N/A (Functionality within an event handler)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```ts
const authHeader = getCookie(event, 'Authorization');
```

### Response
#### Success Response
- **string | undefined** - The value of the cookie, or undefined if not found.

#### Response Example
```json
"Bearer token123"
```

## setCookie

### Description
Sets a cookie by name and value, with optional serialization options.

### Method
Various (overloaded)

### Endpoint
N/A (Functionality within an event handler)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```ts
setCookie(event, 'session_id', 'abc123xyz', { httpOnly: true });
```

### Response
#### Success Response
- **void**

#### Response Example
(No response body for this operation)

## deleteCookie

### Description
Removes a cookie by its name, using optional serialization options.

### Method
Various (overloaded)

### Endpoint
N/A (Functionality within an event handler)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```ts
deleteCookie(event, 'session_id');
```

### Response
#### Success Response
- **void**

#### Response Example
(No response body for this operation)

## getRequestFingerprint

### Description
Generates a fingerprint for the request, useful for identification or tracking. This is an experimental feature.

### Method
Various (overloaded)

### Endpoint
N/A (Functionality within an event handler)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```ts
const fingerprint = await getRequestFingerprint(event);
```

### Response
#### Success Response
- **Promise<string | null>** - A promise that resolves to the request fingerprint string or null.

#### Response Example
```json
"a1b2c3d4e5f6..."
```
```

--------------------------------

### Response Headers API

Source: https://vinxi.vercel.app/api/server/response

APIs for getting, setting, and manipulating response headers.

```APIDOC
## Response Headers API

### Description
Provides functions to interact with HTTP response headers, including retrieving, setting, appending, and clearing them.

### Endpoints

#### `getResponseHeaders(event)`
- **Description**: Get all response headers.
- **Method**: `GET` (conceptually, as it retrieves data)
- **Endpoint**: Not applicable (function call)
- **Parameters**: None
- **Response Example**: `{
  "content-type": "application/json"
}`

#### `getResponseHeader(event, name)`
- **Description**: Get a specific response header by name.
- **Method**: `GET` (conceptually)
- **Endpoint**: Not applicable (function call)
- **Parameters**:
  - `name` (HTTPHeaderName) - Required - The name of the header to retrieve.
- **Response Example**: `"application/json"`

#### `setResponseHeaders(event, headers)`
- **Description**: Set multiple response headers at once.
- **Method**: `POST` (conceptually, as it modifies state)
- **Endpoint**: Not applicable (function call)
- **Parameters**:
  - `headers` (Record<HTTPHeaderName, any>) - Required - An object containing header names and their values.

#### `setResponseHeader(event, name, value)`
- **Description**: Set a specific response header.
- **Method**: `POST` (conceptually)
- **Endpoint**: Not applicable (function call)
- **Parameters**:
  - `name` (HTTPHeaderName) - Required - The name of the header to set.
  - `value` (any) - Required - The value of the header.

#### `appendResponseHeaders(event, headers)`
- **Description**: Append multiple response headers.
- **Method**: `POST` (conceptually)
- **Endpoint**: Not applicable (function call)
- **Parameters**:
  - `headers` (Record<string, string>) - Required - An object containing header names and values to append.

#### `appendResponseHeader(event, name, value)`
- **Description**: Append a value to an existing response header.
- **Method**: `POST` (conceptually)
- **Endpoint**: Not applicable (function call)
- **Parameters**:
  - `name` (HTTPHeaderName) - Required - The name of the header to append to.
  - `value` (string) - Required - The value to append.

#### `clearResponseHeaders(event, headerNames?)`
- **Description**: Clear specified response headers.
- **Method**: `DELETE` (conceptually)
- **Endpoint**: Not applicable (function call)
- **Parameters**:
  - `headerNames` (string[]) - Optional - An array of header names to clear. If not provided, all headers might be cleared (implementation dependent).

#### `removeResponseHeader(event, name)`
- **Description**: Remove a specific response header.
- **Method**: `DELETE` (conceptually)
- **Endpoint**: Not applicable (function call)
- **Parameters**:
  - `name` (HTTPHeaderName) - Required - The name of the header to remove.

#### `writeEarlyHints(event, hints, cb?)`
- **Description**: Write early hints for improved performance.
- **Method**: `POST` (conceptually)
- **Endpoint**: Not applicable (function call)
- **Parameters**:
  - `hints` (string | string[] | Record<string, string | string[]>) - Required - The early hints data.
  - `cb` (function) - Optional - A callback function to execute.

```

--------------------------------

### Configure Static File Server (TypeScript)

Source: https://vinxi.vercel.app/guide/a-story

This TypeScript code configures Vinxi to serve static files from a specified directory ('./public') and map them to the root URL ('/'). This is useful for serving HTML, CSS, and JavaScript files directly.

```typescript
import { createApp } from "vinxi";

export default createApp({
  routers: [
    {
      name: "public",
      type: "static",
      dir: "./public",
      base: "/",
    },
  ],
});
```

--------------------------------

### Response Status Management

Source: https://vinxi.vercel.app/api/server/response

Functions to set and get the HTTP response status code and text.

```APIDOC
## Response Status Management

### Set Response Status

Sets the HTTP response status code and optionally a status text.

- **Method**: `setResponseStatus`
- **Parameters**:
  - `code` (number) - Optional - The HTTP status code.
  - `text` (string) - Optional - The custom status text.

### Get Response Status

Retrieves the current HTTP response status code.

- **Method**: `getResponseStatus`
- **Parameters**:
  - `event` (HTTPEvent) - Optional - The H3 event object.
- **Returns**: (number) - The HTTP status code.

### Get Response Status Text

Retrieves the current HTTP response status text.

- **Method**: `getResponseStatusText`
- **Parameters**:
  - `event` (HTTPEvent) - Optional - The H3 event object.
- **Returns**: (string) - The HTTP status text.
```

--------------------------------

### Create Custom Framework App with Vinxi (TypeScript)

Source: https://vinxi.vercel.app/api/app

Shows how to wrap the `createApp` functionality within a custom function to create a reusable framework app. This allows for pre-configuration of routers and other settings before exporting.

```typescript
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
    ],
  });
}
```

--------------------------------

### SPA Router Configuration with HTML Handler

Source: https://context7.com/context7/vinxi_vercel_app/llms.txt

Sets up a Single Page Application (SPA) router where the handler is an HTML file. This is useful for serving a pre-built SPA. It also shows how to apply Vite plugins like tsconfigPaths.

```typescript
{
  name: "spa",
  type: "spa",
  handler: "./index.html",
  plugins: () => [tsconfigPaths()]
}
```

--------------------------------

### Getting Request Stream API

Source: https://context7.com/context7/vinxi_vercel_app/llms.txt

This API allows you to access the request body as a Web ReadableStream.

```APIDOC
## Getting Request Stream API

### Description
Get the request body as a standard Web ReadableStream, allowing for stream processing of large request bodies.

### Method
POST (Implicit within eventHandler)

### Endpoint
/

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
The raw request body.

### Request Example
```typescript
import { eventHandler, getRequestWebStream } from "vinxi/http";

export default eventHandler(async (event) => {
  const stream = getRequestWebStream(event);

  if (stream) {
    const reader = stream.getReader();
    // Process stream...
  }

  return { hasStream: !!stream };
});
```

### Response
#### Success Response (200)
- **hasStream** (boolean) - Indicates whether a request stream was available.

#### Response Example
```json
{
  "hasStream": true
}
```
```

--------------------------------

### Create Vinxi App with Routers (TypeScript)

Source: https://vinxi.vercel.app/api/app

Demonstrates how to create a Vinxi application instance using `createApp` and configure various routers, such as static file serving and HTTP handlers. This is the primary method for defining the structure of a Vinxi application.

```typescript
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
  ],
});
```

--------------------------------

### Create Vinxi App with Routers (TypeScript)

Source: https://vinxi.vercel.app/api/router

Demonstrates how to create a Vinxi application using `createApp`, configuring both a static router for serving assets from the 'public' directory and an http router for an API.

```typescript
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
      ]
    }
  ],
});
```

--------------------------------

### Get Query Parameters (TypeScript)

Source: https://vinxi.vercel.app/api/server/response

Retrieves all query parameters from an HTTP event. Supports overloaded calls with or without an HTTPEvent object.

```typescript
export function getQuery<T,
	Event extends HTTPEvent = HTTPEvent,
	_T = Exclude<InferEventInput<"query", Event, T>, undefined>,
>(event: Event): _T;
export function getQuery<T,
	Event extends HTTPEvent = HTTPEvent,
	_T = Exclude<InferEventInput<"query", Event, T>, undefined>,
>(): _T;
```

--------------------------------

### Build Vinxi App Programmatically

Source: https://context7.com/context7/vinxi_vercel_app/llms.txt

Programmatically builds the Vinxi application for production using the `createApp` API. This provides an alternative to the CLI for integrating build processes into your application.

```typescript
import { createApp } from "vinxi";

const app = createApp({
  routers: [
    {
      name: "api",
      type: "http",
      handler: "./server.ts",
      target: "server",
    },
  ],
});

// Build for production
await app.build();
```
Tokens:
Raw