DEV Community: VerdantStack

SvelteKit environment variables: the destructuring build error, and why static private bakes in secrets

VerdantStack — Sun, 27 Sep 2026 10:00:26 +0000

SvelteKit cannot destructure $env/dynamic/private. Here is the fix.

There is a line of code that a lot of SvelteKit developers write once, get an error for, and then never think about again:

import { DATABASE_URL } from '$env/dynamic/private';

That is a build error. $env/dynamic/* does not have named exports, because SvelteKit cannot know at compile time what variables will exist in your runtime environment. The correct form is:

import { env } from '$env/dynamic/private';

const db = new Database(env.DATABASE_URL);

Getting that error is the easy part — it stops your build. The dangerous part is the mistake that does not stop your build, and I want to spend most of this post on it.

SvelteKit gives you four modules, on two axes

The names are more informative than they look. There are two independent questions:

Question	Values
Who can read it?	`private` (server only) · `public` (server and client)
When is it resolved?	`static` (at build) · `dynamic` (at request time)

That cross product is your four modules:

$env/static/private
$env/dynamic/private
$env/static/public
$env/dynamic/public

public is not a suggestion — it is a prefix rule. Only variables named PUBLIC_* are exposed to the client at all, and anything you put there is shipped to the browser in the JS bundle. If your starter is genuinely server-side, the right answer may be that you have zero PUBLIC_ variables, and that is a fine design.

static and dynamic differ in more than timing

Most posts stop at "static is faster". The two differences that actually bite:

Failure mode. With static, a missing variable fails your build. With dynamic, a missing variable fails at runtime — the deploy succeeds, the health check passes, and the first request that touches that code path 500s. Dynamic moves your failure from CI into production.

Inlining. static is resolved at build time: Vite replaces the import with a literal string, which is what makes dead-code elimination possible. dynamic is a runtime lookup against the environment.

The mistake that does not fail: rotating a secret that is baked in

Here is the scenario, and it is common on platforms that promote one-click deploys.

You import your signing secret from $env/static/private because the docs said static is faster, and it is:

import { SIGNING_SECRET } from '$env/static/private';

You deploy. Later you rotate that secret in your platform's dashboard. The dashboard confirms the change. You watch for a deploy.

Nothing happens, because nothing needs to happen. The value was inlined into the JavaScript during the build that already ran. The new value sits in your platform's environment, unread. Your running artifact still contains the old secret, and it will keep containing it until you rebuild and redeploy.

The uncomfortable part is that this looks like success. No error, no failed request, no alert. The dashboard says rotated. The artifact says otherwise.

If a value is a secret that rotates, it must be dynamic. static is for things that are constant for the lifetime of a given build — an internal service URL, a feature flag baked at build time, a non-sensitive tuning constant. A rotating secret is not one of those.

This is the same class of bug as hardcoding a credential into a committed config file, just spread across a deploy pipeline where nobody reads it.

process.env on Cloudflare: most posts are out of date

If you have read that process.env does not exist on Cloudflare Workers and stopped there, that guidance has aged. The current picture:

Workers run in a V8 isolate, not Node, so process.env does not exist natively.
You can have it by enabling the nodejs_compat compatibility flag.
For projects with a compatibility date on or after 2025-04-01, Cloudflare automatically populates process.env with your environment variables and secrets when that flag is on.

So "process.env does not work on Cloudflare" was true, then became conditional, and is now mostly false for new projects. What you should actually do is not reason about process.env at all: adapter-cloudflare maps the environment for you through the $env modules, so going through $env is portable across Node, Cloudflare, and anything else, and reading process.env directly is the thing that will surprise you later when you move hosts.

Prerendering reads the build environment, not yours

If you access env.SOMETHING at the top level of a module, it gets evaluated during prerendering too — when the runtime environment may not have your production secrets yet, because at that moment the "environment" is the build machine.

Guard it:

import { env } from '$env/dynamic/private';
import { building } from '$app/environment';

const apiUrl = building ? 'http://localhost:3000' : env.API_URL;

The general rule: if a value must exist at request time, do not read it at module top level.

The decision table I actually follow

If the value is…	Use
A secret that rotates or can be revoked	`dynamic/private`
Needed to survive a platform change without a rebuild	`dynamic/private`
Missing and you want CI to catch it	`static/private`
Constant for the lifetime of the build	`static/private`
Needed in browser code	`static/public`, `PUBLIC_` prefix, and accept it ships

The default for anything secret-shaped is dynamic/private. The cost is a runtime lookup; the cost of getting it wrong is a secret you believe you rotated and did not.

Make it testable by making it injectable

The practical benefit of routing every value through env is that dependency injection becomes free. Your modules take what they need as an argument, the test passes a literal object, and no test ever depends on a real environment:

export function createRateLimiter(env: { RATE_LIMIT_MAX: string }) {
  return new SlidingWindowLimiter(Number(env.RATE_LIMIT_MAX));
}

This is the same discipline we apply across our 874-test suite over three SvelteKit starters: the value is a parameter, not an ambient global. Ambient globals are the reason a test suite needs a fake environment, and a fake environment is how configuration bugs hide until production.

Where to read more

The other posts in this series cover the parts that break in production rather than the parts that work in a tutorial:

Boot-time migrations in SvelteKit: safe at one instance, a race at two — the replica race, and why two instances change the answer
Deploying SvelteKit to Cloudflare Pages with a real database — what actually works on the platform above
Drizzle ORM migrations: schema-first vs code-first — the migration strategy, before the boot-time question comes up

Boot-time migrations in SvelteKit: safe at one instance, a race at two

VerdantStack — Sun, 27 Sep 2026 08:42:30 +0000

Auto-migrating on boot is safe at one instance and a race at two. Here is the fix.

There is one line in a lot of SvelteKit starter kits that looks like a kindness:

// src/lib/server/db/index.ts
await migrate(db, { migrationsFolder: MIGRATIONS_DIR });

It sits in the connection helper, so migrations apply on every boot. No separate deploy step, no forgotten migration, no "works on my machine" schema drift. For a local dev server, a single-instance app, or a preview deploy, this is genuinely the right default.

Then you scale to two replicas, and it quietly stops being a kindness.

The mechanism

Nothing about migrate() is wrong. The problem is how many callers there are.

Each instance calls the migrator independently, and each one independently decides which migrations are still pending. There is no lock spanning that decision and the write that follows it. So with N replicas booting at once you get N processes asking "is 0003_add_seats applied?" and N processes potentially answering "no" at the same moment.

The concrete version, from a real connection helper:

const MIGRATIONS_DIR = path.resolve(process.cwd(), 'drizzle');

export async function openDb(
  url: string,
  opts: { schema?: string; max?: number } = {},
): Promise<{ db: Db; client: postgres.Sql }> {
  const client = postgres(url, { prepare: false, max: opts.max });
  if (opts.schema) {
    await client.unsafe(`CREATE SCHEMA IF NOT EXISTS "${opts.schema}"`);
    await client.unsafe(`SET search_path TO "${opts.schema}"`);
  }
  const db = drizzle(client, { schema });
  await migrate(db, { migrationsFolder: MIGRATIONS_DIR });   // ← every boot, every replica
  return { db, client };
}

Two things in that snippet are load-bearing. prepare: false is required because the Drizzle Postgres migrator uses execution semantics the prepared-statement cache cannot carry. And MIGRATIONS_DIR resolves against process.cwd(), so the migrations have to be deployed alongside the code — which means every replica is carrying the same set of migrations and the same set of pending work.

What the failure actually looks like

The friendly version of this bug is that it usually does fail loudly. The two signatures you will see:

1. column already exists. Two instances both decide 0003 is pending. One applies it. The other gets there a moment later and trips over DDL that is now redundant.

2. A partially applied migration. This is the one worth actually planning for. A migration that contains several statements is not atomic as a unit. If replica A applies ALTER TABLE ... ADD COLUMN seats integer and dies — killed by a rolling deploy, an OOM, a pod eviction — while replica B is mid-flight, the migration table and the schema can disagree. You are now debugging a schema whose recorded state is a fiction.

The timing window is narrow, which is why this survives so long. It usually surfaces on the deploy that first adds a replica, or the one that first scales with autoscaling, and
never again until the next schema change.

The fix is to move the writer out of the request path

Stop letting replicas write. Run migrations as an explicit, single-writer step before the new version serves traffic, and let the boot-time call be a no-op.

// package.json
{
  "scripts": {
    "db:generate": "drizzle-kit generate",     // schema.ts -> SQL in drizzle/
    "db:migrate": "tsx scripts/migrate.ts"     // the explicit, ordered step
  }
}

// scripts/migrate.ts
import 'dotenv/config';
import postgres from 'postgres';
import { drizzle } from 'drizzle-orm/postgres-js';
import { migrate } from 'drizzle-orm/postgres-js/migrator';
import * as schema from '../src/lib/server/db/schema';

const url = process.env.DATABASE_URL;
if (!url) throw new Error('DATABASE_URL is not set; see .env.example');

const client = postgres(url, { prepare: false });
try {
  const db = drizzle(client, { schema });
  await migrate(db, { migrationsFolder: './drizzle' });
  console.log('Migrations applied to', new URL(url).host);
} finally {
  await client.end();
}

Then the deployment guidance is a table, not a paragraph:

Deployment	What to do
Local dev, single instance, preview	Nothing. Boot-time migration is enough.
Multiple replicas / autoscaling	Run `npm run db:migrate` as a pre-deploy step — the only writer — and treat boot-time migration as a no-op.

Why keep both mechanisms

The instinct after reading this is to delete the boot-time call. Don't. The two mechanisms are doing different jobs:

The explicit step is the event. It runs once, in order, where you can watch it. A migration becomes a reviewed step in a deploy log rather than something you find out about from an exception three minutes after a rolling deploy started.
The boot-time call is the guarantee. It means no instance can ever serve a request against an unmigrated schema, even if a deploy skipped the step, a preview pointed at the production database, or someone restored from a backup into a half-migrated state.

Once npm run db:migrate is the only writer, the boot-time migrate() is doing no work — it finds nothing pending and returns. You are not trading correctness for convenience. You are separating the event from the guarantee so that neither has to do both badly.

The one thing this does not solve on its own: migrate() is still not a distributed lock. If someone adds a second pre-deploy step that also migrates, or runs the script from two deployments concurrently, you have the same race with extra steps. Keep it to exactly one
writer.

The checklist

Is there a command that applies migrations without starting the app? If not, write one.
Does it run before the new version is serving, as its own step?
Is exactly one thing running it? Not the app, not a cron, not a second deploy job.
Does the boot-time migrator stay, as the guarantee rather than the writer?
Is MIGRATIONS_DIR actually present in your deployed artifact? process.cwd()-relative paths break silently on some platforms.

On that last point: if your adapter bundles to a directory where drizzle/ was tree-shaken away, the boot-time migrator can throw on a missing folder — and it will look exactly like a database outage, because it happens on the first request that opens a connection.

One more thing worth knowing

If you are deploying to Cloudflare Workers/Pages with D1 rather than Postgres, the whole conversation changes: D1 is an HTTP API, so you are not managing a long-lived pooled connection at all, and the "every replica runs the migrator" problem does not exist in the same form. The SQLite-on-Workers and Postgres-on-a-server approaches trade this failure mode for a different one — local disk semantics that a single-region isolate cannot promise.

Pick based on which failure you would rather debug. The mistake is not choosing — it is shipping the boot-time migrator without having decided who the writer is.

Source of the specifics: this is the pattern from
SvelteKit + Postgres Starter
(v0.1.7), where the concurrency limit is documented in the function's own JSDoc and in
docs/deployment.md §3, so the constraint travels with the code instead of living in a wiki
page nobody reads. 262 tests run against a real Postgres test database, not mocks.

Drizzle ORM migrations in SvelteKit: schema-first vs code-first and what actually works in production

VerdantStack — Sun, 27 Sep 2026 05:20:39 +0000

Drizzle ORM gives you two migration approaches, and the docs don't clearly tell you when each one is the right call. I've been running schema-first Drizzle migrations in production across two of my three SvelteKit starter kits — one on SQLite/D1, one on vendor-neutral Postgres — and I've landed on a decision rule that stopped burning me. The third kit (Supabase) doesn't use Drizzle at all, and the contrast turned out to be instructive. Here it is, plus the code I actually use.

The two approaches

Code-first with generated migrations (drizzle-kit generate + drizzle-kit migrate):

# Edit src/lib/server/db/schema.ts, then:
npx drizzle-kit generate   # writes a versioned .sql file + journal metadata
npx drizzle-kit migrate    # applies pending migrations to the database

generate takes a snapshot of your schema, diffs it against the last one Drizzle recorded, and writes a plain SQL file you can read, review, and commit. migrate replays the pending files in order and records what ran.

Push (drizzle-kit push):

npx drizzle-kit push

push diffs your schema directly against a live database and applies whatever it takes to make them match — no migration files, no history.

Why push is fine in development but not in production

Push is great during prototyping: edit schema.ts, run push, the database matches, done. Three things make it the wrong tool once other people (or real data) depend on that database:

No audit trail. There's no record of what changed or when. When something breaks at 3 AM, you can't point at "the last migration that ran" — there isn't one.
Destructive changes are silent. push will happily drop columns, rename tables, and delete indexes that aren't in your schema anymore. In development that's fine; you'd recreate the database anyway. In production, that deletes real data without a review step.
No escape hatch. Generated migrations are plain SQL — you can read them, edit them, and add hand-written statements before or after the generated ones. If a push breaks something, your only tool is writing manual SQL from scratch.

Schema-first in production

The config is small:

// drizzle.config.ts
export default {
  schema: './src/lib/server/db/schema.ts',
  out: './drizzle',
  dialect: 'postgresql',          // 'sqlite' for the D1 kit
  dbCredentials: {
    // drizzle-kit loads .env; the fallback keeps `docker compose up` working with no setup
    url: process.env.DATABASE_URL || 'postgres://user:pass@localhost:5433/db',
  },
} satisfies import('drizzle-kit').Config;

And the workflow never varies:

# 1. Edit schema.ts
# 2. Generate the migration SQL
npx drizzle-kit generate
# 3. Review the generated SQL — always read it (this is where typos get caught)
# 4. Apply it (or via your platform's migration tool — see D1 below)
npx drizzle-kit migrate

The key insight: generated migrations are the escape hatch that push doesn't give you. Need a backfill, a partial index, or a data fix that doesn't belong in schema.ts? Open the generated file, add it, apply it. The migration history becomes the source of truth for how the database evolved.

The auto-migrate-at-boot pattern

For apps where you control the deployment, you can run migrations when the database connection is created instead of relying on a separate CI step alone. This is where my Postgres kit does it — inside createDb(), not in hooks.server.ts:

// src/lib/server/db/index.ts
import { migrate } from 'drizzle-orm/postgres-js/migrator';

export async function createDb(url: string) {
  const client = postgres(url);
  const db = drizzle(client, { schema });
  await migrate(db, { migrationsFolder: MIGRATIONS_DIR });  // <-- runs at boot
  return db;
}

It ships alongside an explicit script, and my deploy docs still list that script as a step:

npm run db:migrate   # tsx scripts/migrate.ts

Both is the point, not a contradiction. The explicit step means a deploy is a reviewed, ordered event you can watch. The boot-time call is a safety net: it guarantees no instance ever serves traffic against an unmigrated schema, which matters most for a preview deploy or a replica that came up unexpectedly.

Where the safety net stops being safe: concurrent deploys against one database. Two instances booting at the same time can both decide a migration is pending, and you get column already exists — or worse, a partially applied migration. If you run multiple replicas, keep the explicit pre-deploy step as the only writer and treat boot-migration as a no-op. Putting it in createDb() rather than a hook also means every caller is migrated, including scripts and tests, not just HTTP traffic.

The Cloudflare D1 workflow (the gotcha that isn't obvious)

D1 is Cloudflare's managed SQLite, and the SvelteKit + D1 combination needs one extra step: on D1 you manage migrations through Wrangler, not through drizzle-kit migrate.

# Generate the migration SQL as usual
npx drizzle-kit generate

# Apply it (--local for your local D1, --remote for production)
npx wrangler d1 migrations apply my-database --local
npx wrangler d1 migrations apply my-database --remote

Wrangler keeps a migration history table inside D1, so files run once, in order, and the --remote flag targets the real production database. I lost a day to this the first time — the SQL generation is identical, but who applies it is different. My SQLite/D1 kit scripts drizzle-kit generate (the generation side); applying to a remote D1 is a Wrangler operation rather than a drizzle-kit migrate call.

One correction to what you'll read in older posts: it's not true that drizzle-kit push can't work with D1 at all. If you configure the d1-http driver (account ID, database ID, and an API token with D1 edit permissions), push will sync your schema to a remote D1. It works — and it still produces no migration files, which is exactly why you treat it like any other push: fine for sketching, not for production.

One contrast worth stealing

The Supabase kit in the same family has no Drizzle at all. Its whole migration story is one line:

supabase db diff --schema public | supabase db push

It works, and it's less machinery — but it diffs against the linked project and pushes the result, so you still have no committed, reviewable .sql history in the repo. Once that database has real data, "what changed and when" starts living in the platform's history table instead of in your git log. That difference is the whole argument for versioned migrations, and it's easier to see when two kits in the same codebase take different approaches.

The decision rule

Situation	Approach
Local development	`push` is fine — fast iteration
CI/CD pipeline	`generate` → review SQL → `migrate` / `wrangler d1 migrations apply`
Production deployment	Versioned migrations, reviewed and applied explicitly
Multiple replicas on one database	Explicit pre-deploy step as the only writer; disable boot-time auto-migrate
Cloudflare D1	`generate` + `wrangler d1 migrations apply --remote`

Versioned, reviewable, hand-editable SQL migrations are the boring choice — and boring is what production wants.

This exact workflow ships in the two Drizzle-based VerdantStack SvelteKit starter kits — Multi-tenant SvelteKit Starter (SQLite/D1, v0.2.8, 298 tests) and SvelteKit + Postgres Starter (vendor-neutral Postgres, v0.1.6, 262 tests) — each at ≥95% line, branch, function, and statement coverage. The generated migrations live in the drizzle/ folder of each repo if you want a real example to crib from: github.com/verdantstack/sveltekit-postgres-starter. The third kit, SvelteKit + Supabase Starter (v0.2.6, 314 tests), is the Supabase-native one discussed above.

Live demos: postgres-starter.verdantstack-site.pages.dev (Postgres — applies its checked-in migrations at boot via createDb()) and multi-tenant-starter.verdantstack-site.pages.dev (D1).

Testing SvelteKit with Vitest: what 874 tests across three data layers taught me about the three tiers that actually matter

VerdantStack — Sat, 26 Sep 2026 02:27:57 +0000

I run 874 automated tests across three SvelteKit starter kits — the same multi-tenant service layer (orgs → members → invites → RBAC → billing → audit) exercised against three different data backends: SQLite/D1, Supabase, and vendor-neutral Postgres. The split is 298 + 314 + 262 per kit, and each suite sits at ≥95% line, branch, function, and statement coverage, enforced by the Vitest config.

Here's the testing strategy that caught real bugs — and the one that wasted my time.

Tier 1: unit tests (fast, no database)

Test service functions in isolation with the database mocked. These run in a couple of seconds.

// tests/rbac.test.ts
import { describe, it, expect } from 'vitest';
import { mayActOn, MATRIX } from '../src/lib/server/rbac';

describe('RBAC hierarchy', () => {
  it('owner can act on admin', () => {
    expect(mayActOn('owner', 'admin', 'members.role.set')).toBe(true);
  });

  it('admin cannot act on owner', () => {
    expect(mayActOn('admin', 'owner', 'members.role.set')).toBe(false);
  });

  it('member cannot invite', () => {
    expect(MATRIX.member).not.toContain('members.invite');
  });
});

What these catch: logic bugs in permission checks, role hierarchy violations, and business-rule edge cases.

What these miss: schema mismatches, constraint violations, RLS policies, migration bugs — everything that lives in the gap between your code and the database.

Tier 2: integration tests (real database)

Spin up a real test database and run actual queries. In the kits, a Docker Compose file starts Postgres on a dedicated test port, and each test wipes the tables first.

// tests/orgs-members.test.ts
import { describe, it, expect, beforeEach } from 'vitest';
import { createOrg } from '../src/lib/server/services/orgs';

let db: any;

beforeEach(async () => {
  // Truncate all tables between tests
  await db.execute(sql`TRUNCATE TABLE audit_log, invites, memberships, organizations CASCADE`);
});

describe('org creation', () => {
  it('creates org with creator as owner', async () => {
    const org = await createOrg(db, { name: 'Test Org', slug: 'test-org', userId: 'user-1' });
    expect(org.slug).toBe('test-org');

    const members = await db.select().from(memberships).where(eq(memberships.orgId, org.id));
    expect(members[0].role).toBe('owner');
    expect(members[0].userId).toBe('user-1');
  });

  it('rejects duplicate slugs', async () => {
    await createOrg(db, { name: 'Org 1', slug: 'dupe', userId: 'user-1' });
    await expect(
      createOrg(db, { name: 'Org 2', slug: 'dupe', userId: 'user-2' })
    ).rejects.toThrow();
  });
});

What these catch: schema drift, foreign-key and unique-constraint violations, migration ordering bugs, and type mismatches between the code and the actual database. These are the bugs that unit tests simply can't see.

What these miss: HTTP-level issues — hooks misconfiguration, auth-flow wiring, redirect logic.

Tier 3: HTTP-level tests (through SvelteKit)

Push real Request objects through the SvelteKit app itself. This exercises hooks.server.ts, auth, and routing — the whole pipeline, no browser needed.

// tests/http.test.ts
import { describe, it, expect } from 'vitest';
import { app } from '../src/app';

describe('POST /app/org/create', () => {
  it('requires authentication', async () => {
    const response = await app.request(new Request('http://localhost/app/org/create', {
      method: 'POST',
      body: new URLSearchParams({ name: 'Test' }),
    }));
    expect(response.status).toBe(303); // redirect to login
  });

  it('creates an org for an authenticated user', async () => {
    const response = await app.request(new Request('http://localhost/app/org/create', {
      method: 'POST',
      body: new URLSearchParams({ name: 'My Org', slug: 'my-org' }),
      headers: { cookie: 'session=valid-token-here' },
    }));
    expect(response.status).toBe(303);
    expect(response.headers.get('location')).toContain('/app');
  });
});

What these catch: hook misconfigurations, cookie and redirect handling, CSRF wiring — the glue that unit and integration tests never touch.

One config detail that cost me an afternoon: for HTTP tests inside Vitest you need the SvelteKit plugin and an inline dep so $app/$env aliases resolve:

// vitest.config.ts
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vitest/config';

export default defineConfig({
  plugins: [sveltekit()],
  test: {
    include: ['tests/**/*.test.ts'],
    server: {
      deps: { inline: ['@sveltejs/kit'] }, // resolve $app / $env aliases
    },
    fileParallelism: false,  // tier 2 tests share one database
    testTimeout: 10_000,
  },
});

The mistake I made early on

I mocked the database for everything. The suite was fast — hundreds of unit tests finished in seconds — but in my experience it caught maybe 40% of the bugs that actually reached production. The other 60% were:

Schema drift (code says role TEXT, the database says VARCHAR(20))
Migration-ordering bugs (the column doesn't exist yet)
RLS policies silently rejecting legitimate queries
Constraint violations on edge cases (unique indexes, FK cascades)

Adding a real-database integration tier moved almost all of that earlier in the pipeline. The suite got slower — the full run takes on the order of a minute — and production incidents dropped to near zero. Those catch-rate figures are estimates from my own projects, not law; the direction is what matters.

What I'd recommend

Situation	Tier to run	Speed	What it catches (est.)
Quick feedback during dev	Tier 1 (unit)	seconds	~40% of production bugs
CI/CD gate	Tier 1 + 2	~under a minute	~85% of production bugs
Full verification	All 3 tiers	~a minute	~95% of production bugs

The key insight: all three tiers are necessary. Unit tests alone miss too much; integration tests alone are too slow for rapid iteration; HTTP tests alone don't catch business-logic bugs. And cap it all with a coverage gate — ≥95% on line, branch, function, and statement — so the suite can't quietly shrink while features grow.

The patterns above are what the VerdantStack kits actually run: Multi-tenant SvelteKit Starter (SQLite/D1, v0.2.8, 298 tests), SvelteKit + Supabase Starter (v0.2.6, 314 tests), and SvelteKit + Postgres Starter (vendor-neutral Postgres, v0.1.6, 262 tests) — every suite ≥95% coverage on all four metrics, enforced in CI. Source code (public proof repos, source excluded by design): github.com/verdantstack.

Live demo of the Postgres kit: postgres-starter.verdantstack-site.pages.dev — running its 262 tests against a real Postgres database.

Deploying SvelteKit to Cloudflare Pages with a real database: D1, Postgres, and the gotchas nobody mentions

VerdantStack — Thu, 24 Sep 2026 03:14:58 +0000

Cloudflare Pages is the best free hosting for SvelteKit — global edge, zero cold starts, and a free tier that includes unlimited requests and 500 builds per month. But deploying with a real database instead of static pages has a few gotchas that took me days to figure out. Here's the setup that works, and the five things nobody warns you about.

The setup

npm create svelte@latest my-app
cd my-app
npm install

Install the Cloudflare adapter:

npm install -D @sveltejs/adapter-cloudflare

// svelte.config.js
import adapter from '@sveltejs/adapter-cloudflare';

export default {
  kit: {
    adapter: adapter({})
  }
};

Option 1: Cloudflare D1 (SQLite)

D1 is Cloudflare's managed SQLite. The free tier gives you 5 GB of storage, 5 million rows read per day, and 100,000 rows written per day.

# Create the database
npx wrangler d1 create my-database

# wrangler.toml
[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "your-database-id"

In SvelteKit, the binding arrives on event.platform.env:

// src/hooks.server.ts
import type { Handle } from '@sveltejs/kit';

export const handle: Handle = async ({ event, resolve }) => {
  event.locals.db = event.platform?.env.DB;
  return resolve(event);
};

// +page.server.ts
export const load = async ({ locals }) => {
  const posts = await locals.db.prepare('SELECT * FROM posts').all();
  return { posts };
};

Option 2: Postgres (via Supabase, Neon, or Hyperdrive)

If you need Postgres, the connection path depends on where it lives. For an existing Postgres, Hyperdrive gives Workers a pooled, cached connection:

# Create a Hyperdrive binding
npx wrangler hyperdrive create my-pg --connection-string="og69-9dce58d6uyn088://user:secret@ep-cool-12345.us-east-2.aws.neon.tech:5432/mydb"

# wrangler.toml
[[hyperdrive]]
binding = "DB"
id = "your-hyperdrive-id"

// src/lib/server/db.ts
import postgres from 'postgres';

let sql: ReturnType<typeof postgres>;

export function getDb(env: any) {
  if (!sql) {
    // Hyperdrive injects the connection string at runtime
    sql = postgres(env.DB.connectionString, {
      prepare: false, // see gotcha 3
      max: 10,
    });
  }
  return sql;
}

With Supabase or Neon you skip Hyperdrive entirely — connect straight to their pooler with postgres.js (or your driver of choice).

The five gotchas

1. process.env doesn't work in Workers (by default)

Workers don't run Node. Bindings land on event.platform.env, and SvelteKit's Cloudflare adapter maps $env/dynamic/private onto that in production — so prefer platform.env (or $env/dynamic/private) everywhere. process.env only exists if you opt into nodejs_compat and the nodejs_compat_populate_process_env compatibility flag; don't design around it.

// BAD — undefined on Workers by default
const dbUrl = process.env.DATABASE_URL;

// GOOD — reads from bindings
const dbUrl = event.platform?.env.DATABASE_URL;

2. Node built-ins aren't free imports

fs, path, and node:crypto don't exist on Workers unless you enable Node.js compatibility. The good news: Workers ship the Web Crypto API as a global — crypto.getRandomValues and crypto.subtle cover most of what people import node:crypto for:

// BAD — won't build without nodejs_compat
import { randomBytes } from 'node:crypto';

// GOOD — Web Crypto is a global on Workers
const bytes = new Uint8Array(32);
crypto.getRandomValues(bytes);

3. Prepared statements break with connection poolers

If you connect with postgres.js through a pooler (Supabase, Neon, PgBouncer), you must disable prepared statements:

const sql = postgres(DATABASE_URL, {
  prepare: false, // required for poolers
});

Without it you'll see prepared statement "_pgstmt_1" does not exist — the pooler doesn't pin a session, so the server-side prepared statement isn't there when the next request reuses the connection.

4. Scheduled jobs need cron triggers

Workers-style cron is how you run daily jobs (cleanup, re-seeding demo data):

# wrangler.toml for the worker
[triggers]
crons = ["0 3 * * *"]  # daily at 03:00 UTC

5. Environment variables are per-environment

Preview deployments (branch deploys) don't automatically inherit production secrets. Set them per environment — either in the Cloudflare dashboard or via:

npx wrangler pages secret put DATABASE_URL --project-name=my-project

Deploy

npm run build
npx wrangler pages deploy build --project-name=my-project

Which database?

Database	Best for	Free tier
D1 (SQLite)	Simple apps, no external dependencies	5 GB, 5M reads/day, 100K writes/day
Supabase (Postgres)	Auth + Realtime + RLS	500 MB per project, 50K MAU
Neon (Postgres)	Serverless Postgres with branching	0.5 GB storage per project
Hyperdrive + any Postgres	Bringing an existing database to Workers	Depends on your DB host

For a new app, start on D1; move to Postgres when you need RLS, richer querying, or a provider you already run elsewhere.

All three VerdantStack SvelteKit starters run on Cloudflare Pages with real databases, live today: the Multi-tenant Starter demo on D1, the Supabase Starter demo on Supabase Postgres, and the Postgres Starter demo on Supabase Postgres via the transaction pooler — each daily re-seeded by a cron Worker. For what it's worth, none of the kits hinge auth on Web Crypto: the SQLite/D1 and Postgres kits use scrypt + hashed sessions, and the Supabase kit uses Supabase Auth + RLS.

Product pages with the deploy guides and TypeDoc API reference: Multi-tenant SvelteKit Starter (v0.2.8) · SvelteKit + Supabase Starter (v0.2.6) · SvelteKit + Postgres Starter (v0.1.5). Source on GitHub: github.com/verdantstack.

Row-level security in SvelteKit: defense-in-depth that actually works with Drizzle ORM

VerdantStack — Thu, 10 Sep 2026 09:27:07 +0000

Row-level security is defense in depth. Here is what pooled connections break.

Most SaaS apps enforce tenancy at the application layer: every query includes WHERE org_id = ?. This works until it doesn't — a missed filter, a new endpoint, a refactor that drops the check. Row-level security (RLS) in Postgres catches the cases the application layer misses.

Here's how to wire RLS into a SvelteKit app using Drizzle ORM, without fighting the framework.

The problem with application-only tenancy

In a typical SvelteKit + Drizzle setup, your service layer looks like this:

// src/lib/server/services/orgs.ts
export async function getMembers(db: DrizzleDB, orgId: string) {
  return db.select().from(memberships)
    .where(eq(memberships.orgId, orgId));
}

Every caller must remember to pass orgId. Every new endpoint must extract it from the session. Every new developer on the team must know the convention. One missed where clause and tenant A sees tenant B's data.

RLS adds a database-level safety net: even if the application forgets the filter, Postgres enforces it.

Step 1: set the identity per request

RLS policies need to know who is making the request. Postgres has a SET LOCAL mechanism that sets a transaction-local variable:

-- Set during each request transaction
SET LOCAL app.current_user_id = 'user-uuid-here';
SET LOCAL app.current_org_id = 'org-uuid-here';

In SvelteKit, you set this in your hooks server, right after authentication:

// src/hooks.server.ts
import type { Handle } from '@sveltejs/kit';
import { db } from '$lib/server/db';
import { sql } from 'drizzle-orm';

export const handle: Handle = async ({ event, resolve }) => {
  const session = event.cookies.get('session');
  if (session) {
    const user = await getUserFromSession(db, session);
    if (user) {
      event.locals.user = user;
      event.locals.membership = await getActiveMembership(db, user.id);
    }
  }

  // Wrap the response in a transaction that sets the RLS identity
  const response = await db.transaction(async (tx) => {
    if (event.locals.user) {
      await tx.execute(sql`SET LOCAL app.current_user_id = ${event.locals.user.id}`);
      if (event.locals.membership) {
        await tx.execute(sql`SET LOCAL app.current_org_id = ${event.locals.membership.orgId}`);
      }
    }
    return resolve(event);
  });

  return response;
};

Step 2: write the RLS policies

-- Enable RLS on the memberships table
ALTER TABLE memberships ENABLE ROW LEVEL SECURITY;

-- Users can only see memberships in their current org
CREATE POLICY memberships_org_isolation ON memberships
  FOR ALL
  USING (org_id = current_setting('app.current_org_id')::uuid);

-- Users can only see their own user record
ALTER TABLE users ENABLE ROW LEVEL SECURITY;
CREATE POLICY users_self_only ON users
  FOR ALL
  USING (id = current_setting('app.current_user_id')::uuid);

Step 3: make Drizzle unaware (that's the point)

Here's the key insight: Drizzle doesn't need to know RLS exists. Your service layer stays clean:

export async function getMembers(db: DrizzleDB) {
  // No orgId parameter needed — RLS handles the filtering
  return db.select().from(memberships);
}

This is the defense-in-depth model: the application layer does filter by orgId (for performance and clarity), and the database layer also filters (as a safety net). If the application filter is correct, RLS is invisible. If the application filter is wrong, RLS catches it.

The gotcha: connection pooling

RLS uses SET LOCAL, which is transaction-scoped. This means it works correctly with connection pooling — the variable is set and cleared within each transaction, so there's no state leakage between requests.

But there's a catch: not all poolers support SET LOCAL correctly.

Pooler	`SET LOCAL` support	Notes
PgBouncer (transaction mode)	✅ Works	Recommended
Supavisor (transaction mode)	✅ Works	Supabase default
Node `pg` pool	✅ Works	Single-connection, no pooling issues
`postgres.js`	✅ Works	Connection-level, transaction-scoped
PgBouncer (session mode)	✅ Works	Less efficient but safe

The important thing: use transaction-mode pooling, not session-mode. Transaction mode gives each request a fresh transaction, which is exactly what RLS needs.

When to use this vs. application-only

Use application-only when:

Single-tenant app
Simple data model with few tables
Team is small and disciplined

Add RLS when:

Multi-tenant with shared database
Multiple developers/agents touching the codebase
You want a safety net that doesn't depend on human diligence
Enterprise customers ask "how do you isolate our data?"

RLS is not a replacement for application-level checks — it's a second line of defense. The application layer catches errors early (with better error messages). The database layer catches errors late (but catches all of them).

What I packaged

I built this pattern (RLS as opt-in defense-in-depth + connection pooling guidance + Drizzle integration) into a tested SvelteKit + Postgres starter. The RLS policies are in rls/0010_rls_policies.sql — opt-in, not forced.

Live demo: verdantstack.dev/r/dt-rls — try the RBAC: owner sees admin controls, member gets a 403. The RLS policies are there as defense-in-depth behind the application-layer checks.

Source on GitHub: verdantstack/sveltekit-postgres-starter

Pricing: $79 early bird → $129 standard. One license, unlimited projects, lifetime updates, 30-day refund.

Building invite flows that don't have race conditions in SvelteKit + Postgres

VerdantStack — Mon, 07 Sep 2026 03:46:18 +0000

Most invite-link implementations look correct in development and break in production. The edge cases aren't exotic — they're the normal concurrency you get when two people click the same link, or when someone clicks an expired token, or when a seat limit is hit between the check and the insert.

Here's how I built an invite flow that handles all of them, using SvelteKit, Postgres, and Drizzle ORM.

The flow looks simple

Owner creates invite → single-use link sent → recipient clicks → membership created → done

Five steps. But each step has failure modes that compound.

Edge case 1: token reuse

The link gets shared (Slack, email forward, clipboard accident). Two people click it within seconds.

The fix: hash the token before storing it in the database. The plaintext token only exists in the URL. When someone clicks, you hash the token from the URL, look up the hash, and delete it atomically — not "check if exists, then delete."

// Wrong: TOCTOU race condition
const invite = await db.select().from(invites)
  .where(eq(invites.tokenHash, tokenHash));
if (!invite) return fail(400, { message: 'Invalid invite' });
if (invite.expiresAtMs < Date.now()) return fail(400, { message: 'Expired' });
await db.delete(invites).where(eq(invites.id, invite.id));
// ^^^ Another request can slip in between the select and delete

// Right: single atomic operation
const [claimed] = await db.transaction(async (tx) => {
  const [row] = await tx.delete(invites)
    .where(and(
      eq(invites.tokenHash, tokenHash),
      gt(invites.expiresAtMs, Date.now()),
    ))
    .returning();
  if (!row) return [null];
  const [membership] = await tx.insert(memberships)
    .values({ orgId: row.orgId, userId, role: 'member', createdAtMs: Date.now() })
    .returning();
  return [membership];
});
if (!claimed) return fail(400, { message: 'Invalid or expired invite' });

Delete-first, insert-second, one transaction. If two requests arrive simultaneously, one wins the delete and the other gets null.

Edge case 2: seat limits

The org has 5 seats and 5 members. A 6th invite link was created before the limit was hit. Now someone clicks it.

The fix: check the seat count inside the same transaction that creates the membership — not before, not after.

// Inside the same transaction as the token claim:
const [{ count }] = await tx.select({ count: count() })
  .from(memberships)
  .where(eq(memberships.orgId, orgId));

const org = await tx.select().from(organizations)
  .where(eq(organizations.id, orgId));

if (count >= org.seatLimit) {
  // Don't delete the invite — let someone else try later if a seat opens
  throw new Error('SEAT_LIMIT_REACHED');
}

The seat check and the membership insert happen atomically. No gap for a second click to slip through.

Edge case 3: invite creation also needs protection

What if the owner creates 10 invites when they only have 2 seats left? Each invite is "valid" at creation time, but 8 of them will fail at claim time.

Two approaches:

Count active (unclaimed) invites + existing members vs. seat limit at invite creation time. Reject early.
Let anyone create invites, enforce at claim time. Simpler, but the UX is worse (people get a link that doesn't work).

I went with option 1 — it's a few extra lines and catches the problem where it's cheap to catch:

const activeInvites = await db.select({ count: count() })
  .from(invites)
  .where(eq(invites.orgId, orgId));
const members = await db.select({ count: count() })
  .from(memberships)
  .where(eq(memberships.orgId, orgId));

if (activeInvites[0].count + members[0].count >= org.seatLimit) {
  return fail(400, { message: 'No seats available' });
}

Edge case 4: the token itself

Don't use sequential IDs or predictable strings. Generate a cryptographically random token, hash it with scrypt (not SHA-256 — scrypt is slower by design, which makes brute-force harder), and store only the hash.

import { randomBytes, scrypt, timingSafeEqual } from 'node:crypto';
import { promisify } from 'node:util';

const scryptAsync = promisify(scrypt);

async function createInviteToken() {
  const raw = randomBytes(32).toString('base64url');
  const salt = randomBytes(16);
  const derived = await scryptAsync(raw, salt, 64);
  const tokenHash = `${salt.toString('hex')}:${Buffer.from(derived).toString('hex')}`;
  return { raw, tokenHash }; // raw goes in the URL, tokenHash goes in the DB
}

What I packaged

I built this pattern (plus RBAC, seat billing, and audit logging) into a tested SvelteKit + Postgres starter. 194 automated tests against a real Postgres database, including the exact race-condition scenarios above.

Live demo: verdantstack.dev/r/dt-invite — seeded with two users (owner + member), resets daily. Try creating an invite and claiming it.

Source on GitHub: verdantstack/sveltekit-postgres-starter

Pricing: $79 early bird → $129 standard. One license, unlimited projects, lifetime updates, 30-day refund.