Vinxi: composing full stack JavaScript apps from Vite and Nitro routers

The problem Vinxi solves is metaframework wiring, not app code

Building a Next.js or SolidStart style framework on Vite means solving the same set of problems every time: producing a full stack build, tracking which assets to load at production runtime, handling assets during development without a flash of unstyled content in SSR, and smoothing over Vite's dev and prod differences behind manifest APIs that behave the same in both. The README states the primary goal is to build the tools needed to build such a metaframework on top of Vite "without worrying about a lot of the wiring". That framing is the honest one. Vinxi is not a framework you write pages in. It is the layer a framework author writes once so the framework's users never see it. The README puts it as trying to "disappear for the user outside the app.js file". If you are an application developer choosing a stack, you are not the target reader; you are the person the target reader is building for.

Routers are the primitive: how Vinxi splits a URL space

The core primitive is the router, described in the README as a brief specification defining how a group of URLs should be handled. Vinxi ships several router types: static for uncompiled assets, http for traditional web servers, spa for single page application assets, client for SSR application assets, and custom for adapting Vinxi to a use case it does not cover. An app is a createApp call whose routers array holds one specification object per group of URLs. Each router carries a name, a type, a base path, and a dir or handler pointing at the source, plus a plugins function that returns Vite plugins scoped to that router alone. That last part is the mechanism worth understanding: plugin scoping is per router, so a transform applied to an API handler does not leak into the static asset pipeline. Underneath, Vite handles bundling and the dev server while Nitro handles the production server, and the README says the design is inspired by the Bun.App API. The data flow is therefore not a single build but several coordinated ones, one per router, with manifests produced for each so the production runtime knows what to load.

Installing Vinxi and defining a first app

Vinxi is published on npm as vinxi, and the repository's release entries show it at version 0.5.8. The README does not spell out a create command, so the practical first step is adding the package to a project and writing the config file that createApp expects. The README's own example is a TypeScript file exporting a createApp call. A minimal version with a static router and an HTTP router looks like this:

import { createApp } from "vinxi";

export default createApp({
  routers: [
    {
      name: "public",
      type: "static",
      dir: "./public",
      base: "/",
    },
    {
      name: "api",
      type: "http",
      handler: "./app/api.ts",
      base: "/api",
    },
  ],
});

The static router serves files from ./public at the root, and the http router sends everything under /api to ./app/api.ts. The README shows a plugins key on the http router as well, a function returning an array of Vite plugins that apply only to that router. The repository's Dockerfile gives the production entry point: the image builds the monorepo, sets the working directory to packages/vinxi, exposes port 3000, and runs /repo/packages/vinxi/bin/cli.mjs with the arguments run and /script.tsx. That tells you the CLI takes run plus a script path. The README does not document the full flag set for that command, so treat anything beyond run and a path as unverified.

Where Vinxi stops being the right tool

The clearest limitation is audience. Vinxi gives you routers, manifests and a dev server contract; it does not give you routing conventions, data loading patterns, or a component model. A team that wants file-based routes and a documented data-fetching story will end up rebuilding that on top of Vinxi, which is exactly the work SolidStart has already done. The README lists SolidStart as a framework actively being developed on vinxi and mentions AngularStart among frameworks experimenting with it, which is a useful signal about where the maintenance attention sits: the framework consuming Vinxi is the thing most users should evaluate. The second limitation is documentation depth. The README describes goals and the router list, but it does not document rollback, version compatibility between Vinxi releases and framework releases, or the full CLI surface. The third is the release cadence visible in the repository's release list: the newest listed release is [email protected] from 2025-06-29, and the repository's last push was on 2026-03-21. That is a pre-1.0 line with a gap between the last published release and the last commit, so pinning versions and reading the changelog is not optional.

Vinxi compared with using Vite and Nitro directly

The real alternative is not another framework; it is wiring Vite and Nitro yourself. Vite gives you the bundler and dev server, Nitro gives you the production server, and the gap between them is precisely what Vinxi fills: coordinating multiple builds, generating and consuming manifests so the production runtime loads the right assets, and making dev and prod behave the same through common manifest APIs. Doing that by hand means owning the parts of a metaframework that have nothing to do with your product. The trade is control against maintenance. Direct Vite plus Nitro lets you shape the build however you want and depend on two widely used projects with their own release cycles. Vinxi adds a layer that is itself pre-1.0 and whose releases you must track alongside the two it wraps. If your application is a single SPA with a small API, that layer is overhead; a plain Vite build plus a Nitro server covers it. If you are shipping a framework with SSR, SPA and RSC variants that all need consistent asset handling, the coordination Vinxi provides is the part you would otherwise write and debug.

Licence, upgrades and the cost of a pre-1.0 dependency

Vinxi is MIT licensed, which permits commercial use and modification; the repository carries a LICENSE file at the top level and the README does not add terms beyond it. This is not legal advice, and anyone embedding Vinxi in a product should read the LICENSE file in the repository rather than rely on a summary. The upgrade cost is the more practical concern. The packages directory and the changesets directory in the repository layout indicate a monorepo releasing through changesets, and the release list shows vinxi and @vinxi/router versioned in lockstep at 0.5.8. That means a Vinxi bump can move the router package with it, so a framework built on Vinxi should pin both and test the pair together. The root package.json pins the package manager as [email protected] and declares private: true, so the repository itself is not published as a package; only the contents of packages/ are. There is no stated support window or deprecation policy in the README, so plan upgrades around the changesets that accompany each release rather than around a compatibility promise.

Editorial conclusion

Vinxi is for people building a metaframework or a bespoke full stack stack, not for teams that just want to ship a React or Solid app: SolidStart already sits on top of it, so picking SolidStart is the shorter path. Before adopting, confirm which router types your deployment target needs, check whether the dev and prod manifest behaviour you rely on is covered by the router you pick, and pin the version you test against, since the published releases are 0.5.x and the repository's last push was on 2026-03-21.

Frequently asked questions

Official sources

1. License: MIT
2. nksaraf/vinxi on GitHub
3. Project website
4. README
5. Releases