Vinxi Toolkit

Vinxi is a JavaScript toolkit designed for building full-stack applications and metaframeworks. It leverages Vite for bundling and development server capabilities, and Nitro as a universal production server.

Its core primitive is the router, which allows you to define how different URL groups are handled by specifying a configuration object. This makes it ideal for building frameworks with specific opinions on SSR (Server-Side Rendering), SPA (Single Page Application), or RSC (React Server Components).

The Manifest API provides a data structure that allows different environments (server and client) to coordinate work. A manifest tells the runtime about the current router and other routers, including information produced by the bundler about which files are involved in each router and the assets they use.

Behavior across environments:

• Development: The manifest is generated on the fly (Vite-style).
• Production: The manifest is generated by the bundler, saved to disk, and then read by the runtime from disk.

The API remains consistent across server/client and development/production environments.

Vinxi can be wrapped inside a custom function or framework to provide a pre-configured set of routers, middlewares, and settings. This allows you to create a high-level abstraction that end-users can then use to start their own development or build processes.

// framework.ts
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" },
    ],
  });
}

// app.js
import { createFrameworkApp } from "framework";
export default createFrameworkApp();

// 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();
}

Vinxi provides several built-in router types to handle different web patterns:

• static: Used for serving uncompiled, static assets (requires a dir and base path).
• http: Used for creating traditional web servers or API endpoints (requires a handler and base path).
• spa: Used for building and serving Single Page Application (SPA) assets.
• client: Used for building and serving Server-Side Rendering (SSR) application assets.
• custom: Allows you to adapt Vinxi to specific, non-standard use cases.

The Custom Router API allows you to define routers with specialized behavior or configurations that fall outside the predefined router types. This is intended for advanced use cases where you need to programmatically resolve router configurations or implement custom routing logic.

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

The spa router is used to specify a single entrypoint for serving Single Page Applications (SPAs). It allows you to define an HTML entry point and configure how the application is served under a specific base URL, including the ability to inject Vite plugins and define custom routing logic.

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

When defining a Route object in a CompiledRouter, you can attach file dependencies using specific prefixes. This controls how the files are bundled and loaded:

• $ prefix (Dynamic Import): The file is imported dynamically. This is the recommended way to achieve code-splitting, as the file will be bundled into a separate chunk. Use this for route handlers, components, or data loaders.
• $$ prefix (Static Import): The file is imported statically. It will be included in the main bundle. Use this only for critical information required immediately for the application to function where network latency is unacceptable.

Each dependency object requires a src field (the file path) and an optional pick array (to specify which named exports to use).

The client router acts as a wrapper for Vite's build processes and development server. It is designed to facilitate the integration of an http router within server-side rendering (SSR) applications by managing client-side assets and entry points.

// Example configuration for a client router
{
  name: "client",
  type: "client",
  handler: "./app/client.tsx",
  base: "/_build",
  plugins: () => [ reactRefresh() ],
}

When defining a custom router, you must provide specific properties that differ from standard routers. Most notably, the type property must be an object containing a resolveConfig function instead of a string literal, and the target must be explicitly set to 'server'.

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

Once a static router is configured (e.g., pointing to ./public), any files placed in that directory will be accessible via the configured base path. For example, if dir is ./public and base is /, an index.html file in the public folder will be served at http://localhost:3000/.

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

The http router is a wrapper around a Nitro web server. It is used for server-side rendering (SSR), handling WebSockets, and creating custom API endpoints. When defining an http router, you must provide a unique name and a handler file which serves as the entry point for Nitro to handle HTTP requests.

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