Volcano Sdk

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

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