Quick start: Coding agents

Use coding agents to scaffold, refine, and test Tinybird projects with Tinybird agent skills. The prompt below is optimized for setting up the TypeScript SDK.

Looking for other ways to start? See Quick starts.

Before you begin

To get started, you need the following:

  • A coding agent like Cursor, Claude Code, Amp, or Open Code

Install Tinybird agent skills

Install the Tinybird skills so your agent understands the project structure and the workflow you want.

npx skills add tinybirdco/tinybird-agent-skills

The Tinybird agent skills cover both the CLI and TypeScript SDK workflows.

Ask your agent to set up the SDK

Use the following prompt with your agent:

I'm integrating Tinybird Forward into my project. Help me set up the Typescript SDK.

Prerequisites
- Node.js 20 LTS (or newer, non-EOL)
- TypeScript >= 4.9
- Create a branch from main if not already in one

Step 1: Install the Tinybird SDK so we can run commands from anywhere

Ask for the preferred package manager. For example, if the user wants to use pnpm, run:
pnpm add -g @tinybirdco/sdk@latest

Step 2: Install the Tinybird SDK locally in the project

Install the SDK locally in the project using the package manager configured in the repository.

Step 3: Create a tinybird.config.mjs file in the root of the repository
/** @type {import("@tinybirdco/sdk").TinybirdConfig} */
const tinybirdConfig = {
  include: ["/lib/tinybird.ts"],
  token: process.env.TINYBIRD_TOKEN,
  baseUrl: process.env.TINYBIRD_URL,
  devMode: "branch", // or "local" if you want to run the project locally (Tinybird Local required)
};

export default tinybirdConfig;

Step 4: Create .env.local file
TINYBIRD_TOKEN=xxxxxxx
TINYBIRD_URL=xxxxxxx

Step 5: Create lib/tinybird.ts
/**
 * Tinybird Definitions
 *
 * Define your datasources, endpoints, and client here.
 */

import {
  defineDatasource,
  defineEndpoint,
  Tinybird,
  node,
  t,
  p,
  engine,
  type InferRow,
  type InferParams,
  type InferOutputRow,
} from "@tinybirdco/sdk";

// ============================================================================
// Datasources
// ============================================================================

/**
 * Page views datasource - tracks page view events
 */
export const pageViews = defineDatasource("page_views", {
  description: "Page view tracking data",
  schema: {
    timestamp: t.dateTime(),
    session_id: t.string(),
    pathname: t.string(),
    referrer: t.string().nullable(),
  },
  engine: engine.mergeTree({
    sortingKey: ["pathname", "timestamp"],
  }),
});

export type PageViewsRow = InferRow<typeof pageViews>;

// ============================================================================
// Endpoints
// ============================================================================

/**
 * Top pages endpoint - get the most visited pages
 */
export const topPages = defineEndpoint("top_pages", {
  description: "Get the most visited pages",
  params: {
    start_date: p.dateTime().describe("Start of date range"),
    end_date: p.dateTime().describe("End of date range"),
    limit: p.int32().optional(10).describe("Number of results"),
  },
  nodes: [
    node({
      name: "aggregated",
      sql: `
        SELECT
          pathname,
          count() AS views
        FROM page_views
        WHERE timestamp >= {{DateTime(start_date)}}
          AND timestamp <= {{DateTime(end_date)}}
        GROUP BY pathname
        ORDER BY views DESC
        LIMIT {{Int32(limit, 10)}}
      `,
    }),
  ],
  output: {
    pathname: t.string(),
    views: t.uint64(),
  },
});

export type TopPagesParams = InferParams<typeof topPages>;
export type TopPagesOutput = InferOutputRow<typeof topPages>;

// ============================================================================
// Client
// ============================================================================

export const tinybird = new Tinybird({
  datasources: { pageViews },
  pipes: { topPages },
});

Step 6: Setup is completed.

Ask the user to replace the TINYBIRD_* environment variables with the actual values from the quickstart and show the next steps to run:

# Build project
tinybird build

// Ingest data into the data source
await tinybird.pageViews.ingest({
  timestamp: new Date(),
  pathname: '/',
  session_id: '1234567890',
  country: 'US',
});

// Fetch the endpoint data
const result = await tinybird.topPages({
  start_date: new Date('2024-01-01'),
  end_date: new Date('2024-01-02'),
  limit: 10,
});

If some issue appears, check the README.md in the @tinybirdco/sdk repository for more information: https://github.com/tinybirdco/tinybird-sdk-typescript

Use the tinybird CLI to sync and deploy resources once the agent finishes.

Ask your agent to set up the Tinybird CLI workflow

Use the following prompt with your agent if you prefer datafiles and the Tinybird CLI:

I'm integrating Tinybird Forward into my project. Help me set up the Tinybird CLI workflow using datafiles.

Prerequisites
- Check if the folder has a .git. If not, ask user about where to host the project or if you should create the git init in current folder
- Create a branch from main if not already in one

Step 1: Install the Tinybird CLI

Run the official install script:
    curl https://tinybird.co | sh

On Windows, run:
    powershell -ExecutionPolicy ByPass -c "irm https://tinybird.co | iex"

Step 2: Authenticate

Run:
    tb login

Step 3: Create a data source

Use the NYC taxi dataset to create a datasource:
    tb datasource create --url https://tbrd.co/taxi_data.parquet --name trips

Step 4: Create sample fixtures

Run:
    tb mock trips

Step 5: Create an endpoint

Use:
    tb create --prompt "Create an endpoint that returns top pickup zones by tip amount."

Step 6: Build or develop

Show the next steps:
    tb build
    tb dev

Step 7: Check if data can be inserted an queried

Step 8: Propose deploying to Tinybird Cloud Workspace

If some issue appears, check the CLI reference: https://www.tinybird.co/docs/forward/dev-reference/commands

Next steps

Updated