Project contracts · Frontend/backend boundaries

Route contracts.

A route contract gives a Nift project one checked source of truth for named application/API paths. It is a concrete use of project contracts: Nift verifies that the named relationship exists and tracks its source, while the backend or deployment platform still owns what happens when a request arrives.

Declare a routes contract

// .nift/config.json
{
  "config": {
    "contracts": {
      "routes": ".nift/routes.json"
    }
  }
}

// .nift/routes.json
{
  "users": {
    "list": "/api/users",
    "details": "/api/users/{id}"
  },
  "auth": {
    "login": "/api/auth/login"
  }
}

Reference routes as ordinary values

const users = await fetch('$[routes.users.list]');

<a href="$[routes.auth.login]">Sign in</a>

If routes.users.list is removed from the declared contract, the build fails instead of silently generating a frontend that points at an undeclared route.

The contract is the declared relationship, not the server implementation.

Nift verifies that the frontend refers to a route the project declared. Express, Go, Lambda, Vercel Functions, Netlify Functions or another backend can still implement that route independently.

Why named routes help

Without a contract, frontend and backend code can carry unrelated strings that merely happen to match:

fetch('/api/users')

A named contract moves the project-level relationship into one explicit source. If the route changes to /v2/users, update the contract and rebuild the outputs that reference it.

Nift route contracts are not Vercel routing rules

The word route is overloaded in web development. Nift route contracts and Vercel routing rules are different concepts.

Nift route contract	Vercel routing rule
Build-time application relationship.	Deployment/runtime request handling.
Answers “what path does this named application route mean, and was it declared?”	Answers “what should Vercel do when this incoming request matches?”
Can be consumed by frontend templates regardless of hosting platform.	Can rewrite, redirect, set headers, serve static output or dispatch to platform functions.
Lives in project contract data.	Lives in Vercel deployment configuration/output primitives.

Nift route contract
users.list → /api/users
        ↓
frontend generates fetch('/api/users')
        ↓
Vercel / Netlify / Express / Go / another runtime
handles the request according to its own routing model

The models can complement each other. A future deployment adapter could validate or derive provider-specific configuration from project contracts where that remains simple and reliable, but Nift's application contract should not become Vercel-specific.

Routes can describe more than one backend technology

The route contract can remain stable while implementation changes. A project might move an endpoint from a conventional Node server to a serverless function without changing the Nift templates if the public route remains the same.

Keep the first contract small

For many projects, mapping names to path strings is enough. Do not add methods, request schemas, authentication rules or deployment behavior merely because they could theoretically live in the same JSON. Add richer guarantees only when the project has a concrete need and a simple way to validate them.

RelatedContract philosophy →