Use @superinterface/server inside an existing Next.js app

The server package publishes fully built REST handlers you can drop straight into any Next.js App Router project. This lets you keep your own UI while reusing the production-grade API that powers Superinterface Cloud.

Prerequisites

Next.js 15.5+ running with the App Router.

@superinterface/server installed in your project (npm install @superinterface/server).

Environment variables from the self-hosting overview (at minimum DATABASE_URL, DIRECT_URL, NEXT_PUBLIC_SUPERINTERFACE_BASE_URL, and optionally DATABASE_ADAPTER, QSTASH_TOKEN, etc.).

A Prisma client instance you can pass to the route builders.

The package expects Node.js 20+. If you deploy on Vercel, set the runtime to Node.js 20 in your project settings.

1. Expose a Prisma client

Point your project at the same Postgres instance the API uses:

lib/prisma.ts

import { PrismaClient } from '@prisma/client' const globalForPrisma = globalThis as unknown as { prisma?: PrismaClient } export const prisma = globalForPrisma.prisma ?? new PrismaClient({ log: process.env.NODE_ENV === 'development' ? ['error', 'warn'] : ['error'], }) if (!globalForPrisma.prisma) { globalForPrisma.prisma = prisma }

When you deploy on Neon/Vercel Postgres, keep DATABASE_ADAPTER=neon (default). For Supabase or any standard Postgres provider, set DATABASE_ADAPTER=direct.

2. Mount a route handler

Import the generated handlers from @superinterface/server/next/api/.../buildRoute. Each builder returns the HTTP methods you can re-export from your route.ts.

app/api/assistants/route.ts

import { prisma } from '@/lib/prisma' import { buildGET, buildPOST, buildOPTIONS, } from '@superinterface/server/next/api/assistants/buildRoute' export const GET = buildGET({ prisma }) export const POST = buildPOST({ prisma }) export const OPTIONS = buildOPTIONS()

Mounting the handlers under /api/** mirrors the packaged server, so your frontend can call the same relative paths. You can cherry-pick only the endpoints you need. For example, the tasks API lives at @superinterface/server/next/api/tasks/buildRoute, files under .../files/buildRoute, and so on. Browse the package exports for the full list.

3. Configure dynamic rendering

Most routes interact with the database or external services, so mark them as dynamic when needed:

export const dynamic = 'force-dynamic' export const runtime = 'nodejs'

Follow the same pattern as other server actions in your project to avoid accidental caching.

4. Run migrations and seed data

Use the bundled CLI to set up the schema and create credentials:

npx @superinterface/server prisma deploy npx @superinterface/server organizations create npx @superinterface/server organizations api-keys create

Store the organization API key in whatever secret manager you use, then call your newly mounted endpoints with that key in the Authorization: Bearer header.

5. Optional: extend the handlers

Because you import the builders directly, you can:

Inject custom middleware (for example, wrap buildPOST with your own auth check before calling the handler).

Create hybrid routes—serve Superinterface endpoints under a /cloud/* segment while keeping your own bespoke APIs elsewhere.

Import the shared utilities (for example @superinterface/server/lib/assistants/serializeApiAssistant) to reuse serialization logic in your UI.

That’s all you need to plug the Superinterface REST API into an existing Next.js deployment without managing two separate servers.