Skip to main content

​
Package Manager Installation

Install the SDK using your preferred package manager: 
npm install gambiarra-sdk ai

​
Peer Dependencies

The Gambiarra SDK requires the following peer dependencies:
​
ai
string
required
Vercel AI SDK (versions 4.x, 5.x, or 6.x)The AI SDK provides the core functionality for AI completions, streaming, and tool calling.
​
typescript
string
TypeScript 5.x (recommended)While not strictly required at runtime, TypeScript is highly recommended for full type safety.

​
Install Peer Dependencies

If you don’t have the AI SDK installed: 
npm install ai

​
TypeScript Configuration

For optimal type checking and import resolution, configure your tsconfig.json:
tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ES2022"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "isolatedModules": true
  }
}

​
Key Settings Explained

Use "bundler" for modern bundlers (Vite, esbuild, webpack 5+) or "node16" for Node.js projects.
Enables all strict type-checking options for maximum type safety with the SDK’s types.
Ensures compatibility with CommonJS modules and default imports.

​
Verify Installation

Create a test file to verify the SDK is installed correctly:
test-sdk.ts
import { createGambiarra } from "gambiarra-sdk";
import type { ParticipantInfo } from "gambiarra-sdk";

console.log("Gambiarra SDK installed successfully!");

// Type check - this should not produce any errors
const provider = createGambiarra({ roomCode: "TEST" });
console.log("Base URL:", provider.baseURL);
Run the test: 
bun run test-sdk.ts
Expected output: 
Gambiarra SDK installed successfully!
Base URL: http://localhost:3000/rooms/TEST/v1

​
Environment Setup

​
Local Development

For local development, ensure you have a Gambiarra hub running: 
# Install Gambiarra CLI globally
bun install -g gambiarra

# Start a hub
gambiarra serve

​
Environment Variables

Optionally set the default hub URL via environment variable:
.env
GAMBIARRA_HUB_URL=http://localhost:3000
Then use it in your code: 
const gambiarra = createGambiarra({
  roomCode: "ABC123",
  hubUrl: process.env.GAMBIARRA_HUB_URL,
});
Bun automatically loads .env files. For Node.js, install dotenv or use Node 20.6+ with --env-file flag.

​
Runtime Support

The Gambiarra SDK works with multiple JavaScript runtimes:

Bun

Fully supported and recommended for best performance

Node.js

Requires Node.js 18+ with native fetch support

Edge Runtimes

Works with Vercel Edge, Cloudflare Workers, Deno
bun install gambiarra-sdk ai
Bun provides the fastest installation and runtime performance.

​
Node.js

node --version  # Ensure v18.0.0 or higher
npm install gambiarra-sdk ai
Node.js versions below 18 do not have native fetch support and will require a polyfill.

​
Deno

import { createGambiarra } from "npm:gambiarra-sdk";
import { generateText } from "npm:ai";

​
Troubleshooting

The AI SDK peer dependency is not installed. Run:
npm install ai
Ensure TypeScript 5.x is installed and strict: true is enabled in tsconfig.json.
Verify a Gambiarra hub is running:
curl http://localhost:3000/health
Expected response: {"status":"ok"}
Ensure your package.json has "type": "module" or use .mjs file extensions.

​
Next Steps

Usage Guide

Learn how to use the SDK with practical examples

Quickstart

Build your first Gambiarra application

Build docs developers (and LLMs) love

Get started for freeTalk to us