Jekyll2026-03-16T02:18:13+00:00https://rhymion.github.io/feed.xmlRhymion LabsBuilding generative structures that maximize potential.Dark Mode And Hydration In Nextjs With Mui2026-03-16T00:00:00+00:002026-03-16T00:00:00+00:00https://rhymion.github.io/blog/2026/03/16/dark-mode-and-hydration-in-nextjs-with-muiDark Mode and Hydration Errors in Next.js App Router with MUI

Adding dark mode to a Next.js App Router application sounds straightforward — enable a theme option and you’re done. In practice, combining Material UI (MUI) with Next.js App Router introduces a subtle set of pitfalls around React hydration errors that can be hard to diagnose and harder to fix if you encounter them in the wrong order.

This article walks through the problem, why it happens, and the correct setup sequence to get dark mode working without hydration errors.

Background: What Is Hydration?

Next.js renders pages on the server and sends the resulting HTML to the browser. React then runs on the client and “hydrates” that HTML — it attaches event handlers and takes over control of the DOM. For this to work, the HTML structure React produces on the client must exactly match what the server sent.

When there’s a mismatch, React throws a hydration error:

“Hydration failed because the server rendered HTML didn’t match the client.”

These errors are often invisible during development but appear in production, or they can cause a blank page or a broken layout. See the React docs on hydration for a deeper explanation.

Background: How MUI Styles Work

MUI uses Emotion as its CSS-in-JS engine. Emotion generates <style> tags at runtime. In a server-rendered app, Emotion also generates those styles on the server and embeds them in the initial HTML so the page doesn’t flash unstyled content.

The order and position of those <style> tags must be identical between the server and the client. If they differ, React’s hydration check fails.

The Trap: Adding ThemeProvider Before AppRouterCacheProvider

A common mistake is to install MUI and immediately add a ThemeProvider:

// app/layout.tsx — DO NOT do this yet
import { ThemeProvider } from '@mui/material/styles';
import CssBaseline from '@mui/material/CssBaseline';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <ThemeProvider theme={theme}>
          <CssBaseline />
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}

Without the correct Emotion cache setup, adding ThemeProvider triggers a cascade of SSR style injection that produces hydration errors. You may see:

  • Hydration failed because the server rendered HTML didn't match the client
  • Cannot read properties of null (reading 'parentNode')

What makes this tricky is that without ThemeProvider, Emotion generates very little CSS during SSR, so the bug stays hidden. As soon as ThemeProvider is added, Emotion generates substantial CSS server-side and injects <style> tags in a position that conflicts with React’s hydration.

Step 1: Install and Configure AppRouterCacheProvider

AppRouterCacheProvider is MUI’s official adapter for the Next.js App Router. It ensures Emotion’s style cache is shared correctly across SSR and client hydration, so <style> tags are inserted in the same order and position on both sides.

Install the package:

npm install @mui/material-nextjs

Then wrap the root layout’s body content:

// app/layout.tsx
import { AppRouterCacheProvider } from '@mui/material-nextjs/v15-appRouter';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <AppRouterCacheProvider>
          {children}
        </AppRouterCacheProvider>
      </body>
    </html>
  );
}

This must be in place before you add ThemeProvider. If you add ThemeProvider first, you’ll encounter hydration errors that are difficult to trace back to the missing cache provider.

Step 2: Add ThemeProvider with Dark Mode

Once AppRouterCacheProvider is in place, you can safely add a ThemeProvider. Because ThemeProvider and CssBaseline are client components (they use React context), it’s cleanest to extract them into a dedicated Providers component:

// app/providers.tsx
'use client';

import { createTheme, ThemeProvider } from '@mui/material/styles';
import CssBaseline from '@mui/material/CssBaseline';

const theme = createTheme({
  colorSchemes: {
    dark: true,
  },
  cssVariables: {
    colorSchemeSelector: 'media',
  },
});

export default function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ThemeProvider theme={theme}>
      <CssBaseline enableColorScheme />
      {children}
    </ThemeProvider>
  );
}

Then use it in the layout:

// app/layout.tsx
import { AppRouterCacheProvider } from '@mui/material-nextjs/v15-appRouter';
import Providers from './providers';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <AppRouterCacheProvider>
          <Providers>
            {children}
          </Providers>
        </AppRouterCacheProvider>
      </body>
    </html>
  );
}

Why colorSchemeSelector: 'media'

MUI v6+ supports two approaches for activating dark mode:

Approach How it works SSR-safe?
'class' Adds a .dark class to <html> via a JS script Requires getInitColorSchemeScript, which is client-only
'media' Scopes CSS variables inside @media (prefers-color-scheme: dark) Yes — pure CSS, no script needed

The 'class' approach requires injecting getInitColorSchemeScript into the page before React hydrates. However, this API is client-only and cannot be called from a Next.js Server Component — attempting it throws a runtime error.

The 'media' approach uses a CSS media query to apply dark-mode CSS variables. Since the CSS is identical on server and client, there is no hydration mismatch. This is the right default for Next.js App Router.

/* What MUI generates under the hood with colorSchemeSelector: 'media' */
@media (prefers-color-scheme: dark) {
  :root {
    --mui-palette-background-default: #121212;
    --mui-palette-text-primary: #fff;
    /* ... */
  }
}

Dark mode activates automatically based on the OS/browser preference — no JavaScript is required at runtime.

Why CssBaseline enableColorScheme

<CssBaseline enableColorScheme />

CssBaseline resets browser default styles (similar to normalize.css). The enableColorScheme prop adds color-scheme: light dark to <body>, which tells the browser to adapt its native controls — scrollbars, form inputs, select dropdowns, date pickers — to the active color scheme. Without it, browser-native UI elements remain light even when MUI components are dark.

Hardcoded Colors: The Hidden Dark Mode Bug

MUI components adapt automatically once ThemeProvider is set up. The risk area is hardcoded color values in custom components, which bypass the theme entirely.

// Broken in dark mode — hardcoded light grey
<div style=>
  Some content
</div>

#f5f5f5 is near-white. On a dark background it creates a harsh light bar that looks broken.

Fix: use MUI’s CSS variables, which are updated automatically by the theme:

// Theme-aware — adapts to light and dark mode
<div style=>
  Some content
</div>

Common MUI CSS variables that adapt to both light and dark mode:

Variable Use case
var(--mui-palette-action-hover) Subtle tinted background (e.g. info bars)
var(--mui-palette-background-paper) Card / paper surface
var(--mui-palette-background-default) Page background
var(--mui-palette-text-primary) Primary text
var(--mui-palette-text-secondary) Muted / secondary text
var(--mui-palette-divider) Borders and dividers

Alternatively, use MUI’s sx prop or the useTheme() hook, which are always theme-aware:

import { useTheme } from '@mui/material/styles';

function MyComponent() {
  const theme = useTheme();
  return (
    <div style=>
      Some content
    </div>
  );
}

Other Common Hydration Errors

Locale-sensitive date formatting

Date.toLocaleString() and related methods produce different output depending on the locale configured in the runtime. The Node.js server may use a system locale that differs from the user’s browser locale, causing a mismatch.

// Potentially different output on server vs client
<span>{new Date(post.created_at).toLocaleString()}</span>

Two options:

Option A — Suppress the warning (when the client value is the correct one):

<span suppressHydrationWarning>
  {new Date(post.created_at).toLocaleString()}
</span>

suppressHydrationWarning tells React to accept the mismatch on that specific element and use the client-rendered value. Only use it where the mismatch is cosmetic and the client value is the correct one to show (e.g. the user’s local time format).

Option B — Format with a fixed locale (consistent on both sides):

<span>
  {new Date(post.created_at).toLocaleString('en-US', { timeZone: 'UTC' })}
</span>

Browser-only globals

Accessing window, navigator, localStorage, or document during render will throw on the server (where they don’t exist) or produce a mismatch:

// Crashes on server
const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches;

Move these reads inside a useEffect (which only runs on the client) or use a library like usehooks-ts that handles this safely.

Math.random() and Date.now() in rendered output

These produce different values on each call, so server and client will never match:

// Never do this in rendered output
<div id={`item-${Math.random()}`}>...</div>

Use a stable ID source instead, such as a database ID or the useId() hook.

Setup Summary (correct order)

Getting the order right is important — adding ThemeProvider before AppRouterCacheProvider triggers errors that are hard to trace.

  1. Install @mui/material-nextjs
  2. Add AppRouterCacheProvider to app/layout.tsx (wraps the body contents)
  3. Create a client Providers component with ThemeProvider + CssBaseline
  4. Use colorSchemeSelector: 'media' in the theme — no init script, SSR-safe
  5. Replace any hardcoded color values in custom components with MUI CSS variables

References

]]>Improving Next.js App Router Performance with a Remote Database2026-03-16T00:00:00+00:002026-03-16T00:00:00+00:00https://rhymion.github.io/blog/2026/03/16/nextjs-performance-remote-databaseImproving Next.js App Router Performance with a Remote Database

When your Next.js application connects to a database hosted in a distant region, latency becomes the dominant factor in page load time. A single DB round-trip might cost 500ms or more — and every sequential call stacks that cost visibly for the user. This article walks through four techniques that, together, make a significant difference in perceived and actual performance.

The Problem: Sequential Waits Add Up

A typical data page in a Next.js App Router application does something like this:

  1. Check who the current user is (auth lookup)
  2. Fetch the user’s permissions for this resource
  3. Fetch the actual data

If each of these is a separate DB call and each costs 500ms, the user waits 1.5 seconds before seeing anything. On top of that, the entire HTML response is held until all three complete — meaning the browser has nothing to render until everything is done.

The following techniques address this at three levels: what the browser renders first, which calls run in parallel, and how many calls happen at all.

Technique 1: Stream Content with Suspense

The idea

Next.js App Router supports streaming HTML responses. If you wrap an async server component in a <Suspense> boundary, Next.js sends the outer HTML shell to the browser immediately — without waiting for the data — then streams in the content when it’s ready.

The key is to split every data-fetching page into two parts:

  • A sync outer component that returns instantly (no awaits, no DB calls)
  • An async inner component that does the actual data fetching
// The outer component renders immediately — fast first byte
export default function ProductListPage() {
  return (
    <Suspense fallback={<LoadingPlaceholder />}>
      <ProductListContent />
    </Suspense>
  );
}

// The inner component streams in when data is ready
async function ProductListContent() {
  const products = await getProducts();
  return <ProductTable rows={products} />;
}

Without this split, the page component itself is async, which blocks the entire response. With it, the browser receives the page shell — including layout, navigation, and the loading placeholder — at near-zero latency. The content then streams in when the DB responds.

Pages with dynamic route parameters

For pages like /products/[id]/edit, the route params need to be awaited. The cleanest pattern is to await params in the outer component and pass the resolved values down:

export default async function ProductEditPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  return (
    <Suspense fallback={<LoadingPlaceholder />}>
      <ProductEditContent id={id} />
    </Suspense>
  );
}

Technique 2: Show Skeleton Screens While Loading

The idea

Streaming Suspense gives the browser something to work with immediately, but what does the user actually see while waiting? A blank area or a generic spinner is disorienting. A skeleton screen — a low-fidelity outline of the content to come — signals to the user exactly where the content will appear, making the wait feel shorter.

MUI’s <Skeleton> component makes this straightforward:

function TableSkeleton() {
  return (
    <Box sx=>
      <Skeleton variant="rectangular" height={52} sx= />
      {[...Array(5)].map((_, i) => (
        <Skeleton key={i} variant="rectangular" height={48} sx= />
      ))}
    </Box>
  );
}

The skeleton matches the shape of the real content: a header row followed by data rows. When the actual table streams in, there’s no layout shift — the skeleton was already occupying the right space.

The same approach works for form pages:

function FormSkeleton() {
  return (
    <Box sx=>
      <Skeleton variant="rectangular" width={200} height={36} sx= />
      {[...Array(4)].map((_, i) => (
        <Skeleton key={i} variant="rectangular" height={56} sx= />
      ))}
    </Box>
  );
}

Skeleton screens don’t reduce actual load time, but they meaningfully improve perceived performance — which is what users notice.

Technique 3: Fetch Data and Permissions in Parallel

The problem with sequential auth

A common pattern for protected pages looks like this:

// Three sequential round-trips
const userId = await getCurrentUserId();
const permissions = await getPermissions(userId, 'product');
const products = await getProducts();

The permissions call depends on userId, so it can’t start until the first call finishes. The data fetch is independent but happens last. On a remote DB, this stacks three round-trips end-to-end.

Rethinking the auth API

The fix starts by reconsidering what the auth/permissions API returns. If the function that resolves permissions also returns the userId it resolved, the caller can eliminate the separate getCurrentUserId() call — and use Promise.all to run permissions and data fetches concurrently:

// One round-trip for both
const [{ permissions, userId }, products] = await Promise.all([
  getPermissions('product'),   // now returns { permissions, userId } together
  getProducts(),
]);

For detail pages (where permissions may depend on the item’s creator or assignee), the item and base permissions can still be fetched in parallel. The item-level permission resolution happens afterward, once both are available:

const [item, { permissions: basePermissions, userId }] = await Promise.all([
  getProduct(id),
  getPermissions('product'),
]);

// Resolve item-specific permissions (creator/assignee rules) — no extra DB call
const finalPermissions = resolveItemPermissions(basePermissions, item, userId);

This pattern turns what was three sequential DB calls into effectively one parallel round-trip, saving two full DB latency cycles on every page load.

Keeping component interfaces simple

The internal permission object may carry rich context (general role, creator role, assignee role) for server-side resolution. Components don’t need this detail — they just need four booleans: can read, create, update, delete. Strip the rich object down before passing it to components:

// Server: resolve rich permissions
const finalPermissions = resolveItemPermissions(basePermissions, item, userId);

// Pass simplified flags to the component
return <ProductForm permissions={toSimpleFlags(finalPermissions)} />;

This keeps the server logic flexible while keeping component props clean.

Technique 4: Avoid Unnecessary Cache Invalidation

Even after optimizing what happens on the first load, extra DB calls can sneak in through cache invalidation logic. Two common sources:

Double-fetch from revalidatePath + redirect

In a Next.js Server Action, it’s tempting to both invalidate the cache and redirect after a successful save:

export async function saveProduct(data: FormData) {
  await upsertProduct(data);
  revalidatePath('/products');  // invalidate
  redirect('/products');        // navigate
}

The problem is that revalidatePath schedules a background re-render of /products, and redirect causes the client to navigate to /products — which also triggers a render. The result is two DB calls for the list page in rapid succession.

The fix: remove revalidatePath. The redirect() call in a Server Action already invalidates the router cache for the destination, so revalidatePath is redundant here:

export async function saveProduct(data: FormData) {
  await upsertProduct(data);
  redirect('/products');  // handles cache invalidation + navigation together
}

Extra fetch from router.refresh() in navigation handlers

A similar issue appears in client-side navigation. It’s common to call both router.push() and router.refresh() when a form’s back button is clicked:

// Before: causes extra fetches
const handleBack = () => {
  router.push('/products');
  router.refresh();  // triggers getProductDetail AND getProducts
};

The router.refresh() re-renders the current page before navigation completes, firing DB calls that are about to be discarded as the user leaves. Remove it:

// After: clean navigation, no extra fetches
const handleBack = () => {
  router.push('/products');
};

The destination page fetches its own fresh data when it mounts.

When revalidatePath is still needed

Some actions don’t redirect — they update the current page in place. Comment CRUD, status toggles, and similar in-place updates fall into this category. These still need revalidatePath because the client calls router.refresh() to pick up changes, and the server needs its cache invalidated for that refresh to return fresh data:

export async function addComment(productId: string, text: string) {
  await createComment({ productId, text });
  revalidatePath('/products');  // needed: no redirect, client will call router.refresh()
}

The rule: use revalidatePath when there is no redirect. Drop it when there is.

Results and Trade-offs

These four techniques work at different layers and complement each other:

Technique Latency saved Mechanism
Streaming Suspense Fast TTFB regardless of DB latency Shell rendered before DB responds
Skeleton screens Perceived wait reduced Visual placeholder during loading
Parallel data + permissions ~1–2× DB round-trips eliminated Promise.all instead of sequential awaits
Remove redundant invalidation 1–2 extra renders eliminated per navigation redirect instead of revalidatePath + redirect

The parallelism improvement (Technique 3) requires some thought about API design — specifically making auth functions return enough context to avoid a separate userId lookup. The cache invalidation improvements (Technique 4) are mostly a matter of understanding what revalidatePath and redirect each do and avoiding the overlap.

Streaming + skeletons are largely mechanical: split the page component, add a <Suspense> boundary, provide a meaningful fallback. These changes don’t require touching any business logic and can be applied incrementally.

Together, on an application with ~500ms DB round-trips, these changes can reduce the wait before something interactive appears from several seconds to near-zero (skeleton is immediate), and cut total DB calls on common navigation patterns by half.

]]>Internationalization (i18n) — Locale-Based Routing with Next.js2026-03-07T00:00:00+00:002026-03-07T00:00:00+00:00https://rhymion.github.io/blog/2026/03/07/i18n-locale-routingInternationalization (i18n) — Locale-Based Routing with Next.js

Overview

In many cases apps must support multiple locales. We can use next-intl v4 with locale-based URL routing in Next.js. Every page URL is prefixed by the locale (/en/booking, /ja/booking), which gives:

  • SEO — search engines index each locale at its own URL
  • CDN caching — responses are cacheable per locale without cookie-based variance
  • Shareable links — the locale is self-contained in the URL, not hidden in a cookie
  • Server-side rendering — the locale is known at request time without client-side detection

In our case, we try to support the locales en (English, default) and ja (Japanese).

File Structure

i18n/
  routing.ts          ← supported locales + default locale
  request.ts          ← server-side getRequestConfig (loads messages)
  navigation.ts       ← locale-aware Link, useRouter, usePathname, redirect

messages/
  en.json             ← English translation strings
  ja.json             ← Japanese translation strings

proxy.ts              ← Next.js middleware: locale routing + auth token check
app/
  layout.tsx          ← minimal root shell; reads locale via getLocale()
  [locale]/
    layout.tsx        ← locale layout: wraps NextIntlClientProvider + page shell
    @header/page.tsx  ← header with locale switcher (client component)
    @sidebar/page.tsx ← nav sidebar (client component)
    @footer/page.tsx  ← footer
    providers.tsx     ← SessionProvider + SidebarProvider
    login/page.tsx
    register/page.tsx
    [entity]/...      ← all generated entity pages
  api/                ← API routes (no locale prefix — unaffected by i18n)

Key Files Explained

i18n/routing.ts

Defines the supported locales and the default. Import this wherever the locale list is needed (e.g. the header locale switcher, generateStaticParams).

import { defineRouting } from 'next-intl/routing';

export const routing = defineRouting({
  locales: ['en', 'ja'],
  defaultLocale: 'en',
});

i18n/request.ts

Called by next-intl on every server request. Reads the locale from the URL (set by the middleware) and loads the matching message file.

import { getRequestConfig } from 'next-intl/server';
import { routing } from './routing';

export default getRequestConfig(async ({ requestLocale }) => {
  let locale = await requestLocale;
  if (!locale || !routing.locales.includes(locale as 'en' | 'ja')) {
    locale = routing.defaultLocale;
  }
  return {
    locale,
    messages: (await import(`../messages/${locale}.json`)).default,
  };
});

i18n/navigation.ts

Re-exports locale-aware navigation helpers created by next-intl. Always import Link, useRouter, usePathname, and redirect from here instead of next/link or next/navigation — the wrappers automatically prepend the current locale to every path.

import { createNavigation } from 'next-intl/navigation';
import { routing } from './routing';

export const { Link, redirect, usePathname, useRouter, getPathname } =
  createNavigation(routing);

proxy.ts (middleware)

The project uses proxy.ts as its middleware entry point. (While middleware.ts had been used, from Next.js 16 proxy is recommended instead). It chains two responsibilities:

  1. Locale routing — next-intl redirects bare paths (/booking → /en/booking) and sets the locale for the request
  2. Auth protection — non-public paths require a valid JWT; unauthenticated users are redirected to /{locale}/login
// proxy.ts (simplified)
const intlMiddleware = createIntlMiddleware(routing);
const PUBLIC_PATHS = ['/login', '/register'];

export async function proxy(req: NextRequest) {
  // determine path without locale prefix
  const isPublicPath = PUBLIC_PATHS.some(p => pathnameWithoutLocale === p);
  const intlResponse = intlMiddleware(req);   // handles locale redirect/rewrite

  if (isPublicPath) return intlResponse;

  const token = await getToken({ req, secret: process.env.AUTH_SECRET });
  if (!token) {
    url.pathname = `/${locale}/login`;
    return NextResponse.redirect(url);
  }
  return intlResponse;
}

export const config = {
  matcher: ['/((?!api|_next|_vercel|.*\\..*).*)'],
};

Do not create middleware.ts — the framework detects both files and throws an error.

Using Translations

In server components

import { getTranslations } from 'next-intl/server';

export default async function MyPage() {
  const t = await getTranslations('Nav');
  return <h1>{t('home')}</h1>;
}

In client components

"use client";
import { useTranslations } from 'next-intl';

export default function MyComponent() {
  const t = useTranslations('Header');
  return <button>{t('signOut')}</button>;
}

Note: useTranslations only works inside NextIntlClientProvider. The locale layout (app/[locale]/layout.tsx) wraps all pages in this provider, so any client component under [locale]/ can call useTranslations.

In app/[locale]/layout.tsx

The locale layout must call setRequestLocale (for static rendering support) and fetch messages before rendering:

import { NextIntlClientProvider } from 'next-intl';
import { getMessages, setRequestLocale } from 'next-intl/server';

export default async function LocaleLayout({ children, params }) {
  const { locale } = await params;
  setRequestLocale(locale);
  const messages = await getMessages();

  return (
    <NextIntlClientProvider messages={messages}>
      <Providers>...</Providers>
    </NextIntlClientProvider>
  );
}

Adding a New Locale

  1. Add the locale to i18n/routing.ts: 
    locales: ['en', 'ja', 'fr'],

  2. Create the message file messages/fr.json with all required keys (copy en.json as a starting template).

  3. Update the localeLabels map in app/[locale]/@header/page.tsx: 
    const localeLabels: Record<string, string> = {
  en: "EN",
  ja: "日本語",
  fr: "FR",
};
  4. Update i18n/request.ts — widen the type guard to include the new locale: 
    if (!locale || !routing.locales.includes(locale as 'en' | 'ja' | 'fr')) {

That’s all — next-intl handles the rest automatically.

Switching locale

From a client component, use useRouter().replace with the locale option:

const router = useRouter();     // from @/i18n/navigation
const pathname = usePathname(); // from @/i18n/navigation

router.replace(pathname, { locale: 'ja' });

The header already exposes this as labelled buttons (EN / 日本語).

Message File Structure

{
  "Header": {
    "signIn": "Sign In",
    "signOut": "Sign Out",
    "openMenu": "Open menu",
    "closeMenu": "Close menu"
  },
  "Nav": {
    "home": "Home",
    "dbTables": "DB Tables",
    ...
  },
  "Auth": {
    "signInTitle": "Sign in to your account",
    "registerTitle": "Create your account",
    ...
  }
}

Add new namespaces (top-level keys) as features grow. Keep key names camelCase and scoped to their UI context.

Testing

Cypress E2E

All cy.visit() calls use the /en/ prefix (the default locale):

cy.visit('/en/booking');
cy.visit('/en/booking/new');
cy.visit('/en/');

This is baked into the test templates (utils/scripts/templates-test.ts). Regenerating tests will produce the correct paths automatically.

Vitest unit tests

NextIntlClientProvider is also needed in (component) testing, when the target component uses translation. Unlike in components, if it is acceptable to hard-code locale in testing, code is slightly simpler.

import { render } from '@testing-library/react';
import { NextIntlClientProvider } from 'next-intl';
import messages from '@/messages/en.json';

export function renderWithIntl(ui: React.ReactElement) {
  return render(
    <NextIntlClientProvider locale="en" messages={messages}>
      {ui}
    </NextIntlClientProvider>
  );
}

We can now call the target component with renderWithIntl as wrapper. Of course we can also use mock instead, if i18n itself is not the target of testing.

Additional Resources

Tags: Next.js, i18n, Testing, E2E Testing, Cypress, TypeScript

]]>How to Use Prisma Adapters for Testing While Keeping Accelerate for Production2026-02-17T00:00:00+00:002026-02-17T00:00:00+00:00https://rhymion.github.io/blog/2026/02/17/prisma-adapter-testing-strategyHow to Use Prisma Adapters for Testing While Keeping Accelerate for Production
Published: February 17, 2026 Reading Time: 12 minutes Difficulty: Intermediate

Are you struggling to test your Next.js application locally while using Prisma Accelerate in production? You’re not alone. Many developers face the challenge of managing database connections across different environments when using Prisma’s powerful Accelerate extension.

In this comprehensive guide, you’ll learn how to set up a flexible database strategy that uses Prisma Accelerate for production while seamlessly switching to direct connections for local development and testing.

📚 What You’ll Learn

By the end of this tutorial, you will:

  • ✅ Understand why Prisma Accelerate creates challenges for local testing
  • ✅ Set up conditional database adapters for different environments
  • ✅ Configure your Next.js app to use Accelerate in production and direct connections for testing
  • ✅ Implement a complete e2e testing workflow with Docker
  • ✅ Optimize bundle size by dynamically importing adapters
  • ✅ Avoid common pitfalls when working with Prisma 7

Understanding the Problem: Why Accelerate Breaks Local Testing

What is Prisma Accelerate?

Prisma Accelerate is a cloud-based connection pooler and global cache for your database. It provides:

  • 🚀 Global edge caching for faster query responses
  • 🔄 Connection pooling to handle thousands of serverless connections
  • 📊 Built-in performance monitoring and analytics

The Testing Dilemma

When you install @prisma/extension-accelerate, it modifies PrismaClient’s TypeScript types to require the accelerateUrl parameter:

// ✅ Works in production with Accelerate
const prisma = new PrismaClient({
  accelerateUrl: process.env.PRISMA_DATABASE_URL, // prisma+postgres://...
}).$extends(withAccelerate());

But here’s the catch – the extension validates URLs at runtime and only accepts URLs starting with prisma:// or prisma+postgres://:

// ❌ Fails with local database!
const prisma = new PrismaClient({
  accelerateUrl: process.env.DATABASE_URL, // postgresql://localhost:5432/...
}).$extends(withAccelerate());

// Error: InvalidDatasourceError: the URL must start with prisma:// or prisma+postgres://

This creates a frustrating situation where you can’t easily test your application locally without:

  • Creating fake Accelerate URLs (hacky)
  • Paying for Accelerate connections during testing (wasteful)
  • Removing the extension entirely (losing production benefits)

💡 Expert Tip: This issue only affects projects using @prisma/extension-accelerate. If you’re not using Accelerate, you can safely use direct database connections everywhere.

The Solution: Conditional Adapter Strategy

The elegant solution is to use database adapters for local/test environments while keeping Accelerate for production. This gives you the best of both worlds.

How It Works

import { PrismaClient } from '@/app/generated/prisma/client';
import { withAccelerate } from '@prisma/extension-accelerate';

const createPrismaClient = async () => {
  if (process.env.PRISMA_DATABASE_URL) {
    // Production: Use Prisma Accelerate
    console.log('Using Accelerate URL for Prisma Client');
    const client = new PrismaClient({
      accelerateUrl: process.env.PRISMA_DATABASE_URL,
      log: process.env.NODE_ENV === 'development' ? ['query'] : [],
    }).$extends(withAccelerate());
    return client;
  } else {
    // Development/Testing: Use direct connection with adapter
    console.log('Using direct database connection for Prisma Client');
    const connectionString = process.env.DATABASE_URL;
    
    // Dynamic import to avoid bundling adapter in production
    const { PrismaPg } = await import('@prisma/adapter-pg');
    const adapter = new PrismaPg({ connectionString });
    const client = new PrismaClient({ adapter });
    return client;
  }
};

const prisma = await createPrismaClient();
export default prisma;

How the conditional logic works:

Environment PRISMA_DATABASE_URL Set? Connection Type Extension Used
Production ✅ Yes Accelerate withAccelerate()
Development ❌ No Direct (adapter) None
Testing ❌ No Direct (adapter) None

Step-by-Step Implementation Guide

Prerequisites

Before you begin, make sure you have:

  • Node.js 18+ installed
  • A Next.js project with Prisma configured
  • Prisma Accelerate set up (optional, for production)
  • Docker installed (for local testing database)

Step 1: Install the PostgreSQL Adapter

Install @prisma/adapter-pg as a development dependency:

npm install --save-dev @prisma/adapter-pg

⚠️ Important: Install as a dev dependency (--save-dev) to prevent bundling it in production builds.

Step 2: Set Up Environment Variables

Create separate environment files for different scenarios:

.env.local (Development with Production Database)

# Direct connection for Prisma migrations
DATABASE_URL="postgres://user:pass@db.prisma.io:5432/production_db"

# Accelerate URL for application runtime
PRISMA_DATABASE_URL="prisma+postgres://accelerate.prisma-data.net/?api_key=eyJhbG..."

# NextAuth configuration
AUTH_SECRET="your-production-secret-key"

.env.test (Local Testing)

# Local test database - NO PRISMA_DATABASE_URL here!
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/myapp_test"

# NextAuth configuration
AUTH_SECRET="test-secret-key-for-testing"
NODE_ENV="test"

💡 Pro Tip: The key is to omit PRISMA_DATABASE_URL in test environments. This triggers the adapter-based connection instead of Accelerate.

Step 3: Update Your Prisma Client Configuration

Create or update your lib/prisma.ts file:

import { PrismaClient } from '@/app/generated/prisma/client';
import { withAccelerate } from '@prisma/extension-accelerate';

const globalForPrisma = global as unknown as { prisma: PrismaClient };

const createPrismaClient = async () => {
  if (process.env.PRISMA_DATABASE_URL) {
    // Production path: Accelerate
    console.log('Using Accelerate URL for Prisma Client');
    const client = new PrismaClient({
      accelerateUrl: process.env.PRISMA_DATABASE_URL,
      log: process.env.NODE_ENV === 'development' ? ['query'] : [],
    }).$extends(withAccelerate());
    return client;
  } else {
    // Development/Test path: Direct connection
    console.log('Using direct database connection for Prisma Client');
    const connectionString = process.env.DATABASE_URL as string;
    
    // Dynamic import - only loaded when needed
    const { PrismaPg } = await import('@prisma/adapter-pg');
    const adapter = new PrismaPg({ connectionString });
    const client = new PrismaClient({ adapter });
    return client;
  }
};

const prisma = globalForPrisma.prisma || await createPrismaClient();

if (process.env.NODE_ENV !== "production") {
  globalForPrisma.prisma = prisma;
}

export default prisma;

Key implementation details:

  1. Async function - Required for dynamic imports
  2. Dynamic import - await import('@prisma/adapter-pg') loads the adapter only when needed
  3. Type assertion - Ensures TypeScript knows the connection string exists
  4. Singleton pattern - Prevents multiple Prisma instances in development

Step 4: Configure Prisma 7

If you’re using Prisma 7, the configuration structure has changed significantly.

prisma/schema.prisma

datasource db {
  provider = "postgresql"
  // ⚠️ No 'url' property in Prisma 7!
}

generator client {
  provider = "prisma-client"
  output   = "../app/generated/prisma"
}

model User {
  id       String  @id @default(cuid())
  email    String  @unique
  password String
  // ... other fields
}

prisma.config.ts

import "dotenv/config";
import { defineConfig } from "prisma/config";

export default defineConfig({
  schema: "prisma/schema.prisma",
  datasource: {
    url: process.env.DATABASE_URL, // Used for migrations
  },
});

📌 Remember: In Prisma 7, the url property moved from schema.prisma to prisma.config.ts. This affects migrations and introspection but not runtime connections.

Setting Up Your E2E Testing Environment

Now let’s set up a complete testing workflow using Docker and Cypress.

Step 5: Create Docker Compose Configuration

Create docker-compose.test.yml in your project root:

version: '3.8'

services:
  postgres-test:
    image: postgres:16-alpine
    container_name: myapp-test-db
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: myapp_test
    ports:
      - "5432:5432"
    volumes:
      - postgres-test-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  postgres-test-data:
    driver: local

Step 6: Add NPM Scripts

Update your package.json:

{
  "scripts": {
    "dev": "next dev",
    "dev:test": "dotenv -e .env.test -- next dev",
    "build": "next build",
    
    "docker:test:up": "docker-compose -f docker-compose.test.yml up -d",
    "docker:test:down": "docker-compose -f docker-compose.test.yml down",
    
    "db:reset:test": "dotenv -e .env.test -- prisma migrate reset --force",
    "db:seed:test": "dotenv -e .env.test -- tsx scripts/seed-test-db.ts",
    
    "cy:open": "cypress open",
    "cy:run": "cypress run --browser chromium",
    "cy:test": "start-server-and-test dev:test http://localhost:3000 cy:run"
  }
}

Required dependencies:

npm install --save-dev dotenv-cli start-server-and-test tsx

Step 7: Create Database Helper Functions

Create cypress/support/db-helpers.ts:

import { PrismaClient } from '@/app/generated/prisma/client';
import { TEST_CREDENTIALS, getTestPasswordHash } from './test-credentials';

// Simple direct connection - no Accelerate needed
const prisma = new PrismaClient();

export async function resetTestDatabase() {
  // Delete all records in reverse order (respect foreign keys)
  await prisma.post.deleteMany();
  await prisma.user.deleteMany();
}

export async function seedTestDatabase() {
  const hashedPassword = await getTestPasswordHash();
  
  const user = await prisma.user.create({
    data: {
      email: TEST_CREDENTIALS.email,
      name: TEST_CREDENTIALS.name,
      password: hashedPassword,
    },
  });

  return { user };
}

export { prisma };

💡 Note: Test helpers use new PrismaClient() without parameters because .env.test only has DATABASE_URL, triggering the adapter path automatically.

Step 8: Configure Cypress

Update cypress.config.ts:

import { defineConfig } from "cypress";

export default defineConfig({
  e2e: {
    baseUrl: "http://localhost:3000",
    setupNodeEvents(on, config) {
      require('dotenv').config({ path: '.env.test' });
      
      on('task', {
        async 'db:reset'() {
          const { resetTestDatabase } = require('./cypress/support/db-helpers');
          await resetTestDatabase();
          return null;
        },
        async 'db:seed'() {
          const { seedTestDatabase } = require('./cypress/support/db-helpers');
          await seedTestDatabase();
          return null;
        }
      });
      
      return config;
    },
    video: false,
  },
});

Your Complete Testing Workflow

Now you have everything set up. Here’s how to run tests:

Quick Start

# 1. Start the test database
npm run docker:test:up

# 2. Initialize the database schema
npm run db:reset:test

# 3. Run e2e tests (auto-starts dev server)
npm run cy:test

Manual Testing (with live dev server)

# Terminal 1: Start dev server with test database
npm run dev:test

# Terminal 2: Run Cypress interactively
npm run cy:open

Daily Development Workflow

# Development with production database
npm run dev

# Testing
npm run cy:test

# Stop test database when done
npm run docker:test:down

Benefits of This Approach

🎯 1. Environment Parity

Each environment uses the optimal connection strategy:

  • Production: Accelerate for global caching and pooling
  • Testing: Local database for speed and isolation

💰 2. Cost Efficiency

You don’t pay for Accelerate connections during development and testing.

⚡ 3. Performance

Local database connections are significantly faster than going through Accelerate’s cloud infrastructure for tests.

📦 4. Bundle Size Optimization

The adapter is dynamically imported, so it’s never included in your production bundle.

🔄 5. Easy Environment Switching

Change environments by simply setting or unsetting PRISMA_DATABASE_URL.

Common Pitfalls and How to Avoid Them

❌ Pitfall 1: Top-Level Adapter Import

Wrong:

import { PrismaPg } from '@prisma/adapter-pg'; // Always bundled!

Correct:

const { PrismaPg } = await import('@prisma/adapter-pg'); // Only when needed

❌ Pitfall 2: Setting PRISMA_DATABASE_URL in Test Environment

Wrong:

# .env.test
DATABASE_URL="postgresql://localhost:5432/test"
PRISMA_DATABASE_URL="postgresql://localhost:5432/test" # Don't do this!

Correct:

# .env.test
DATABASE_URL="postgresql://localhost:5432/test"
# Don't set PRISMA_DATABASE_URL - triggers adapter path

❌ Pitfall 3: Installing Adapter as Regular Dependency

Wrong:

npm install @prisma/adapter-pg

Correct:

npm install --save-dev @prisma/adapter-pg

Frequently Asked Questions

Can I use this with SQLite for testing?

Yes! Install @prisma/adapter-better-sqlite3 and modify the adapter import:

const { PrismaSqlite } = await import('@prisma/adapter-better-sqlite3');
const adapter = new PrismaSqlite({ url: 'file:./test.db' });

Will this work with Prisma 6?

The adapter strategy works with Prisma 6, but the prisma.config.ts file is Prisma 7+ only. For Prisma 6, keep url = env("DATABASE_URL") in your schema.prisma.

Do I need Docker for testing?

No, but it’s recommended. You can use any PostgreSQL instance – Docker just makes it easier to manage isolated test databases.

Can I use this with other ORMs?

This strategy is Prisma-specific, but the concept of conditional database connections applies to any ORM.

What about CI/CD pipelines?

In CI, set only DATABASE_URL (pointing to a test database) and omit PRISMA_DATABASE_URL. The adapter path will be used automatically.

Conclusion

The adapter strategy provides a clean, maintainable solution for managing database connections across environments. By conditionally using Prisma Accelerate in production and direct connections for testing, you get:

✅ Fast, isolated local testing
✅ Production-grade performance with Accelerate
✅ Optimized bundle sizes
✅ Simple environment management
✅ Lower costs

Next Steps

  1. Implement the adapter strategy in your Next.js project
  2. Set up Docker for your test database
  3. Configure Cypress with database helpers
  4. Write comprehensive e2e tests using your isolated test environment

Ready to optimize your testing workflow? Start by installing the adapter and setting up your environment variables today!

Additional Resources

Did this guide help you? Share your testing setup in the comments below or reach out if you have questions!

Tags: Prisma, Next.js, Testing, E2E Testing, Cypress, Docker, PostgreSQL, TypeScript

]]>Welcome2026-02-17T00:00:00+00:002026-02-17T00:00:00+00:00https://rhymion.github.io/blog/2026/02/17/welcomeThis is the first post on the Rhymion Labs blog.

I’ll share notes on building generative systems, structured reasoning, and scalable architectures.

]]>