Skip to main content

​
Install

npm install @vela-event/sdk

pnpm add @vela-event/sdk

yarn add @vela-event/sdk

​
Requirements

  • Node.js 18+ — the SDK uses the native fetch API added in Node 18
  • Works in all modern browsers (Chrome 95+, Firefox 90+, Safari 15+)
  • Compatible with edge runtimes: Cloudflare Workers, Vercel Edge Functions, Deno
If you need to use the SDK in Node.js 16 or earlier, pass a custom fetch implementation via the fetchImpl option: 
import nodeFetch from 'node-fetch';
import { VelaIngestClient } from '@vela-event/sdk';

const ingest = new VelaIngestClient(process.env.VELA_API_KEY!, {
  fetchImpl: nodeFetch as unknown as typeof fetch,
});

​
Set up credentials

# For management operations (apps, schemas, rules)
export VELA_CLIENT_SECRET="vela_cs_..."

# For event ingestion
export VELA_API_KEY="vela_live_..."

# .env — add this to .gitignore
VELA_CLIENT_SECRET=vela_cs_...
VELA_API_KEY=vela_live_...
See the credentials guide for how to generate these values. Client secrets come from Settings → Client Secrets in the dashboard. API keys are generated when you create an app.

​
Verify your setup

Run this to confirm the SDK can connect and your credentials are valid: 
import { VelaManagementClient } from '@vela-event/sdk';

const client = new VelaManagementClient(process.env.VELA_CLIENT_SECRET!);

try {
  const apps = await client.apps.list();
  console.log(`Connected! ${apps.length} app(s) found.`);
} catch (err) {
  console.error('Connection failed:', err.message);
}
If you see Connected! N app(s) found., you’re ready.

​
Self-hosted setup

If you’re running Vela on your own infrastructure, pass the baseUrl option pointing to your instance: 
import { VelaIngestClient, VelaManagementClient } from '@vela-event/sdk';

const ingest = new VelaIngestClient(process.env.VELA_API_KEY!, {
  baseUrl: 'https://vela.your-domain.com',
});

const client = new VelaManagementClient(process.env.VELA_CLIENT_SECRET!, {
  baseUrl: 'https://vela.your-domain.com',
});

​
TypeScript configuration

The SDK ships with full type declarations. No @types package is needed. Recommended tsconfig.json settings: 
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true
  }
}
For CommonJS projects: 
{
  "compilerOptions": {
    "target": "ES2019",
    "module": "CommonJS",
    "strict": true
  }
}