Fixing IndexedDB Initialization Errors with TanStack Router + Effect + Pglite

Table of Contents

• Overview
• Background
  • The Tech Stack
  • The Cause
• The Solution
  • Here is how
    • 1. Remove initialization from the root route
    • 2. Wrap Pglite in TanStack Router’s ClientOnly
    • 3. Use the provider in a client-rendered route
• Conclusion

Overview

This covers a migration from fp-ts to Effect, where the app needed local-first database migrations using Pglite. Pglite can run against IndexedDB, an in-memory store, or the filesystem, but the IndexedDB backend only exists in a browser: it fails silently, or not so silently, the moment SSR tries to touch it.

Combining TanStack Router and Pglite in a server-rendered React app surfaces exactly that problem: the server-side render path tries to initialize IndexedDB and throws:

1
TypeError: Cannot read properties of null (reading 'open')
2
    at Object.getDB (...)
3
    ...

Calling into pglite before the client has mounted causes this. Below is the cause and the fix.

Background

The Tech Stack

• Effect: improves on fp-ts’s concepts for side effects, concurrency, and error handling.
• TanStack Router: a router for React with optional server-side rendering (SSR).
• Pglite: a client-side Postgres build that can persist to IndexedDB.
• Local-first migrations: following approaches like this guide, migrations run in the browser against the local database.

The Cause

Because TanStack Router supports SSR, the root component’s code executes on the server too. That code called into Pglite’s initialization, which depends on IndexedDB, and there is no window or IndexedDB in a Node SSR process. pglite expects to call open() on a real db instance; on the server that instance is null, so the call throws.

The Solution

TL;DR: keep all Pglite and IndexedDB code inside a client-only boundary.

Here is how

1. Remove initialization from the root route

Per TanStack Router’s SSR guide, any code in your root route runs on both server and client during SSR. Keep Pglite initialization out of it entirely.

2. Wrap Pglite in TanStack Router’s ClientOnly

Older versions of this pattern hand-rolled an isMounted state and a useEffect to defer rendering until the client mounted. TanStack Router now ships a ClientOnly component (and a useHydrated hook) that does exactly this, so there is no need to write it yourself:

1
import { useEffect, useState } from "react";
2
import { ClientOnly } from "@tanstack/react-router";
3
import { PGliteProvider } from "@electric-sql/pglite-react";
4
import { PgliteDrizzleContext } from "@/hooks/use-pglite-drizzle";
5
import { RuntimeClient } from "@/db/runtime-client";
6
import { Effect, DateTime } from "effect";
7
import { Pglite } from "@/db/services/pglite";
8
import { Migrations } from "@/db/services/migrations";
9
import { ReadApi } from "@/db/services/read-api";
10
import { SeedApi } from "@/db/services/seed-api";
11
import { WriteApi } from "@/db/services/write-api";
12

13
function PgliteBoundary({ children }: { children: React.ReactNode }) {
14
  const [client, setClient] = useState<any>(null);
15
  const [orm, setOrm] = useState<any>(null);
16

17
  useEffect(() => {
18
    async function initPglite() {
19
      // Initialize pglite on the client
20
      const pgliteInstance = RuntimeClient.runPromise(
21
        Effect.gen(function* () {
22
          const pglite = yield* Pglite;
23
          return pglite;
24
        })
25
      );
26

27
      // Run migrations on the client side
28
      RuntimeClient.runPromiseExit(
29
        Effect.gen(function* () {
30
          console.log("Migrating database...");
31
          const migrations = yield* Migrations;
32
          const readApi = yield* ReadApi;
33
          const writeApi = yield* WriteApi;
34
          const seedApi = yield* SeedApi;
35

36
          const latestMigration = migrations.length;
37
          console.log("Latest migration:", latestMigration);
38

39
          const { version } = yield* readApi.getSystem.pipe(
40
            Effect.catchTags({
41
              PgliteError: () => Effect.succeed({ version: 0 }), // No db yet
42
            })
43
          );
44

45
          console.log("Current version:", version);
46

47
          // Apply all unrun migrations
48
          yield* Effect.all(migrations.slice(version));
49

50
          // If no system record, create one and seed data
51
          if (version === 0) {
52
            yield* writeApi.createSystem;
53
            yield* seedApi.seedTodos;
54
          }
55

56
          // Update system version
57
          yield* writeApi.updateSystemVersion(latestMigration);
58
          yield* Effect.log(
59
            version === latestMigration
60
              ? "Database up to date"
61
              : `Migrations done (from ${version} to ${latestMigration})`
62
          );
63

64
          return yield* DateTime.now;
65
        }).pipe(Effect.tapErrorCause(Effect.logError))
66
      );
67

68
      setClient((await pgliteInstance).client);
69
      setOrm((await pgliteInstance).orm);
70
    }
71
    initPglite();
72
  }, []);
73

74
  if (!client) {
75
    return null;
76
  }
77

78
  return (
79
    <PGliteProvider db={client}>
80
      <PgliteDrizzleContext.Provider value={orm}>
81
        {children}
82
      </PgliteDrizzleContext.Provider>
83
    </PGliteProvider>
84
  );
85
}
86

87
export function ClientOnlyPgliteProvider({ children }: { children: React.ReactNode }) {
88
  return (
89
    <ClientOnly fallback={null}>
90
      <PgliteBoundary>{children}</PgliteBoundary>
91
    </ClientOnly>
92
  );
93
}

ClientOnly guarantees the wrapped tree never runs during SSR, which removes an entire class of “works locally, breaks on the server” bugs. The inner useEffect still guards the async Pglite setup itself, since mounting on the client and having an initialized database are two different moments.

3. Use the provider in a client-rendered route

1
// In a new route or existing route where you need the client DB
2
import { ClientOnlyPgliteProvider } from "@/context/ClientOnlyPgliteProvider";
3
import { createFileRoute } from "@tanstack/react-router";
4
import { IndexComponent } from "./IndexComponent"; // example component
5

6
export const Route = createFileRoute("/test_indexdb_page/")({
7
  component: RootDocument,
8
});
9

10
function RootDocument() {
11
  return (
12
    <div className="flex flex-col items-center justify-center min-h-screen">
13
      <ClientOnlyPgliteProvider>
14
        <IndexComponent />
15
      </ClientOnlyPgliteProvider>
16
    </div>
17
  );
18
}

With this in place, SSR never attempts to open IndexedDB, so the null database instance error goes away. All database logic, migrations included, runs only in the browser after hydration.

Conclusion

Switching from fp-ts to Effect gives a cleaner, more structured way to handle side effects and concurrency. But any client-only library that depends on IndexedDB, Pglite included, has to be isolated from the SSR code path. TanStack Router’s ClientOnly component makes that isolation a one-line wrapper instead of hand-rolled mount-state tracking.

Key takeaways:

1. Keep client-specific libraries out of the server render cycle.
2. Use ClientOnly (or useHydrated) to defer rendering until after hydration, instead of a manual isMounted state.
3. Centralize client-only logic in a dedicated provider to keep the rest of the app clean.

If you are taking this into production, the next steps below cover auth, data and observability, and the newsletter is where the Astro SaaS boilerplate ships first.