Where should ts-rest contract and client live in a custom-layered FSD project?

[bykim-metis]

Context

I'm using FSD with a custom layer stack in a Next.js App Router project that also uses ts-rest for end-to-end type-safe API contracts. My current layer order (top to bottom) is:

app
api       ← custom layer (ts-rest contract + Route Handler implementations)
pages
widgets
features
entities
shared

The problem

I have three related issues that create a circular dependency:

1. Contract references schemas from multiple layers

The ts-rest contract (api/contract.ts) needs zod schemas. These schemas naturally live in entities/, but occasionally I find myself importing schemas defined in pages/ as well — which is an upward import violation:

// api/contract.ts
import { PostSchema } from 'entities/post'   // ✅ downward, fine
import { SomeSchema } from 'pages/some-page' // ❌ upward violation

2. The fetch client is used by lower layers

The ts-rest fetch client (initQueryClient) is initialized in api/client.ts and imports the contract from the same layer. But features and pages also need this client to make requests — which means they are importing from a layer above them:

// features/post/api/use-posts.query.ts
import { client } from 'api/client' // ❌ upward import from features → api

3. The contract is a shared resource that doesn't fit cleanly into any layer

The contract is simultaneously:

• Required by the server (Route Handlers in app/api/)
• Required by the client (fetch client used in features and pages)
• Dependent on zod schemas from entities

This makes it impossible to place the contract in a single layer without either violating import direction rules or forcing all schemas into an inconvenient location.

What I've considered

Option A: Move contract + client to shared/api

This aligns with the official docs (v2.1 release notes mention that "API calls are now explicitly allowed in Shared"). The contract would import zod schemas from entities, which is also in shared or co-located.

shared/
  api/
    contract.ts   ← initContract()
    client.ts     ← initQueryClient()
    schemas/
      post.schema.ts

But this requires moving domain-specific zod schemas into shared, which feels wrong semantically — they belong to a business domain.

Option B: Move the entire api layer below entities

Reorder the layer stack so api sits just above shared:

app
pages
widgets
features
entities
api       ← contract + client here
shared

This makes features → api imports valid (downward). But the contract still needs to import from entities for zod schemas, which would now be an upward import.

Option C: Treat contract as outside the FSD layer system

Place the contract in a top-level contract/ folder that is not part of the FSD hierarchy, and alias it as @contract in tsconfig paths. Any layer can import from it without violating layer rules.

src/
  contract/     ← outside FSD, aliased as @contract
    index.ts
  app/
  api/
  pages/
  ...

Question

What is the recommended FSD approach for placing a shared API contract (like ts-rest or tRPC router) that:

1. Must be imported by both server-side handlers and client-side fetch code
2. Depends on domain-specific zod schemas from entities
3. Is used as a fetch client in features and pages

Is Option A (contract in shared/api) the intended solution, even if it means moving domain schemas to shared? Or is treating the contract as an external module (Option C) more aligned with FSD principles?

Any guidance from the core team would be very appreciated!

[Solant]

Hey

Option A is indeed the preferred way of handling API requests (as per documentation). The issue you are getting with zod schemas is related to the fact that CRUD operation code is leaking outside shared/api into entities layer https://fsd.how/docs/guides/issues/excessive-entities/#3-exclude-crud-operations-from-entities

But this requires moving domain-specific zod schemas into shared, which feels wrong semantically — they belong to a business domain.

This is, in fact, not true. The frontend application has no control over the type or validation rules for the schema. This schema and its respective types describe the payload types, not domain logic. This follows the same pattern of DDD and clean architecture, where controller/adapter validations and domain logic are separated.

So I would suggest you move schemas and validations to shared/api and not treat it as a business logic but as part of the API. You can still have pure domain validation rules in entities alongside the validations in shared/api.

I don't know details of your project, but there are 2 options for server-client typesafety: you can either create a private package in your monorepo that exposes those types (and schemas) to both client and server, or you can follow a pattern of having suffixed public API files like index.server.ts. The second pattern is fully compatible with FSD and Steiger.