# Neon JavaScript/TypeScript packages
The monorepo for [Neon](https://neon.com)'s open-source JavaScript/TypeScript SDKs, libraries, CLIs, and framework plugins. Each folder under [`packages/`](./packages) is an independently versioned, separately published package; they share tooling (pnpm workspaces, Biome, tsdown, Vitest, Changesets) but ship on their own cadence.
If you're looking for a single package's docs, see its own `README.md` under `packages/<name>/`.
Apps and starters that work with these packages live in [`neondatabase/examples`](https://github.com/neondatabase/examples).
## Packages
### Neon CLI
| Package | Description |
| --- | --- |
| `neon` | The Neon CLI. Install this package for the `neon` command. |
| `neonctl` | Compatibility package that delegates to `neon`. Provides the legacy `neonctl` command (plus `neon`) and is what Homebrew builds from. |
### Config-as-Code (`neon.ts`)
| Package | Description |
| --- | --- |
| `@neon/config` | Config-as-Code for Neon: `defineConfig` types + the pure diff engine and Neon API adapter behind a `neon.ts` policy. |
| `@neon/config-runtime` | Runtime for `neon.ts` policies — `inspect` / `plan` / `apply` (push/pull) plus function bundling and deploy. |
| `@neon/env` | Resolve and inject a branch's Neon env (`fetchEnv` / `parseEnv`, `neon-env run`) from a `neon.ts` policy. |
### API & integrations
| Package | Description |
| --- | --- |
| `@neon/sdk` | The official TypeScript SDK for the Neon API — a modern, Fetch-based client generated from Neon's OpenAPI spec (successor to `@neondatabase/api-client`). |
| `@neon/tools` | Type-safe agent tools for the `@neon/sdk` ergonomic client, with MCP, Eve, and Mastra adapters. |
| `@neon/effect` | Effect v4 bindings for the `@neon/sdk` ergonomic client: Effects, paginated Streams, tagged errors and request cancellation on interruption. |
| `@neon/functions` | Runtime helpers for Neon Functions: `waitUntil`, `upgradeWebSocket` (fetch handler or Hono route via `@neon/functions/hono`), `attachDatabasePool`, and `parseTriggerInvocation` (`@neon/functions/triggers`). |
| `@neon/ai-sdk-provider` | Community [Vercel AI SDK](https://ai-sdk.dev) provider for the Neon AI Gateway. |
| `@neon/convex-to-postgres` | Migrate a Convex deployment to Neon Postgres with `npx @neon/convex-to-postgres` or as a library: generate DDL (including Neon Lakebase Search indexes) from a Convex schema and load a `convex export` snapshot. |
### Realtime
| Package | Description |
| --- | --- |
| `@neon/realtime` | Typed backend and browser SDKs for defining and consuming live queries in realtime. |
| `@neon/realtime-react` | React provider and hook for live-query subscriptions. |
| `@neon/realtime-tanstack` | TanStack DB collection integration for live-query subscriptions. |
| `@neon/realtime-drizzle` | Drizzle adapter for type-safe live queries. |
| `@neon/realtime-kysely` | Kysely adapter for type-safe live queries. |
### Auth & data access
| Package | Description |
| --- | --- |
| `@neon/auth` | Authentication adapters for Neon Auth (Supabase-compatible and Better Auth APIs), with React, Next.js, and framework-agnostic server toolkit entrypoints. |
| `@neon/postgrest-js` | Generic PostgreSQL client for the Neon Data API without built-in authentication. |
| `@neon/neon-js` | Unified client combining Neon Auth and the Neon Data API, with automatic token injection into database queries. |
| `@neon/oauth` | OAuth helpers for apps that use Neon Auth as an OAuth provider: PKCE sign-in, access-token verification, and MCP server protection (with Hono, Express, Next.js and `node:http` adapters). |
`neon-new` and `vite-plugin-neon-new` are **deprecated**. Use Claimable Neon in the Neon CLI: `npx neon@latest claim create`. The old alias packages (`get-db`, `neondb`, `vite-plugin-db`, `@neondatabase/vite-plugin-postgres`) still re-export them.
`neonctl` is not deprecated: it is a supported compatibility package that installs and runs `neon`.
`neon-init` is **deprecated and no longer built from this repo**. Everything it did is the
`neon init` command, so the command is `npx neon init`. There is no alias package: it was a
CLI rather than a library, and the replacement is a command on a CLI most users already have.
## Repository layout
```
packages/ # the published SDKs, libraries, CLIs, and plugins (one per folder)
tests/ # test-only tooling that is never published (the live Neon e2e harness)
```
This is a [pnpm workspace](https://pnpm.io/workspaces). Internal dependencies are linked with `workspace:*`, so changes to one package are immediately visible to its dependents without republishing.
## Development
Contributing to this repo requires **Node.js >= 22** and [pnpm](https://pnpm.io) — pnpm itself needs Node 22.13+, and regenerating the `@neon/sdk` types needs Node 22.18+. The **published packages** support **Node.js >= 20.19** at runtime (see each package's README and `CONTRIBUTING.md`). From the repo root:
```bash
pnpm install # install all workspaces
pnpm build # build every package (tsc + tsdown)
pnpm test:ci # run the test suites (Vitest)
pnpm lint:ci # lint + format check (Biome)
```
Scope a command to a single package with a filter, e.g.:
```bash
pnpm --filter @neon/env build
pnpm --filter @neon/env test:ci
```
## Releasing
Versioning is driven by [Changesets](https://github.com/changesets/changesets). Add a changeset describing your change (`pnpm changeset`), and a maintainer applies the version bumps + changelogs (`pnpm changeset version`) on a release PR. Publishing to npm runs from a separate workflow once that PR lands on `main`.
## License
Every package in this repository is licensed under **Apache-2.0**.