Why Pothos and Prisma Is the Stack Worth Learning Right Now
Building a GraphQL API used to mean hours of boilerplate — manual type definitions, resolvers that drifted out of sync with your database schema, and runtime errors that only appeared in production. In 2026, that approach is obsolete.
The combination of Pothos (a code-first GraphQL schema builder) and Prisma (a type-safe ORM) eliminates almost all of that friction. Your database schema drives your GraphQL types automatically. TypeScript catches mismatches at compile time. And the Pothos Prisma plugin generates cursor-based pagination, filtering, and relation resolvers with minimal manual code.
This tutorial walks you through building a production-ready GraphQL API from scratch — the kind of backend that underpins SaaS dashboards, mobile apps, and e-commerce platforms for SMBs in Australia, Singapore, Canada, and the US.
What You'll Need
- Node.js 20+ and npm/pnpm installed
- A PostgreSQL database (local via Docker or a hosted instance on Supabase, Railway, or Neon)
- TypeScript familiarity — intermediate level
- Basic understanding of GraphQL concepts (queries, mutations, resolvers)
Step 1: Initialise the Project
Create a new Node.js project and install core dependencies:
mkdir graphql-api && cd graphql-api
npm init -y
npm install @pothos/core @pothos/plugin-prisma @prisma/client graphql graphql-yoga
npm install -D typescript ts-node @types/node prismaInitialise TypeScript:
npx tsc --initUpdate your tsconfig.json to include these key options:
{
"compilerOptions": {
"target": "ES2022",
"module": "CommonJS",
"strict": true,
"outDir": "dist",
"rootDir": "src"
}
}Pro tip: Use pnpm instead of npm if you are working inside a monorepo — it handles shared dependencies far more efficiently.
Step 2: Define Your Prisma Schema
Initialise Prisma:
npx prisma initThis creates a prisma/schema.prisma file and a .env file. Update .env with your database connection string:
DATABASE_URL="postgresql://user:password@localhost:5432/myapp"Now define a simple data model. For this tutorial, we will build the backend for a project management tool — a common requirement for SMB clients:
// prisma/schema.prisma
generator client {
provider = "prisma-client-js"
}
generator pothos {
provider = "prisma-pothos-types"
}
datasource db {
provider = "postgresql"
url = env("DATABASE_URL")
}
model User {
id String @id @default(cuid())
email String @unique
name String
projects Project[]
createdAt DateTime @default(now())
}
model Project {
id String @id @default(cuid())
title String
description String?
owner User @relation(fields: [ownerId], references: [id])
ownerId String
tasks Task[]
createdAt DateTime @default(now())
}
model Task {
id String @id @default(cuid())
title String
done Boolean @default(false)
project Project @relation(fields: [projectId], references: [id])
projectId String
createdAt DateTime @default(now())
}Run the migration to create your tables:
npx prisma migrate dev --name init
npx prisma generateCommon pitfall: If you skip npx prisma generate after schema changes, the Prisma client will not reflect your latest model and you will get confusing TypeScript errors downstream.
Step 3: Set Up the Pothos Schema Builder
Install the Prisma plugin for Pothos and its type generator:
npm install @pothos/plugin-prisma prisma-pothos-typesCreate src/builder.ts:
import SchemaBuilder from '@pothos/core';
import PrismaPlugin from '@pothos/plugin-prisma';
import { PrismaClient } from '@prisma/client';
import type PrismaTypes from '../prisma/pothos-types';
export const prisma = new PrismaClient();
export const builder = new SchemaBuilder<{
PrismaTypes: PrismaTypes;
}>({
plugins: [PrismaPlugin],
prisma: {
client: prisma,
exposeDescriptions: true,
filterConnectionTotalCount: true,
},
});This is the core of what makes Pothos powerful: the schema builder is fully aware of your Prisma types at compile time. Any resolver that returns the wrong shape will fail TypeScript — not at runtime in front of users.
Step 4: Define Your GraphQL Types
Create src/types/user.ts:
import { builder } from '../builder';
builder.prismaObject('User', {
fields: (t) => ({
id: t.exposeID('id'),
email: t.exposeString('email'),
name: t.exposeString('name'),
projects: t.relation('projects'),
createdAt: t.expose('createdAt', { type: 'DateTime' }),
}),
});Create src/types/project.ts:
import { builder } from '../builder';
builder.prismaObject('Project', {
fields: (t) => ({
id: t.exposeID('id'),
title: t.exposeString('title'),
description: t.exposeString('description', { nullable: true }),
owner: t.relation('owner'),
tasks: t.relation('tasks'),
createdAt: t.expose('createdAt', { type: 'DateTime' }),
}),
});Notice that you never write a separate TypeScript interface to mirror your Prisma model. The prismaObject method reads directly from the generated types. This is the key productivity gain teams at agencies like Lenka Studio rely on when shipping client backends quickly.
Step 5: Build Queries and Mutations
Create src/schema/query.ts:
import { builder, prisma } from '../builder';
builder.queryType({
fields: (t) => ({
me: t.prismaField({
type: 'User',
nullable: true,
resolve: async (query, _root, _args, ctx) => {
// In production, derive userId from your auth context
return prisma.user.findUnique({
...query,
where: { id: ctx.userId },
});
},
}),
projects: t.prismaField({
type: ['Project'],
resolve: async (query, _root, _args, ctx) => {
return prisma.project.findMany({
...query,
where: { ownerId: ctx.userId },
orderBy: { createdAt: 'desc' },
});
},
}),
}),
});The ...query spread is a critical Pothos pattern. It passes Prisma query hints that automatically include only the relations the GraphQL client actually requested — solving the N+1 problem without a DataLoader.
Create src/schema/mutation.ts for write operations:
import { builder, prisma } from '../builder';
builder.mutationType({
fields: (t) => ({
createProject: t.prismaField({
type: 'Project',
args: {
title: t.arg.string({ required: true }),
description: t.arg.string(),
},
resolve: async (query, _root, args, ctx) => {
return prisma.project.create({
...query,
data: {
title: args.title,
description: args.description,
ownerId: ctx.userId,
},
});
},
}),
toggleTask: t.prismaField({
type: 'Task',
args: { id: t.arg.id({ required: true }) },
resolve: async (query, _root, args) => {
const task = await prisma.task.findUniqueOrThrow({
where: { id: args.id },
});
return prisma.task.update({
...query,
where: { id: args.id },
data: { done: !task.done },
});
},
}),
}),
});Step 6: Wire Up the Server
Create src/index.ts:
import { createServer } from 'node:http';
import { createYoga } from 'graphql-yoga';
import './types/user';
import './types/project';
import './schema/query';
import './schema/mutation';
import { builder } from './builder';
const schema = builder.toSchema();
const yoga = createYoga({
schema,
context: async ({ request }) => ({
// Replace with real JWT/session auth
userId: request.headers.get('x-user-id') ?? '',
}),
});
const server = createServer(yoga);
server.listen(4000, () => {
console.log('GraphQL API running at http://localhost:4000/graphql');
});Start the server:
npx ts-node src/index.tsOpen http://localhost:4000/graphql to access the GraphQL Yoga playground and run your first query.
Step 7: Add Input Validation
Install the Zod validation plugin:
npm install @pothos/plugin-zod zodUpdate your builder to include it, then wrap mutation args:
args: {
title: t.arg({
type: 'String',
required: true,
validate: { minLength: 3, maxLength: 120 },
}),
},Pro tip: Validating at the GraphQL layer — before touching Prisma — keeps your database clean and your error messages user-friendly. This matters especially for client-facing SaaS products where input quality directly affects data integrity.
Step 8: Deploy to a Production Edge
GraphQL Yoga runs natively on Cloudflare Workers, making it an excellent fit for low-latency APIs serving users across Australia, Singapore, and North America from a single deployment.
Install the Wrangler CLI and create a wrangler.toml, then update your entry point to export a fetch handler instead of using createServer. Refer to the Cloudflare Workers documentation for the current deployment workflow — the process is straightforward once your schema is working locally.
Common pitfall: Prisma's default client does not work in edge runtimes. Use Prisma Accelerate or switch your data layer to Drizzle ORM if you need a true edge-native deployment.
Next Steps
You now have a fully type-safe GraphQL API backed by a real PostgreSQL database — built without a single hand-written TypeScript interface for your data layer. From here, the natural next moves are:
- Add authentication using JWTs with the @pothos/plugin-scope-auth package to lock down resolvers per user role
- Implement cursor-based pagination using the built-in Pothos connection helpers for large datasets
- Write integration tests against a test database using Vitest and Prisma's test environment utilities
- Set up subscriptions with GraphQL Yoga's built-in WebSocket support for real-time features
If you are building a product backend and want an experienced team to architect it correctly from the start — or you need to move faster than your current in-house capacity allows — the team at Lenka Studio works with SMBs across Australia, Singapore, Canada, and the US to deliver scalable, production-ready backends. Get in touch to talk through your project.
