Next.js
Reylo in the Next.js App Router
Your server code imports .sql files, and the build checks their types. Usage covers running a query.
| Config | withReylo from reylo/next, around your Next.js config |
| Bundlers | Turbopack, and webpack with --webpack |
| Queries run in | Server components, route handlers and server actions |
| Edge runtime | A driver that connects over HTTP or WebSockets, such as Neon's |
| Example | nextjs, a Next.js 16.4 app on Postgres with a page, a server action and a route handler |
View the schema behind the examples
create table users (
id serial primary key,
name text not null,
email text
);
create table posts (
id serial primary key,
user_id integer not null references users (id),
title text not null,
body text
);Setup
Wrap your Next.js config with withReylo, which loads .sql files in server code:
import type { NextConfig } from "next";
import { withReylo } from "reylo/next";
const nextConfig: NextConfig = {
// ...
};
export default withReylo(nextConfig);Add Reylo to tsconfig.json as a content mapper, as in Setup:
{
"compilerOptions": { /* ... */ },
"contentMappers": [{ "package": "reylo" }]
}To type-check without building, run next typegen first, which writes the route types:
{
"scripts": {
"typecheck": "next typegen && tsc --noEmit --runExternalCode"
}
}Database client
Create one client for the app, in a module that only server code imports:
import "server-only";
import postgres from "postgres";
// one pool across the reloads of next dev
const globalForDb = globalThis as typeof globalThis & { db?: postgres.Sql };
export const db = (globalForDb.db ??= postgres(process.env.DATABASE_URL));Next.js handles the server-only import itself, so the package needs no install. A client component that imports this module fails the build.
Server code
In next dev, an edit to a .sql file takes effect on the next request.
Server components
Await a query in an async server component:
import { } from "@/lib/db";
import from "./list_posts.sql";
export default async function () {
const posts = await .(); return (
<>
{.(() => (
< ={.}>
{.} by {.}
</>
))}
</>
);
}select p.id, p.title, u.name as author
from posts p
join users u on u.id = p.user_id
order by p.idWith Cache Components, which create-next-app 16.4 turns on, a component that queries at request time goes inside <Suspense>, or is marked "use cache".
Route handlers
Return a query's result from a route handler:
import { } from "@/lib/db";
import from "./get_user.sql";
type = { : <{ : string }> };
export async function (: Request, { }: ) {
const user = await .(, { : ((await ).) }); if (!) return .({ : "not found" }, { : 404 });
return .();
}select id, name, email
from users
where id = :idA 64-bit integer comes back as a bigint, which Response.json() refuses, so convert it before you return it.
Server actions
Run a write in a server action:
import { } from "next/cache";
import { } from "@/lib/db";
import from "./create_post.sql";
async function (: FormData) {
"use server";
await .(, {
: (.("user_id")),
: (.("title")),
});
("/");
}
export default function () {
return (
< ={}>
< ="user_id" ="number" ={1} />
< ="title" />
<>Post</>
</>
);
}insert into posts (user_id, title)
values (:user_id, :title)
returning idClient components
A client component can't import a query. Run it in a server component, and pass the rows as props:
import { } from "@/lib/db";
import from "./list_posts.sql";
import { } from "./post-list";
export default async function () {
return < ={await .()} />;
}"use client";
import type from "./list_posts.sql";
type = <<typeof .>>;
export function ({ }: { : }) {
return (
<>
{.(() => (
< ={.}>{.}</>
))}
</>
);
}- A type-only import, as in
post-list.tsx, leaves nothing for the bundler to load. - A client component that imports a query fails
next build, and its page innext dev. Turbopack reports an "Unknown module type", and webpack that the file needs "an appropriate loader". - The type check doesn't catch it, since types don't know which side of the boundary a module runs on.
The edge runtime
On the edge runtime, which has no TCP sockets, use a driver that connects over HTTP or WebSockets, such as Neon's:
import { } from "@neondatabase/serverless";
import from "./get_user.sql";
export const = "edge";
const = (..);
export async function (: Request) {
const = (new (.)..("id"));
return .(await .(, { }));
}Next.js 16.4 marks the edge runtime as deprecated, and refuses it with Cache Components on.
Building
The build runs Reylo's type check after the compile, and a type error in a query or its caller stops it:
$ next build
✓ Compiled successfully in 1760ms
Running next.config.js provided runAfterProductionCompile ...
app/page.tsx(10,33): error TS2551: Property 'authr' does not exist on type '{ id: number; title: string; author: string; }'. Did you mean 'author'?
⨯ Failed to run runAfterProductionCompile: Failed to type check (tsc --runExternalCode).- Next.js's own check runs without
--runExternalCode, sowithReyloturns it off and runs Reylo's instead. The build still prints "Skipping validation of types" for Next.js's check. - Setting
typescript.ignoreBuildErrorsin your config turns Reylo's check off too. - The build needs your dev database, as the type check does. In CI, start it and apply your migrations first (Deployment / CI). A host that builds before it migrates, such as Vercel, can build against a database of its own.