Volcano SDK

The official JavaScript/TypeScript SDK for Volcano.

npm install @volcano.dev/sdk

import { VolcanoClient } from '@volcano.dev/sdk';

const volcano = new VolcanoClient({
  apiUrl: 'https://api.yourproject.volcano.dev',
  anonKey: 'your-anon-key',
});

// Authentication
const { user } = await volcano.auth.signIn({
  email: 'user@example.com',
  password: 'password123',
});

// Database queries
volcano.database('my-database');
const { data } = await volcano
  .from('posts')
  .select('*')
  .eq('published', true)
  .order('created_at', { ascending: false });

// File storage
const { data: file } = await volcano.storage.from('uploads').upload('photo.jpg', imageFile);

// Backend leader election (initialize accessToken with a service-role key)
const lockResult = await volcano.locks.withLock('daily-rollup', { ttl: 30 }, async ({ signal }) => {
  await runRollup({ signal });
});
if (lockResult.error) throw lockResult.error;

// Realtime subscriptions
import { VolcanoRealtime } from '@volcano.dev/sdk/realtime';

const realtime = new VolcanoRealtime({
  apiUrl: 'https://api.yourproject.volcano.dev',
  anonKey: 'your-anon-key',
  accessToken: volcano.accessToken,
});

await realtime.connect();
const channel = realtime.channel('updates', { type: 'postgres' });
channel.onPostgresChanges('INSERT', 'public', 'posts', (change) => {
  console.log('New post:', change.record);
});
await channel.subscribe();

VolcanoClient is the preferred name for new code. VolcanoAuth remains a compatible alias, so existing applications do not need to change imports.

For browser realtime connections, make sure the browser app's origin is allowed in your project's auth CORS settings. The anonymous key is used to identify the project before the WebSocket upgrade completes.

Installing @volcano.dev/sdk pulls in two packages, both for realtime:

Writing a durable function needs one more, and you do not install it: Volcano adds it when it builds a function deployed as durable.

The SDK declares it as an optional peer dependency, which is what lets the SDK resolve it in the deployed function without anything else installing it: a browser bundle and a standard function stay as small as they were. Its install closure is ~19 MB, which is why it belongs in durable functions rather than in everyone's node_modules. It also requires Node 22, where this SDK supports Node 20, so it is only ever installed on the runtimes that can host a durable function (nodejs22.x and nodejs24.x).

A function that declares it explicitly is left alone by the build, version included, which is the way to pin a specific runtime.

See CONTRIBUTING.md for local workflows, package structure, and pull request expectations.

If you believe you have found a security vulnerability, do not open a public issue. Follow SECURITY.md instead.

Volcano SDK is licensed under the Apache License 2.0. See LICENSE.