---
title: "Install MainSDK"
description: "Install the mainsdk package, CLI and testing kit in a Node.js 22+ TypeScript project and wire it into Next.js, Hono, Express or a worker."
section: "getting-started"
status: "Building for 0.2"
spec: "adapters"
canonical: "https://mainsdk.dev/docs/getting-started/installation"
updated: "2026-10-28"
---

# Install MainSDK

> Install the mainsdk package, CLI and testing kit in a Node.js 22+ TypeScript project and wire it into Next.js, Hono, Express or a worker.

Status: Building for 0.2 · Canonical: https://mainsdk.dev/docs/getting-started/installation · Updated: 2026-10-28

MainSDK is a library, a CLI and an MCP server that live in your repo. There is nothing to host and no sidecar to run: you import it like any other package.

Nothing is published yet: MainSDK is pre-release, and these steps are the planned design. What runs from the repository today, and how to run it, is in the [README](https://github.com/hubxero/mainsdk#quick-start). The Next.js, Hono, Express, worker, Prisma and Drizzle adapters are planned for milestone 0.2.

Starting from an empty folder? Skip to the [quickstart](https://mainsdk.dev/docs/getting-started/quickstart); it creates a Next.js app and runs `init` for you. Read on to add MainSDK to a project you already have, or to wire in a framework other than Next.js.

## Requirements

| You need | Version |
| --- | --- |
| Node.js | 22 or later, with ESM (`"type": "module"`) |
| Language | TypeScript (phases 1 to 4 are TypeScript only) |
| Operating system | Linux x64 or arm64 (glibc and musl), macOS (arm64, x64) or Windows x64 |
| Account | None. Everything runs locally until you choose to run `mainsdk login` |

MainSDK is pure TypeScript with zero runtime dependencies: no native binary, no WebAssembly core and no install scripts.

## Install

Run `init` in the root of your project. It installs the packages, writes a minimal `main.yaml`, adds `.mainsdk/` to `.gitignore` and connects your coding agent. It needs no account and no network.

npm:

```bash
npx mainsdk init
```

pnpm:

```bash
pnpm dlx mainsdk init
```

bun:

```bash
bunx mainsdk init
```


> **Note:** Bun works here as a package manager. Running your app on the Bun runtime, Deno or Cloudflare Workers is phase 5. Until then, run the app on Node.js 22+.

To add the packages by hand instead:

npm:

```bash
npm install mainsdk
npm install --save-dev @mainsdk/cli @mainsdk/testing
```

pnpm:

```bash
pnpm add mainsdk
pnpm add -D @mainsdk/cli @mainsdk/testing
```

bun:

```bash
bun add mainsdk
bun add -d @mainsdk/cli @mainsdk/testing
```


| Package | What it holds |
| --- | --- |
| `mainsdk` | The SDK: every interface, one subpath per adapter (`mainsdk/next`, `mainsdk/hono` …) |
| `@mainsdk/cli` | The `mainsdk` command: `init`, `sync`, `check`, `info`, `logs`, `dev` and more |
| `@mainsdk/testing` | In-memory fakes, assertions, time control and chaos drills for your tests |

The packages are ES modules only (ADR-0045) and ship built files with source maps. `import` them, or `require()` them on Node.js 22.12 or later.

## Wire in your framework

One import puts every request and job behind MainSDK: each gets a trace, its user and market context, the lifecycle hooks, and errors returned as problem details.

Next.js:

```ts
// proxy.ts (middleware.ts on Next.js 15)
import { mainsdk } from "mainsdk/next";
export const proxy = mainsdk.proxy();

// app/api/orders/route.ts
import { withMainSDK } from "mainsdk/next";
import { auth, db } from "mainsdk";

export const GET = withMainSDK(async (req) => {
  const session = await auth.require(req);
  return Response.json(await db.orders.for(session.user).list({ limit: 20 }));
});
```

Hono:

```ts
import { Hono } from "hono";
import { mainsdk } from "mainsdk/hono";

const app = new Hono();
app.use("*", mainsdk());
export default app;
```

Express:

```ts
import express from "express";
import { mainsdk } from "mainsdk/express";

const app = express();
app.use(mainsdk());
// … your routes
app.use(mainsdk.errors());   // last: turns errors into problem details
app.listen(3000);
```

Node worker:

```ts
import { worker } from "mainsdk/worker";
import { log } from "mainsdk";

export default worker(async (job, ctx) => {
  log.info("job started", { job: job.name });   // carries the producer's trace and user
});
```


Next.js support covers the App Router (route handlers, server actions and `proxy.ts` or `middleware.ts`). The Pages Router is not supported.

### Prisma and Drizzle

Wrap your existing client so every query goes through the policy engine and the audit log. `mainsdk check` reports any query made with the unwrapped client (`MAIN-DATA-0001`).

```ts title="lib/db.ts"
import { PrismaClient } from "@prisma/client";
import { withPrisma } from "mainsdk/prisma";

export const prisma = withPrisma(new PrismaClient());
```

```ts title="lib/db.ts"
import { drizzle } from "drizzle-orm/node-postgres";
import { withDrizzle } from "mainsdk/drizzle";
import { pool } from "./pool";

export const db = withDrizzle(drizzle(pool));
```

> **Note:** The adapters ship as beta until each has three production users. Expo and React Native adapters arrive in phase 3.

## Check the install

```bash
npx mainsdk info
```

`info` reads `main.yaml` and prints the app, its interfaces and drivers, network destinations, data labels and regions, and open exceptions. Add `--json` for a versioned document. If it prints your app, you're set.

## What runs when

Nothing is published yet. Milestone 0.2: `init`, `check`, `sync`, `info`, `logs`, `dev` and local `config`, `secrets`, `policy` and `log`. Milestone 0.3: `init --preset`, `add`, `doctor`, `check --json --agent` and local `auth`, `db` and `ai`. Milestone 0.4: the testing kit. Milestone 0.5: public beta, the migration skill and `adopt`.

## Next

- [Quickstart](https://mainsdk.dev/docs/getting-started/quickstart): build a checked app from an empty folder
- [Interfaces and drivers](https://mainsdk.dev/docs/concepts/interfaces-and-drivers)
- [CLI reference](https://mainsdk.dev/docs/reference/cli)