tieline

Static frontend↔backend contract-drift checker. Pact without writing a single contract test.

tieline reads the code you already wrote on both sides of an API boundary — the HTTP calls your frontend makes and the routes your backend exposes — and tells you where they disagree. No contract tests to author, no broker to run, no backend to boot. It finishes in well under a second and is built to run in CI as a gate.

Delete the LLM and a developer still installs it. tieline is a deterministic tool first; an agent reading its output is a bonus.

How it works

  frontend code                                  backend code
  (axios, rtk-query, …)                          (express, nestjs, openapi, …)
        │                                                │
   client adapter                                   server adapter
        │            normalize  ${id} :id {id} → {}       │
        └───────────────►  join on (METHOD, path)  ◄──────┘
                                   │
              ✅ matched   ❌ drift   ⚠️ unverifiable   🟡 dead

Both sides are reduced to a canonical (METHOD, path) and joined. The matcher is adapter-agnostic — any client adapter pairs with any server adapter, so the same engine checks a React app against Express, an Angular app against Spring, or anything against an OpenAPI spec.

tieline vs alternatives

These tools solve neighbouring problems — pick by what you have and what you want guaranteed.

They compose: tieline catches FE↔BE drift statically in every PR, tieline doctor keeps code↔spec honest, and a runtime tool like Pact or Schemathesis can guard the payload/behaviour layer underneath.

Quick start

Install (or run with npx):

npm install -g @nugehs/tieline
# or, from a clone:  git clone … && cd tieline && npm link

Generate a tieline.config.json — init sniffs the surrounding directories (cwd, its children, and its siblings) for known stacks and writes a ready-to-run config:

tieline init

  tieline · init

  scanning ~/code for repos…
  ✔ client: rtk-query     → web   (roots: src/redux/apis)
  ✔ server: nestjs        → api   (roots: src)

  📝 wrote tieline.config.json

It detects adapters from package.json deps (@reduxjs/toolkit, axios, @angular/core, @nestjs/core, express, fastify, next), requirements.txt / pyproject.toml (fastapi, flask), pom.xml / build.gradle (spring), and any OpenAPI doc as a fallback. Anything it can't detect is written as a placeholder for you to edit. The file is always overwritten, so re-run it whenever your layout changes.

Or write it by hand — at the root of (or above) your repos:

{
  "client": { "adapter": "rtk-query", "repo": "../web", "roots": ["src/redux/apis"], "basePath": "/api/v1" },
  "server": { "adapter": "nestjs",    "repo": "../api", "roots": ["src"], "globalPrefix": "api/v1" },
  "failOn": ["drift"]
}

Run it:

tieline check

  tieline · contract check

  ❌  2 drift  (FE calls a route the backend does not expose)
     GET    /users/{}
            getUser  ·  web/src/redux/apis/user-api.ts:42
            → did you mean "user/{}"?            # plural vs singular — a guaranteed 404
     PUT    /orders/{}
            updateOrder  ·  web/src/redux/apis/order-api.ts:88
            → path exists but as GET, not PUT    # method mismatch

  ✅ 274 matched   ❌ 2 drift   ⚠️  6 unverifiable   🟡 31 unused backend routes

check exits non-zero when any failOn bucket is non-empty — drop it into CI and the build fails the moment the two sides disagree.

Commands

tieline init       # auto-detect nearby repos and write tieline.config.json
tieline check      # FE↔BE drift; exits non-zero on drift (the CI gate)
tieline list       # the full resolved contract map (every endpoint + status)
tieline orphans    # backend routes no frontend call reaches
tieline doctor     # code↔spec drift (see below)

Supported stacks

Any client adapter pairs with any server adapter — the matcher never changes.

That covers MERN (rtk/axios ↔ express), MEAN (angular ↔ express), MEVN (axios ↔ express), Next full-stack, Python (fastapi/flask), and enterprise (angular ↔ spring) — plus openapi for any backend that emits a spec (Express+swagger-jsdoc, FastAPI, Spring springdoc, .NET Swashbuckle, …).

Notes:

• express walks the app.use() mount graph across require/import boundaries and nested routers; routers it can't reach are flagged, never dropped.
• next is file-system routing — app-router files export GET/POST/…; pages-router handlers serve any verb (matched as ALL).
• Runtime-built urls (e.g. `users/${id}?x=${q}`) are surfaced as unverifiable rather than guessed.

Configuration

tieline.config.json — repo paths resolve relative to the config file.

{
  "client": {
    "adapter": "rtk-query",      // rtk-query | axios-fetch | angular-http
    "repo": "../web",
    "roots": ["src/redux/apis"], // dirs to scan for call sites
    "basePath": "/api/v1"        // stripped from call sites before matching
  },
  "server": {
    "adapter": "nestjs",         // nestjs | express | fastify | next | fastapi | flask | spring | openapi
    "repo": "../api",
    "roots": ["src"],
    "globalPrefix": "api/v1",    // stripped from routes before matching
    "spec": "openapi.json"       // openapi adapter & `doctor` only — file path or URL
  },
  "ignore": ["internal/.*"],     // regexes on the normalized path
  "failOn": ["drift"]            // buckets that make `check` exit non-zero
}

Visual report

tieline check --html report.html writes one self-contained file (inline CSS/JS, no external assets) you can open in any browser or attach to a PR:

• a contract-flow diagram — frontend resources on the left, backend on the right, curved links coloured green (matched) / red (drift), with a ∅ no route node catching calls that land nowhere; hover a resource to highlight its links
• a health ring, summary cards, and live-filterable drift / unverifiable / unused tables

tieline doctor — does your code match your published docs?