Getting started

Tango is a set of TypeScript packages for building data-heavy web applications with a workflow inspired by Django and Django REST Framework.

Tango lives inside a host runtime such as Express or Next.js and gives you a consistent way to define models, configure environments, query data, manage migrations, expose API endpoints, and test the result.

Package layers

Most applications start with these packages:

@danceroutine/tango-config for tango.config.ts, environment profiles, and runtime config loading
@danceroutine/tango-schema for model definitions and metadata
@danceroutine/tango-orm for Model.objects, QuerySet, and database adapters
@danceroutine/tango-migrations for schema diffing, migration generation, and migration execution
@danceroutine/tango-resources for APIView, generic CRUD views, ModelViewSet, filtering, and pagination
an adapter package such as @danceroutine/tango-adapters-express or @danceroutine/tango-adapters-next

You will also see @danceroutine/tango-openapi for machine-readable API documents, @danceroutine/tango-testing for test helpers, and @danceroutine/tango-cli for the unified tango command-line workflow.

The basic workflow

Most Tango applications follow the same order:

Define tango.config.ts so the application and the CLI share the same database and migration settings.
Define a model with Zod and Tango metadata.
Query or mutate that model through Model.objects.
Generate or write migrations so the database matches the model metadata.
Run the migration workflow through the tango CLI.
Expose the model through a view class or viewset.
Register the view class with an adapter for your host framework.

The examples in this repository follow that flow, which makes them useful as both tutorials and reference implementations.

Read the docs the same way Django expects you to

The official Django documentation teaches through four document types: tutorial, topic guide, how-to guide, and reference. Tango uses the same split because each document type answers a different question well.

Tutorials answer: "How do I build something real?"
Topic guides answer: "How does this part work and why is it designed this way?"
How-to guides answer: "How do I complete this task in my project?"
Reference answers: "What does the API do exactly?"

If you want the background for that structure, compare:

Prerequisites

Node.js 22 or newer
pnpm 9 or newer
Docker if you want to run the PostgreSQL integration tests

If you are working from a local clone of Tango, these commands should all succeed:

bash

pnpm install
pnpm typecheck
pnpm test
pnpm test:integration:all

A practical first exercise

The fastest way to understand Tango is to make one small change across the whole stack.

Use the Express blog example and do this:

Run the example application.
Add a field to PostModel.
Generate a migration for the example.
Apply the migration with tango migrate.
Update the resource code if needed.
Confirm the field shows up in the API response.

That exercise forces you to touch the same boundaries you will use in a real project.

Common misunderstandings

Tango enhances host frameworks such as Express and Next.js while those frameworks continue to own routing and request lifecycle behavior.
Model.objects is the default application-facing data access path.
A migration is not optional once model metadata changes.
tango.config.ts is the normal place to define database and migration settings for an application.
Pagination should use explicit ordering. The examples use createdAt or id to keep result order stable.

Getting started ​

Package layers ​

The basic workflow ​

Read the docs the same way Django expects you to ​

Suggested reading order ​

Prerequisites ​

A practical first exercise ​

Common misunderstandings ​

Related pages ​