Official SDK for Runtime Studio — real-time collaboration, version control, plugin ecosystem, multi-format export, AI-powered design suggestions, and analytics. All in one system.
npm install @runtime-studio/sdk
# or
yarn add @runtime-studio/sdk
# or
pnpm add @runtime-studio/sdk
import { RuntimeStudioClient } from '@runtime-studio/sdk';
const studio = new RuntimeStudioClient({
apiKey: process.env.RUNTIME_STUDIO_API_KEY!,
openaiApiKey: process.env.OPENAI_API_KEY!, // required for AI features
});
// List your workspaces
const workspaces = await studio.projects.listWorkspaces();
// Create a project
const project = await studio.projects.createProject(workspaces[0].id, {
name: 'My Design System',
});
// Add a canvas node
const button = await studio.projects.addNode(project.id, {
type: 'component',
name: 'Primary Button',
x: 100, y: 100, width: 160, height: 44,
styles: { backgroundColor: '#0F172A', borderRadius: 8, color: '#FFFFFF' },
});Copy .env.example to .env and fill in your keys:
cp .env.example .env
| Variable | Required | Description |
|---|---|---|
| RUNTIME_STUDIO_API_KEY | Yes | Your Runtime Studio API key |
| OPENAI_API_KEY | For AI features | Your OpenAI API key |
| RUNTIME_STUDIO_BASE_URL | No | Override API base URL |
src/
├── client.ts # RuntimeStudioClient — main entry point
├── index.ts # Public exports
├── modules/
│ ├── projects.ts # Workspace & project management, canvas CRUD
│ ├── collaboration.ts # Real-time WebSocket collaboration
│ ├── version-control.ts # Branches, commits, rollback, diff
│ ├── plugins.ts # Plugin marketplace & webhook management
│ ├── export.ts # Multi-format export (SVG, CSS, React, Vue…)
│ ├── ai.ts # AI suggestions, generation, chat (OpenAI)
│ └── analytics.ts # Usage metrics, component adoption, velocity
├── types/
│ └── index.ts # All TypeScript types & interfaces
└── utils/
├── http.ts # Typed HTTP client with error handling
└── emitter.ts # Type-safe event emitter
examples/
├── basic-usage.ts # Full-featured walkthrough
└── ai-only.ts # AI features deep-dive
| Option | Type | Default | Description |
|---|---|---|---|
| apiKey | string | — | Runtime Studio API key (required) |
| openaiApiKey | string | — | OpenAI key for AI module |
| baseUrl | string | https://api.runtimestudio.io/v1 | API base URL |
| timeout | number | 30000 | Request timeout in ms |
// Workspaces
studio.projects.listWorkspaces()
studio.projects.getWorkspace(workspaceId)
// Projects
studio.projects.listProjects(workspaceId, { page, pageSize, search })
studio.projects.getProject(projectId)
studio.projects.createProject(workspaceId, { name, description })
studio.projects.updateProject(projectId, { name, description })
studio.projects.deleteProject(projectId)
// Canvas
studio.projects.getCanvas(projectId)
studio.projects.updateCanvas(projectId, nodes)
studio.projects.addNode(projectId, node)
studio.projects.updateNode(projectId, nodeId, patch)
studio.projects.deleteNode(projectId, nodeId)Returns a CollaborationClient connected via WebSocket.
const collab = studio.collaboration(project.id);
collab.on('connected', () => { /* session open */ });
collab.on('user.join', (presence) => { /* new collaborator */ });
collab.on('user.leave', ({ userId }) => { /* collaborator left */ });
collab.on('cursor.move', (cursor) => { /* live cursor */ });
collab.on('node.update', (msg) => { /* remote edit */ });
collab.on('presence.update', (users) => { /* full presence list */ });
collab.connect();
// Send your own events
collab.sendCursorMove(x, y);
collab.sendNodeUpdate(nodeId, patch);
collab.sendSelectionChange([nodeId]);
// Read current presence
const users = collab.getPresence();
collab.disconnect();// Branches
studio.versionControl.listBranches(projectId)
studio.versionControl.createBranch(projectId, name, fromBranchId?)
studio.versionControl.deleteBranch(projectId, branchId)
// Commits
studio.versionControl.listCommits(projectId, branchId, { page, pageSize })
studio.versionControl.commit(projectId, branchId, message, canvas)
studio.versionControl.getCommit(projectId, commitId)
// Rollback (< 1 second)
studio.versionControl.rollback(projectId, commitId)
// Diff between two commits
studio.versionControl.diff(projectId, fromCommitId, toCommitId)studio.plugins.list({ page, pageSize, status, search })
studio.plugins.get(slug)
studio.plugins.listInstalled(projectId)
studio.plugins.install(projectId, slug)
studio.plugins.uninstall(projectId, slug)
studio.plugins.configure(projectId, slug, config)
studio.plugins.callWebhook(projectId, slug, event, data)// Export whole project or specific nodes
studio.export.export(projectId, {
format: 'react', // 'svg' | 'css' | 'react' | 'vue' | 'flutter' | 'png' | 'pdf'
nodeIds: [nodeId],
scale: 2,
framework: { componentName: 'Button', typescript: true, styled: true },
})
// Shorthand for a single node
studio.export.exportNode(projectId, nodeId, 'svg')
studio.export.getSupportedFormats()
studio.export.getExportHistory(projectId)
studio.export.toDownloadUrl(projectId, exportId)// Context-aware design suggestions
studio.ai.suggest({
context: 'Navigation sidebar for a SaaS dashboard',
nodeType: 'component', // optional
maxSuggestions: 5,
temperature: 0.7,
})
// Generate canvas nodes from a natural language prompt
studio.ai.generate({
prompt: 'Create a 4-column stats row with metric cards',
projectId,
canvasContext: canvas, // optional — gives model awareness of existing canvas
maxTokens: 2000,
})
// Describe an existing node in plain language
studio.ai.describeNode(node)
// Conversational design assistant
studio.ai.chat({ messages, canvasContext }) // resolves to string
studio.ai.chat({ messages, canvasContext, stream: true }) // async iterable tokensstudio.analytics.getDashboard(projectId, '30d') // full dashboard
studio.analytics.getUsageMetrics(projectId, '7d')
studio.analytics.getComponentAdoption(projectId, { limit: 10, range: '30d' })
studio.analytics.getTeamVelocity(projectId, '14d')
studio.analytics.trackEvent(projectId, 'my.event', { key: 'value' })All HTTP methods throw RuntimeStudioError on non-2xx responses:
import { RuntimeStudioError } from '@runtime-studio/sdk';
try {
await studio.projects.getProject('unknown-id');
} catch (err) {
if (err instanceof RuntimeStudioError) {
console.error(err.status, err.code, err.message);
}
}# Copy and fill in your credentials
cp .env.example .env
# Install dependencies
npm install
# Full walkthrough
npx ts-node examples/basic-usage.ts
# AI features only
npx ts-node examples/ai-only.ts
MIT