Builds your TypeScript resources and pushes them to a Tinybird branch (not main). This is a one-time operation without file watching.
Syntax Basic Usage Build to Branch
Preview Without Pushing
Local Tinybird
How It Works
Reads configuration from tinybird.config.json
Bundles TypeScript files from include paths
Validates all resource definitions
Creates or reuses Tinybird branch
Pushes resources to branch using /v1/build API
Reports changes (created, modified, deleted)
Output Example Building resources... ✓ Found 3 datasources, 5 pipes Pushing to branch: feature/new-endpoint ✓ Branch created ✓ Dashboard: https://ui.tinybird.co/workspace/branch/feature-new-endpoint Deployed in 1.2s: Datasources: • Created: user_events • Changed: page_views • Unchanged: sessions Pipes: • Created: user_funnel • Changed: top_pages • Unchanged: analytics, dashboard, metrics
Options --dry-runBuild resources without pushing to Tinybird:
Building resources... ✓ Found 3 datasources, 5 pipes Dry run - no changes pushed to Tinybird
Useful for:
Validating TypeScript definitions
Testing configuration changes
CI validation without side effects
--localBuild to local Tinybird container:
Requires Docker:
docker run -d -p 7181:7181 --name tinybird-local tinybirdco/tinybird-local:latest
--branchExplicitly use Tinybird cloud branches (default):
Branch Management Automatic Branch Creation Build automatically creates branches from your git branch:
# On feature branch git checkout -b feature/user-analytics tinybird build
✓ Branch created: feature/user-analytics ✓ Dashboard: https://ui.tinybird.co/workspace/branch/feature-user-analytics
Reusing Existing Branches Subsequent builds reuse the same branch:
# Second build on same branch tinybird build
✓ Using existing branch: feature/user-analytics
Branch Naming Git branch names are sanitized for Tinybird:
feature/user-analytics → feature-user-analyticsfix/bug-123 → fix-bug-123update/deps → update-deps
Main Branch Protection Build is blocked on main branch to prevent accidental production deployments.
# On main branch tinybird build
Cannot deploy to main workspace with 'build' command. Use 'tinybird deploy' to deploy to production, or switch to a feature branch.
To deploy to production:
Build Process 1. Resource Discovery Finds all resources in include paths:
{ "include" : [ "src/tinybird.ts" , "tinybird/**/*.datasource" , "tinybird/**/*.pipe" ] }
Supports:
TypeScript files with define* functions
Legacy .datasource files
Legacy .pipe files
Glob patterns
2. Validation Validates before pushing:
// Invalid: missing required fields export const invalid = defineDatasource ( "events" , { schema: { timestamp: t . dateTime () }, // Error: missing engine });
Build failed: Datasource 'events' missing required field: engine
3. Dependency Resolution Resolves dependencies automatically:
// Connection defined first export const kafka = defineKafkaConnection ( "kafka" , { ... }); // Datasource references connection export const events = defineDatasource ( "events" , { kafka: { connection: kafka }, ... });
Resources are pushed in correct order:
Connections
Datasources
Pipes
4. Incremental Updates Only changed resources are pushed:
Deployed: Datasources: 3 unchanged Pipes: 1 changed, 4 unchanged
Local Mode Setup Start local Tinybird container:
docker run -d -p 7181:7181 \ --name tinybird-local \ tinybirdco/tinybird-local:latest
Build to Local ✓ Local workspace ready: feature-user-analytics ✓ Dashboard: http://localhost:7181/feature-user-analytics Deployed in 0.3s: Datasources: 2 created Pipes: 3 created
Workspace per Branch Local mode creates workspace per git branch:
main → Uses authenticated workspace namefeature/analytics → feature-analyticsfix/bug → fix-bug
Isolated workspaces for each branch.
CI/CD Integration GitHub Actions .github/workflows/tinybird-ci.yaml
name : Tinybird CI on : pull_request : env : TINYBIRD_TOKEN : ${{ secrets.TINYBIRD_TOKEN }} jobs : build : runs-on : ubuntu-latest steps : - uses : actions/checkout@v4 - uses : actions/setup-node@v4 - run : npm install - run : npx tinybird build
GitLab CI tinybird_build : stage : test script : - npm install - npx tinybird build variables : TINYBIRD_TOKEN : $TINYBIRD_TOKEN
Examples Feature Branch Development # Create feature branch git checkout -b feature/new-datasource # Add new datasource edit src/tinybird.ts # Build to branch tinybird build # View in dashboard open https://ui.tinybird.co/workspace/branch/feature-new-datasource
Validate Before Commit # Dry run to validate tinybird build --dry-run # If valid, commit git commit -m "Add user events datasource"
Local Testing # Test against local Tinybird tinybird build --local # Verify in local dashboard open http://localhost:7181
Build Output Success ✓ Deployed in 1.2s: Datasources: 1 created, 1 changed, 1 unchanged Pipes: 2 created, 3 unchanged Connections: 1 created
Errors ✗ Build failed: Datasource 'events' validation error: Invalid engine configuration: sortingKey is required at src/tinybird.ts:15:30
Warnings ⚠ Warnings: Pipe 'top_pages' schema may not match query output Consider adding explicit output types
Build Time Typical build times:
Small project (1-5 resources): < 1s
Medium project (5-20 resources): 1-2s
Large project (20+ resources): 2-5s
Caching Branch tokens are cached to avoid API calls:
~ /.tinybird/branches.json
First build: slower (creates branch)
Subsequent builds: faster (reuses cached token)
Troubleshooting Build Timeout Error: Build timed out after 30s
Large builds may timeout. Contact support for limits.
Token Invalid Run tinybird login to refresh credentials.
Branch Creation Failed Error: Failed to create branch: feature-analytics
Check workspace limits. Delete unused branches:
tinybird branch delete old-feature
dev : Build with file watchingdeploy : Deploy to productionbranch : Manage branches
For continuous development, use tinybird dev instead of repeated build commands.