@zvk/supabase-kit

Supabase environment, client, storage, local bootstrap, and test utilities for ZVK applications.

Imports

import { parseSupabasePublicEnv } from "@zvk/supabase-kit";
import {
  mapLocalSupabaseStatusEnv,
  parseEnvText,
  parseSupabaseSecretEnv,
  resolveSupabasePublicEnv,
  resolveSupabaseSecretEnv,
  upsertManagedEnvBlock
} from "@zvk/supabase-kit/env";
import {
  createBrowserSupabaseClient,
  resolveBrowserSupabaseClientConfig
} from "@zvk/supabase-kit/next/client";
import {
  createNextServerSupabaseClient,
  resolveNextServerSupabaseClientConfig
} from "@zvk/supabase-kit/next/server";
import {
  createSupabaseAdminClient,
  resolveSupabaseAdminClientConfig
} from "@zvk/supabase-kit/next/admin";
import { createSupabaseSessionProxy } from "@zvk/supabase-kit/next/proxy";
import { createUploadDescriptor } from "@zvk/supabase-kit/storage";
import { createOrganizationStoragePolicy } from "@zvk/supabase-kit/storage/org";
import {
  createOrganizationSignedStorageUrl,
  createOrganizationStorageWorkflow,
  createSignedStorageUrl,
  uploadOrganizationStorageObject
} from "@zvk/supabase-kit/storage/server";
import {
  createOrganizationSignedStorageUrlFake,
  createOrganizationStorageWorkflowFake,
  createSupabaseStorageFake
} from "@zvk/supabase-kit/test";
import {
  classifySupabaseStatusFailure,
  createLocalSupabaseBootstrapPlan
} from "@zvk/supabase-kit/local";

The root export is browser-safe. Server-only helpers live under explicit storage/server, next/server, next/proxy, and next/admin subpaths.

See ../../docs/package-boundary-matrix.md for the package-family runtime boundary matrix covering browser-safe, server-only, Node-only, adapter, and test-only subpaths.

Environment

Public clients prefer NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY. The legacy NEXT_PUBLIC_SUPABASE_ANON_KEY alias is accepted for existing applications. Admin clients prefer SUPABASE_SECRET_KEY; SUPABASE_SERVICE_ROLE_KEY is accepted as a legacy alias.

const env = parseSupabasePublicEnv(process.env);

if (!env.ok) {
  throw new Error(env.error.message);
}

Script helpers under @zvk/supabase-kit/env can parse dotenv-style text, map supabase status -o env output to app env keys, map remote env aliases, manage caller-labeled env blocks, and redact secret values before printing. Apps still own file paths, labels, source files, command execution, and writes.

Clients

const browser = createBrowserSupabaseClient(process.env);
const server = await createNextServerSupabaseClient(process.env);
const admin = createSupabaseAdminClient(process.env);

Use the resolve*Config helpers when a Server Action, route handler, or local script should return a Result instead of throwing on missing env.

Admin clients are never exported from the package root and are created without persistent sessions.

Storage

const descriptor = createUploadDescriptor({
  bucket: "documents",
  objectPath: "org_1/project_1/file.pdf",
  contentType: "application/pdf"
});

Storage helpers normalize paths and return Result envelopes. They do not embed buckets, organization rules, RLS policy, entitlements, or migration behavior.

createOrganizationStoragePolicy is available for apps that want a reusable organization-prefix object path policy. Use requireStorageTarget from that policy when a storage operation needs both an allowed bucket and an organization-prefixed object path. Bucket names, RLS policy, and storage tables remain app-owned.

Use createOrganizationSignedStorageUrl when an app needs to validate an allowed bucket and organization-prefixed object path before creating a private bucket signed URL from a server-only Supabase client.

Use uploadOrganizationStorageObject when an app needs to validate an allowed bucket and organization-prefixed object path before uploading from a server-only Supabase client.

Use createOrganizationStorageWorkflow when a server module repeats the same policy/client pair across upload, signed URL, download, or remove operations:

const organizationStorage = createOrganizationStorageWorkflow({
  client: adminClient,
  policy
});

const download = await organizationStorage.download({
  organizationId: "org_1",
  objectPath: "org_1/docs/file.pdf"
});

const upload = await organizationStorage.upload({
  organizationId: "org_1",
  objectPath: "org_1/docs/report.pdf",
  body: file,
  options: {
    contentType: file.type
  }
});

The workflow validates buckets and object paths before each operation. Bucket names, RLS policy, organization authorization, file-type rules, content scanning, and lifecycle cleanup remain app-owned.

createSupabaseStorageFake records upload, signed URL, download, and remove operations in tests. Use queueUploadResponse or queueSignedUrlResponse to force the next matching call to return an error or missing value, and reset to clear fake state between tests. Use createOrganizationSignedStorageUrlFake or createOrganizationStorageWorkflowFake when a test needs to mock server-only storage helpers without importing their server-only boundary.

Local Bootstrap

createLocalSupabaseBootstrapPlan returns command descriptions for app-owned scripts. It does not spawn processes, reset databases, generate types, write files, run Docker, or create SQL.

Local diagnostic helpers under @zvk/supabase-kit/local parse Docker context lists and classify supabase status failure text. They do not run Docker or the Supabase CLI, and app scripts still own terminal output and remediation copy.

Repo Skill

This repository keeps the Codex usage and maintenance skill at:

.codex/skills/use-zvk-supabase-kit/SKILL.md

Use that skill before maintaining this package or replacing local app src/lib/supabase/*, storage helpers, local Supabase scripts, or Supabase test fakes. The skill includes Next App Router, storage path, local dev env, migration, and testing references.

Migration Notes

Prefer publishable and secret API keys for new work. Legacy anon and service-role env names are accepted only as compatibility aliases while apps migrate.

Keep server-only imports explicit. Root imports, env, storage, storage/org, test, local, and next/client are browser-safe; storage/server, next/server, next/proxy, and next/admin are server-only subpaths.

Local bootstrap helpers describe commands so application scripts can decide how to execute them. Diagnostic helpers classify command output after the app runs its own commands. Port drift diagnostics, .env.local writing, supabase/config.toml parsing, and dev-server restart behavior remain app-owned.

Anti-Goals

This package does not provide RBAC, route guards, migrations, RLS policies, generated database clients, billing flows, or app migration code. Those remain application-owned.