StealthQL

0.2.13 verified Sat May 09 auth: no javascript

StealthQL (v0.2.13) is a repo-native backend capsule for Next.js that bundles a local PGlite database, built-in auth (magic links, Google/GitHub/Facebook OAuth, recovery codes, org membership, service accounts, share tokens), policy-based row access control, field masks, Google-Sheets-style shares with proposals/CSV round-trip/expiration/revocation/audit logs, scheduled jobs, compliance evidence, and one-command deployment to DigitalOcean or Vercel+DigitalOcean split. Published on npm, TypeScript ships types, requires Node >=20, and follows a local-first dev loop with hot-reload. Differentiates from Supabase/Firebase by being fully self-hosted, repo-native (capsule files checked into your repo), and LLM-friendly.

Common errors

error ERR_REQUIRE_ESM ↓

cause Trying to require('stealthql') in a CommonJS file

fix

Use import('stealthql') or switch to ESM (type: module in package.json)

error Module not found: Can't resolve 'stealthql/auth' ↓

cause Using older version before auth subpath was added (<0.2.5)

fix

Upgrade stealthql: npm install stealthql@latest

error Error: createCapsule is not a function ↓

cause Importing createCapsule from main 'stealthql' instead of 'stealthql/capsule'

fix

Change import to import { createCapsule } from 'stealthql/capsule'

error Error: Node version >=20 required ↓

cause Running on Node <20

fix

Install Node v20 or later

error Error: PGlite not initialized. Set PGLITE_DATA_DIR or configure storage ↓

cause No persistent storage configured; PGlite defaults to in-memory which is lost on restart

fix

Set environment variable PGLITE_DATA_DIR to a persistent path, or add storage configuration in stealth.storage.js

Warnings

breaking Removed default export in v0.2.0; use named exports like createCapsule from subpaths ↓

fix Replace `import StealthQL from 'stealthql'` with specific imports like `import { createCapsule } from 'stealthql/capsule'`

breaking Requires Node >=20; older versions incompatible ↓

fix Upgrade Node to v20 or later

breaking ESM-only since v0.2.0; CommonJS require() fails ↓

fix Use ESM imports (import/export) or dynamic import() in CommonJS files

deprecated setup command with --javascript flag is deprecated; use --typescript for new projects ↓

fix Use `npx stealthql setup next --typescript` instead of --javascript

gotcha PGlite database is in-memory by default; data lost on server restart unless configured with persistent storage ↓

fix Set `PGLITE_DATA_DIR` environment variable or configure `storage` in stealth.storage.js

gotcha Hot-reload does not apply schema changes that drop columns or tables; requires full restart ↓

fix Run `npm run build:capsule` and restart dev server after destructive schema changes

Install

npm install stealthql

yarn add stealthql

pnpm add stealthql

Imports

default import
wrong
```
const StealthQL = require('stealthql')
```
correct
```
import StealthQL from 'stealthql'
```
StealthQL is ESM-only since v0.2.0; CommonJS require() will fail with ERR_REQUIRE_ESM
createCapsule
wrong
```
import { createCapsule } from 'stealthql'
```
correct
```
import { createCapsule } from 'stealthql/capsule'
```
createCapsule is exported from stealthql/capsule subpath, not the main entry

defineAuth

wrong

import { defineAuth } from 'stealthql'

correct

import { defineAuth } from 'stealthql/auth'

Auth helpers are under stealthql/auth since v0.2.5

type Actor
wrong
```
import { Actor } from 'stealthql/types'
```
correct
```
import type { Actor } from 'stealthql/types'
```
Type imports should use `import type` to avoid runtime errors; Actor is only a type, not a value

runMigration

wrong

import { runMigration } from 'stealthql'

correct

import { runMigration } from 'stealthql/database'

Database helpers are under stealthql/database subpath

Quickstart

Scaffolds a Next.js project with StealthQL backend capsule, local database, auth, and hot-reload dev server.

npm init -y && npm install next react react-dom stealthql && npx stealthql setup next && npm run dev:stealth