Prisma Next Quickstart

Prisma Next — Quickstart (Adoption)

Edit your data contract. Prisma handles the rest.

This skill takes the user from zero (or near-zero) to a first working query against Prisma Next. Three paths — and they all converge on the same first arc: connect → write → read. Schema editing comes after the first arc, not before.

• First-touch orientation — the user has arrived at a Prisma Next project for the first time (a scaffold tool like npx createprisma dropped them in, they cloned a teammate's repo, or they ran prisma-next init themselves and now want to make their first move) and they're asking "what can I do with Prisma Next?", "where do I start?", or "what's next?". The goal is to anchor them on the contract, get them connected to a database, round-trip one row, and let further commands surface organically.
• Greenfield — new project, fresh database. User runs prisma-next init themselves. init seeds a starter contract with a sample model, so the path joins the first-touch orientation arc as soon as the database is initialised.
• Brownfield-DB — existing database, no contract yet. Infer the contract from the database with contract infer, sign the marker with db sign, then write queries against one of the existing tables.

This skill does not cover migrating from another ORM (Drizzle, Prisma 6/7, Sequelize, TypeORM, Kysely, Knex, raw drivers). Those are separately-installable skills.

When to Use

• User asks "what can I do with Prisma Next?", "what can I do next with Prisma?", "where do I start?", "what should I do first?" — and a PN project already exists on disk. First-touch orientation path below.
• User just ran createprisma (or equivalent scaffold tool) and is asking what to do next. First-touch orientation path.
• User is starting a new project and wants to use Prisma Next. Greenfield path.
• User has an existing database (no PN contract) and wants to introduce PN. Brownfield-DB path.
• User typed "prisma-next init", "get started with PN", "set up PN", "how do I scaffold a project". Greenfield path.
• User says "I have an existing Postgres/Mongo, how do I start using PN?". Brownfield-DB path.

When Not to Use

• User already has a PN project and wants to add a model → prisma-next-contract.
• User wants to migrate FROM a specific ORM → install @prisma-next/migrate-from-<orm>-skill (separate).
• User wants to wire db.ts in a project that already has a contract → prisma-next-runtime.
• User wants to integrate Prisma Next with a build tool (Vite plugin, Next.js, …) → prisma-next-build.

Key Concepts

• Contract: the data model. Authored as contract.prisma (PSL, the canonical surface) or contract.ts (TypeScript builder). The framework reads it and emits two artefacts: contract.json (runtime IR) and contract.d.ts (types).
• Target: the backing store. Today: postgres or mongodb. Picked at init time; baked into the @prisma-next/<target> façade the scaffold imports from.
• Authoring mode: how you write the contract. psl (Prisma Schema Language, default) or typescript (programmatic builder, optionally paired with the Vite plugin for auto-emit during vite dev — see prisma-next-build).
• Façade packages. The scaffold installs exactly one façade per target — @prisma-next/postgres (or @prisma-next/mongo). User code imports from façade subpaths (@prisma-next/postgres/config, @prisma-next/postgres/runtime, @prisma-next/postgres/contract-builder). The façade bakes in the family / target / adapter / driver wiring; never reach past it. See prisma-next-contract for the full list.
• `db.ts`: the runtime entry point. Lives next to the contract source at src/prisma/db.ts. Imports the contract artefacts and exports a db value the rest of the app uses.
• Marker: a pn_meta_marker row in your database that records the contract hash. Lets PN detect drift between contract and live DB. Created by db init (greenfield / first-touch orientation) or db sign (brownfield).

Canonical on-disk layout

Every application that consumes Prisma Next uses the same shape:

<app-root>/
├── prisma-next.config.ts             ← project config at repo root
├── src/
│   └── prisma/
│       ├── contract.prisma           ← (or contract.ts) — schema source you author
│       ├── contract.json             ← emitted by `contract emit` — do not edit
│       ├── contract.d.ts             ← emitted by `contract emit` — do not edit
│       └── db.ts                     ← runtime entry; the rest of `src/` imports from here
└── migrations/
    ├── snapshots/                    ← content-addressed contract store, shared across spaces
    │   └── <hex>/
    │       ├── contract.json
    │       └── contract.d.ts
    └── app/                          ← created on first `migration plan` / `db init`
        ├── refs/head.json
        └── <timestamp>_<slug>/
            ├── migration.json
            ├── ops.json
            └── migration.ts

Three things to internalise:

• `src/prisma/` is the home for the contract — source + emitted artefacts + db.ts all colocated. The rest of src/ imports from ./prisma/db (or ../prisma/db, depending on file depth).
• `migrations/app/` — the app/ segment is the consuming application's space-id. Extensions you depend on get sibling directories under migrations/ (one per extension contract-space), but you don't write into those — only the app/ subtree is your migrations.
• `prisma-next.config.ts` lives at the repo root, not under src/. Every command resolves paths relative to the config's directory.

Contributors building extension packages or aggregate-root monorepo packages use a different layout — src/contract.{prisma,ts} (no prisma/ subdir) + migrations/<timestamp>_<slug>/ (no app/ segment). That distinction is intentional; see prisma-next-contract for which path applies to you.

Heads up — `prisma-next init` currently scaffolds the wrong layout. It writes prisma/contract.{prisma,ts} and prisma/db.ts at the repo root instead of under src/prisma/. Tracked as TML-2532. Until the fix lands, either pass --schema-path src/prisma/contract.prisma to init, or move the scaffolded prisma/ directory into src/prisma/ after init and update the contract path in prisma-next.config.ts to match. The canonical layout above is what the demo example uses and what the rest of the framework expects.

Your first arc — connect, write, read

All three paths in this skill converge here. Once the project is scaffolded and the database is reachable, the first move is always the same: connect, write a row, read it back, against whatever model the contract already declares. Don't touch the contract source on this first move — extend it later, after the round-trip works.

Write the snippet in a fresh file directly under src/ (e.g. src/first-arc.ts) so the relative import resolves to one level deep:

// src/first-arc.ts
import 'dotenv/config';
import { db } from './prisma/db';

// Write a row against the starter model. Adapt the field names to whatever
// model your contract source actually declares — read it first.
await db.orm.User.create({ email: 'alice@example.com' });

// Read it back.
const users = await db.orm.User.select('id', 'email').all();
console.log(users);

If that prints [{ id: 1, email: 'alice@example.com' }], the project is wired end-to-end and the user has crossed from "I have a project" to "I'm building."