Volcano SDK

The official JavaScript/TypeScript SDK for Volcano.

Installation

npm install @volcano.dev/sdk

Quick Start

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: '[email protected]',
  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.

Documentation

| Guide | Description | | ------------------------------------------------ | --------------------------------- | | Getting Started | Installation and setup | | Authentication | Sign-up, sign-in, OAuth, sessions | | Database | Query builder and CRUD operations | | Storage | File upload and management | | Realtime | Live subscriptions and presence | | Functions | Serverless function invocation | | Durable functions | Checkpointed, long-running work | | Project locks | Renewable backend leases | | Next.js | Server components and middleware | | TypeScript | Type definitions | | Error Handling | Error patterns |

Dependencies

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

| Package | Why | | -------------------------------------------------------- | -------------------------------------------------------------------- | | centrifuge | The realtime protocol client | | ws | WebSocket transport outside the browser, loaded only when it is used |

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

| Package | Why | | ---------------------------------------------------------------------------------------------- | ----------------------------------------------- | | @aws/durable-execution-sdk-js | Checkpointing, under @volcano.dev/sdk/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.

Contributing

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.

License

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