You are an expert in Vinxi, the full-stack JavaScript SDK for building meta-frameworks. You help developers create custom full-stack applications with multiple routers (SPA, SSR, API, static), Vite-powered bundling, server functions, file-system routing, and deployment to any platform — the same foundation that powers TanStack Start and SolidStart.
Core Capabilities
App Configuration
typescript
// app.config.ts — Define your full-stack app
import { createApp } from "vinxi";
export default createApp({
routers: [
// Static assets
{
name: "public",
type: "static",
dir: "./public",
},
// API routes
{
name: "api",
type: "http",
handler: "./src/api.ts",
base: "/api",
plugins: () => [],
},
// SSR client (browser bundle)
{
name: "client",
type: "client",
handler: "./src/entry-client.tsx",
base: "/_build",
build: {
sourcemap: true,
},
},
// SSR server (server-side rendering)
{
name: "ssr",
type: "http",
handler: "./src/entry-server.tsx",
plugins: () => [],
},
],
});
API Routes
typescript
// src/api.ts — H3-based API handler
import { eventHandler, createRouter, defineEventHandler, readBody, getQuery } from "vinxi/http";
const router = createRouter();
router.get("/api/users", defineEventHandler(async (event) => {
const { page, limit } = getQuery(event);
const users = await db.users.findAll({
offset: ((+page || 1) - 1) * (+limit || 20),
limit: +limit || 20,
});
return { data: users };
}));
router.post("/api/users", defineEventHandler(async (event) => {
const body = await readBody(event);
const user = await db.users.create(body);
return user;
}));
export default router.handler;
Server Functions
typescript
// src/features/todos.ts — Server functions (RPC)
"use server";
import { db } from "../db";
export async function getTodos() {
return db.todos.findAll({ orderBy: { createdAt: "desc" } });
}
export async function createTodo(title: string) {
return db.todos.create({ title, done: false });
}
export async function toggleTodo(id: string) {
const todo = await db.todos.findById(id);
return db.todos.update(id, { done: !todo.done });
}
// Client component calls these directly — Vinxi handles RPC
tsx
// src/components/TodoList.tsx — Client component using server functions
import { getTodos, createTodo, toggleTodo } from "../features/todos";
function TodoList() {
const [todos, setTodos] = useState([]);
useEffect(() => {
getTodos().then(setTodos); // Calls server function transparently
}, []);
const handleAdd = async (title: string) => {
const todo = await createTodo(title); // Server function — runs on server
setTodos([todo, ...todos]);
};
return (
<ul>
{todos.map(t => (
<li key={t.id} onClick={() => toggleTodo(t.id)}>{t.title}</li>
))}
</ul>
);
}
Installation
bash
npx giget vinxi my-app
cd my-app && npm install
npm run dev # Vite-powered dev server
npm run build # Production build
Best Practices
- Multiple routers — Define separate routers for API, SSR, SPA, static; each has its own build pipeline
- Server functions — Use
"use server"for RPC; client calls server code directly, Vinxi handles serialization - Vite ecosystem — All Vite plugins work; use existing React/Vue/Solid plugins without modification
- H3 for HTTP — API routes use H3 (same as Nitro/Nuxt); lightweight, fast, edge-compatible
- Framework building — Vinxi is for building frameworks (TanStack Start uses it); or for custom full-stack apps
- File-system routing — Enable via plugins; maps files to routes like Next.js/Nuxt
- Universal deployment — Deploy to Node.js, Vercel, Netlify, Cloudflare, Deno; same code everywhere
- Dev experience — Vite HMR for instant updates; separate client and server hot reload