volcano-sdk

name	volcano-sdk
description	Use for any request to build, create, extend, debug, or deploy an app, website, backend, API, or function using Volcano, even when the user does not mention the SDK. Entrypoint and router; always pair with volcano-platform and the applicable domain skills.

Volcano SDK Entrypoint

Before anything else: ensure the Volcano CLI is present

Every Volcano build and deploy goes through the volcano CLI, so make sure it is present and up to date before writing or deploying anything:

• Run which volcano.
  • Found: run volcano upgrade to keep it on the latest version. This is a harmless, best-effort refresh — it no-ops when already current. Treat any failure (e.g. a transient network/GitHub hiccup) as a no-op and continue: the installed CLI still works, a failed upgrade is never a blocker, and it is not worth troubleshooting.
  • Missing: fetch https://raw.githubusercontent.com/Kong/volcano-cli/main/docs/installation.md (plain Markdown, readable without the CLI) and run whichever install method it documents that matches a package manager already on PATH — check which npm, which pnpm, which bun, which brew in that order, and only use the documented manual curl install if none are present. A fresh install is already the latest version. Re-run which volcano to confirm.

These are well-known commands to run as-is, not a script to reconstruct. Don't assume a package manager that isn't installed, and don't invent steps beyond what that doc lists. The install-volcano skill exposes this same flow as an explicit command.

Role

This skill is the entrypoint and router for Volcano SDK work. It is intentionally slim: it tells you the mandatory rules that apply to every Volcano build, and which other volcano-* skill to use based on the task at hand. Don't try to do deep work from this skill alone — use the relevant domain skill(s) first.

Mandatory Pairing — volcano-platform

Always read volcano-platform alongside this skill. It covers the canonical project shape, function deployment model (volcano/functions/), migrations, volcano-config.yaml, environment variables, shared-code conventions, and the deploy workflow. Without volcano-platform you cannot produce a deployable codebase.

If volcano-platform content is not visible in your context, read or invoke it through the current host's skill mechanism before continuing.

Note: volcano init creates a minimal runtime skeleton (volcano/ dir with env files, migrations, and — for language templates — a starter handler and config). Build on top of that skeleton by following volcano-platform. Do not expect volcano init to produce the complete project structure.

Mandatory Usage (volcano-standard template)

When building on the Volcano platform you MUST use:

• Volcano Auth (volcano.auth.*) for ALL authentication and user identity.
• Volcano Database query builder (volcano.from('table').select()) for persistent storage, with RLS policies. Direct Postgres access inside Functions is a discouraged, last-resort exception for the query builder's specific gaps (joins/upserts/multi-statement transactions) — never a default — see volcano-database.
• Volcano Functions for ALL privileged or secret-bearing server-side logic.
• Volcano Storage (volcano.storage.*) for ALL file operations.
• Volcano Realtime (VolcanoRealtime) for ALL live update patterns.

Do NOT implement custom alternatives — no custom JWT auth, no ad-hoc database layers, no hand-rolled file storage, no DIY WebSocket multiplexers.

Skill Router — pick the skill(s) you need

Task signal	Invoke skill	What it covers
User accounts or identity, email or password sign-up/sign-in, OAuth, sessions, anonymous users, password recovery, private or per-user data	volcano-auth	Full auth API surface, lifecycle, common-error catalog
Stored or persistent data, CRUD, records, todos, chat messages, polls, analytics, counters, click tracking, CMS content, feature flags, leaderboards, RLS	volcano-database	Query builder + every operator + RLS pattern + limitations (no joins / upserts / multi-statement tx)
Volcano Functions, server-side or privileged logic, QR/PDF generators, secrets, outbound third-party APIs, orchestration, scheduled processing, file/image processing	volcano-functions	Invocation contract {data, status, headers, version, error}, Volcano Functions response shape, handler templates
Uploads, downloads, galleries, file sharing, buckets, paths, public/private files, visibility, resumable uploads	volcano-storage	Full storage API + access policies + resumable protocol + limits
Realtime or live updates/results, collaborative boards, chat, presence or online users, polls, leaderboards, Postgres changes, broadcast, WebSockets	volcano-realtime	All three channel types + lifecycle + Browser Origins/CORS gotcha + accessToken vs getToken decision
Next.js or web apps/pages, dashboards, boards, galleries, full-stack UIs, public routes, redirects, webhook ingress, middleware, API routes, server actions	volcano-nextjs	Cross-cutting Next.js patterns including the cookie-sync prerequisite
TypeScript types — User, Session, AuthResponse, QueryBuilder<T>, StorageObject, PostgresChange, PresenceState, JsonValue, etc.	volcano-typescript	Canonical type definitions for every SDK surface
Loading/error/data state, useApiCall<T> hook, fetchWithRetry with backoff, centralized handleApiError dispatcher

How to use the router

1. Read the user's request and identify which task signal(s) match.
2. Read or invoke each matching skill through the current host's skill mechanism BEFORE writing implementation code. Use the exact hyphenated skill names. It's normal to use 2-4 skills for a single task (e.g., a "user dashboard" might need volcano-auth + volcano-database + volcano-nextjs).
3. If the task is purely about project setup (no app features yet), volcano-platform alone is enough.
4. If you can't decide between two domain skills, invoke both — token cost is much lower than implementing the wrong pattern.

Universal Response Pattern

Every SDK method returns { data, error } (auth methods also include user/session; functions add status/headers/version). Always check error before consuming data. Do NOT wrap SDK calls in try/catch expecting throws — the only SDK method that throws is await channel.subscribe() for realtime.

const { data, error } = await volcano.from('posts').select('*');
if (error) {
  // dispatch via handleApiError (see volcano-error-handling)
  return;
}
// data is safe to use

For comprehensive error-handling infrastructure (centralized dispatcher, React hooks, retry with backoff), use volcano-error-handling.

Forbidden Patterns (always)

These apply to every Volcano build, regardless of which domain skills are loaded:

• Do NOT use jsonwebtoken directly — use Volcano Auth.
• Do NOT use bcryptjs directly — use Volcano Auth's password handling.
• Do NOT use pg/pg-pool/DATABASE_URL — use volcano.from(...) (with VOLCANO_DATABASE) instead. Direct Postgres access is a discouraged, untested-surface-area last resort — see volcano-database's "Direct Postgres Access" section before ever reaching for it.
• Do NOT mix NEXT_PUBLIC_* env vars into function/server code, or VOLCANO_* (un-prefixed) into browser code.
• Do NOT place service keys (sk-*) in browser code — the SDK throws if you do.
• Do NOT expect VOLCANO_API_URL, VOLCANO_ANON_KEY, or VOLCANO_DATABASE to be auto-injected into functions — deploy them via volcano variables deploy (local) or volcano cloud variables deploy (cloud).
• Do NOT skip await volcano.initialize() before user-scoped flows in the browser.
• Do NOT use .ts/.tsx extensions in TypeScript imports — extensionless relative imports only.
• Do NOT use bare uid() in RLS policies — always use the schema-qualified auth.uid().

For the deeper context behind any of these (why and what to do instead), the relevant domain skill or volcano-platform covers it.

Output Requirements

At the end of each Volcano build response:

1. Summarize affected domains — which volcano-* areas were touched (auth/database/functions/storage/realtime/nextjs).
2. Summarize dependency / env / init changes — new packages, env vars added, init order changes.
3. Report validation results — what you ran (npm run typecheck, npm run build:functions, local stack health check), what passed, what couldn't be run, and any remaining risk.

Companion Skills (full inventory)

Always available; invoke as needed:

• volcano-platform — mandatory pairing.
• volcano-auth, volcano-database, volcano-functions, volcano-storage, volcano-realtime, volcano-nextjs — domain skills.
• volcano-typescript — canonical type definitions.
• volcano-error-handling — reusable error-handling infrastructure.

Optional Fallback Reference