Tinybird TypeScript SDK Guidelines

What Is This?

Overview

The Tinybird TypeScript SDK, distributed as the @tinybirdco/sdk package, provides a structured way to define and interact with Tinybird resources directly from TypeScript projects. It enables developers to declare datasources, pipes, and queries with complete type inference, reducing runtime errors and improving developer confidence when working with real-time data pipelines. Rather than relying on raw HTTP calls or loosely typed wrappers, the SDK enforces schema definitions at the TypeScript level.

This SDK bridges the gap between Tinybird's powerful data ingestion and query engine and the TypeScript ecosystem. Developers can define their data models once and benefit from autocomplete, compile-time validation, and consistent type propagation throughout their application. The result is a more maintainable codebase where data contracts between the frontend or backend and Tinybird are explicit and verifiable.

The package integrates naturally into modern TypeScript projects, including Node.js services, Next.js applications, and serverless functions. It supports both data ingestion workflows and query execution, making it suitable for a wide range of real-time analytics use cases.

Who Should Use This

• Backend engineers building data ingestion pipelines who need type-safe event publishing to Tinybird datasources
• Frontend developers querying Tinybird pipes from Next.js or similar frameworks who want typed API responses
• Full-stack engineers maintaining TypeScript monorepos who want consistent data contracts across services
• Data engineers prototyping Tinybird resources and wanting compile-time feedback during development
• Platform teams standardizing how multiple services interact with a shared Tinybird workspace
• DevOps and infrastructure engineers automating Tinybird resource management through typed configuration scripts

Why Use It?

Problems It Solves

• Eliminates untyped HTTP requests to Tinybird endpoints, which are prone to silent failures when field names or types change
• Removes the need to manually parse and validate query responses, since the SDK infers return types from pipe definitions
• Reduces integration bugs caused by mismatched schemas between the application layer and Tinybird datasources
• Simplifies onboarding for new team members by making data contracts self-documenting through TypeScript types
• Prevents accidental ingestion of malformed records by enforcing row shapes at the type level before sending data

Core Highlights

• Full TypeScript type inference for datasource schemas, pipe parameters, and query results
• Strongly typed append method for sending rows to datasources with schema validation
• Typed pipe query execution with parameter support and inferred response shapes
• Compatible with Node.js, edge runtimes, and browser environments
• Minimal configuration requiring only a Tinybird host and API token
• Supports both single-row and batch ingestion patterns
• Works alongside existing Tinybird CLI workflows without conflict

How to Use It?

Basic Usage

Install the package and initialize the client with your workspace credentials.

npm install @tinybirdco/sdk

import { createClient } from "@tinybirdco/sdk";

const tb = createClient({
  host: "https://api.tinybird.co",
  token: process.env.TINYBIRD_TOKEN,
});

Define a datasource schema and append rows with full type checking.

const eventsSchema = tb.datasource("analytics_events", {
  user_id: "String",
  event_name: "String",
  timestamp: "DateTime",
});

await eventsSchema.append({
  user_id: "u_123",
  event_name: "page_view",
  timestamp: new Date().toISOString(),
});

Specific Scenarios

Querying a pipe with typed parameters and results:

const topPages = tb.pipe("top_pages_api", {
  params: { date_from: "String", limit: "Int32" },
  schema: { page: "String", views: "Int64" },
});

const result = await topPages.query({ date_from: "2024-01-01", limit: 10 });
// result.data is typed as Array<{ page: string; views: number }>

Batch ingestion in a serverless function:

const rows = events.map((e) => ({ user_id: e.id, event_name: e.type, timestamp: e.ts }));
await eventsSchema.append(rows);

Real-World Examples

A Next.js API route can query a Tinybird pipe and return typed JSON to the client without manual casting. A Node.js worker processing webhook payloads can validate and forward structured events to a Tinybird datasource in a single typed call.

When to Use It?

Use Cases

• Publishing user behavior events from a web application to Tinybird in real time
• Querying aggregated analytics data from Tinybird pipes inside API routes
• Building internal dashboards that fetch typed metrics from Tinybird endpoints
• Automating datasource population from scheduled Node.js jobs
• Validating event schemas before ingestion in high-throughput pipelines
• Integrating Tinybird into TypeScript monorepos with shared type definitions
• Prototyping new Tinybird resources with immediate compile-time feedback

Important Notes

Requirements

• Node.js 18 or later, or a compatible edge runtime environment
• A valid Tinybird workspace with an API token that has appropriate read or write permissions
• TypeScript 4.7 or later to benefit from full type inference features