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.

ConfigwithReylo from reylo/next, around your Next.js config
BundlersTurbopack, and webpack with --webpack
Queries run inServer components, route handlers and server actions
Edge runtimeA driver that connects over HTTP or WebSockets, such as Neon's
Examplenextjs, 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:

next.config.ts
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:

tsconfig.json
{
  "compilerOptions": { /* ... */ },
  "contentMappers": [{ "package": "reylo" }] 
}

To type-check without building, run next typegen first, which writes the route types:

package.json
{
  "scripts": {
    "typecheck": "next typegen && tsc --noEmit --runExternalCode"
  }
}

Database client

Create one client for the app, in a module that only server code imports:

lib/db.ts
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 .();
const posts: {
    id: number;
    title: string;
    author: string;
}[]
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.id

With 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 ).) });
const user: {
    id: number;
    name: string;
    email: string | null;
} | null
if (!) return .({ : "not found" }, { : 404 }); return .(); }
select id, name, email
from users
where id = :id

A 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 id

Client 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 in next 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:

Terminal
$ 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, so withReylo turns it off and runs Reylo's instead. The build still prints "Skipping validation of types" for Next.js's check.
  • Setting typescript.ignoreBuildErrors in 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.
Released under the MIT License. Copyright © 2026 Colin McDonnell.

On this page