Split a TypeScript schema into multiple files

[lonix1]

I'm using v8 with TypeScript-based schemas.

The documentation states the ts approach is useful when:

model definitions must be split, composed, or reused across ordinary TypeScript modules or packages

It also shows an example single-file schema; here it is, but simplified:

import { defineContract, rel } from "@prisma/orm-postgres/contract-builder";

export default defineContract({}, ({ field, model }) => {

  const User = model("User", {
    fields: {
      id: field.int32().primaryKey(),
      name: field.text(),
    },
  });

  const Post = model("Post", {
    fields: {
      id: field.int32().primaryKey(),
      title: field.text(),
      userId: field.int32(),
    },
  });

  return {
    models: {
      User: User.relations({
        posts: rel.hasMany(Post, { by: "userId" }),
      }).sql({ table: "user" }),
      Post: Post.relations({
        user: rel.belongsTo(User, {
          from: "userId",
          to: "id",
        }),
      }),
    },
  };
});

I want to split that into separate files and compose them in the main contract file, for example:

prisma/
  contract.ts
  user.ts
  post.ts

I've struggled to get that to work, as there's no guidance for that scenario (other than stating it's possible), and the changes between versions makes it hard to find the correct syntax.

What is the official approach for this scenario?

Thanks!

[lonix1]

I don't think this is officially/properly supported despite the claim in the docs, so added it as a feature request here.

[amasen02]

It is fully supported, but the challenge most developers hit when splitting into separate files is circular module imports (user.ts importing post.ts, which imports user.ts to define reciprocal relations like hasMany and belongsTo).

In TypeScript, you can solve this cleanly by decoupling model field declarations from relation wiring.

Here are the two standard patterns:

---

Pattern 1: Factory Functions + Central Relation Wiring (Recommended)

In this pattern, each domain file defines its own fields independently without needing to import sibling models. The reciprocal relations are wired together in contract.ts where both model instances exist in scope.

prisma/user.ts

import type { Builder } from "@prisma/orm-postgres/contract-builder";

export function createUserModel({ field, model }: Builder) {
  return model("User", {
    fields: {
      id: field.int32().primaryKey(),
      name: field.text(),
    },
  });
}

export type UserModel = ReturnType<typeof createUserModel>;

prisma/post.ts

import type { Builder } from "@prisma/orm-postgres/contract-builder";

export function createPostModel({ field, model }: Builder) {
  return model("Post", {
    fields: {
      id: field.int32().primaryKey(),
      title: field.text(),
      userId: field.int32(),
    },
  });
}

export type PostModel = ReturnType<typeof createPostModel>;

prisma/contract.ts

import { defineContract, rel } from "@prisma/orm-postgres/contract-builder";
import { createUserModel } from "./user";
import { createPostModel } from "./post";

export default defineContract({}, (builder) => {
  // 1. Instantiate pure models (zero circular imports!)
  const User = createUserModel(builder);
  const Post = createPostModel(builder);

  // 2. Wire relations together at the contract boundary
  return {
    models: {
      User: User.relations({
        posts: rel.hasMany(Post, { by: "userId" }),
      }).sql({ table: "user" }),

      Post: Post.relations({
        user: rel.belongsTo(User, {
          from: "userId",
          to: "id",
        }),
      }),
    },
  };
});

---

Pattern 2: Domain-Colocated Relations via Parameter Injection

If you prefer to keep relation definitions colocated within each domain file (e.g. keeping posts: rel.hasMany(...) inside user.ts), inject the target model dependency dynamically instead of statically importing it:

prisma/user.ts

import type { Builder, Rel } from "@prisma/orm-postgres/contract-builder";
import type { PostModel } from "./post";

export function defineUser(builder: Builder) {
  const User = builder.model("User", {
    fields: {
      id: builder.field.int32().primaryKey(),
      name: builder.field.text(),
    },
  });

  return {
    raw: User,
    bindRelations: (Post: PostModel, rel: Rel) =>
      User.relations({
        posts: rel.hasMany(Post, { by: "userId" }),
      }).sql({ table: "user" }),
  };
}

prisma/contract.ts

import { defineContract, rel } from "@prisma/orm-postgres/contract-builder";
import { defineUser } from "./user";
import { definePost } from "./post";

export default defineContract({}, (builder) => {
  const user = defineUser(builder);
  const post = definePost(builder);

  return {
    models: {
      User: user.bindRelations(post.raw, rel),
      Post: post.bindRelations(user.raw, rel),
    },
  };
});

Why this works

• Zero runtime cycles: Because module-level import type is erased during compilation, circular import issues at bundle/runtime are completely avoided.
• Full TypeScript inference: You retain 100% type safety and IDE autocomplete across all fields and relation navigations.

[lonix1]

I can also consult AI, but was hoping for a human answer from someone with actual experience. Posting AI slop isn't helpful.

I already tried various approaches and they simply don't work. The linked issues show various non-working or non-ideal approaches. They are apparently currently working on this behaviour for a future RC.

[giaBaoJS]

Splitting works today on the published packages. The thing that blocks it is the module loader, not the contract builder.

Tested against prisma@8.0.0-rc.14, @prisma/orm-postgres@8.0.0-rc.10, Node 24.13.0, TypeScript 5.9.3.

1. The blocker is the file extension

prisma contract emit does not bundle your contract. It loads it with a bare dynamic import():

// prisma/orm @ main (1e8b6a6)
// packages/2-sql/2-authoring/contract-ts/src/config-types.ts:106  (typescriptContractFromPath)
const mod = await import(pathToFileURL(absolutePath).href);

So Node's own TypeScript support runs contract.ts, and Node's ESM resolver requires an explicit extension on relative specifiers. That is exactly the Cannot find module '.../prisma/models/user' imported from '.../prisma/contract.ts' you hit on rc.12; I reproduced it verbatim on rc.14, and it goes away with .ts:

import { userModel } from './models/user';      // ERR_MODULE_NOT_FOUND
import { userModel } from './models/user.ts';   // works

Add "allowImportingTsExtensions": true to your tsconfig so tsc accepts the same specifier.

(The CLI does also ship an esbuild-based loader at packages/1-framework/3-tooling/cli/src/load-ts-contract.ts, which would resolve extensionless imports. It is not the code path ormConfig({ contract: './prisma/contract.ts' }) takes.)

2. Why the field sugar vanishes when you move to module scope

field.text() / field.int() are not on the module-level field export. That export is three functions:

// packages/2-sql/2-authoring/contract-ts/src/contract-dsl.ts:2102
export const field = {
  column: columnField,
  generated: generatedField,
  namedType: namedTypeField,
};

Confirmed at runtime on rc.10: Object.keys(field) is ['column', 'generated', 'namedType'].

The sugar is composed per contract from the family pack plus the target pack plus your extensions, and only exists on the helpers object handed to the factory callback:

// packages/2-sql/2-authoring/contract-ts/src/composed-authoring-helpers.ts:141
readonly field: CoreFieldHelpers & FieldHelpersFromNamespace<
  ExtractFieldNamespaceFromPack<Family> &
  ExtractFieldNamespaceFromPack<Target> &
  MergeExtensionFieldNamespaces<Extensions>
>;

built at contract-builder.ts:488 via createComposedAuthoringHelpers. That is the whole reason your Approach 2 had to fall back to codecId strings, and there is no other mechanism: to keep the sugar in a split file you have to pass helpers into that file.

model and rel are different. composed-authoring-helpers.ts:303-304 puts the module-level exports on the helpers object unchanged, so helpers.rel === rel. Importing rel straight from the package inside a model file is fine.

3. Working example

Four files, relations colocated with each model, no any, full sugar, no runtime cycle.

prisma/helpers.ts

import type { defineContract } from '@prisma/orm-postgres/contract-builder';

export type Helpers = Parameters<NonNullable<Parameters<typeof defineContract>[1]>>[0];

prisma/models/user.ts

import { rel } from '@prisma/orm-postgres/contract-builder';
import type { Helpers } from '../helpers.ts';
import type { postModel } from './post.ts';

export function userModel({ field, model }: Helpers) {
  return model('User', {
    fields: { id: field.int().id(), name: field.text() },
  });
}

export function userRelations(
  User: ReturnType<typeof userModel>,
  Post: ReturnType<typeof postModel>,
) {
  return User.relations({
    posts: rel.hasMany(Post, { by: 'userId' }),
  }).sql({ table: 'user' });
}

prisma/models/post.ts

import { rel } from '@prisma/orm-postgres/contract-builder';
import type { Helpers } from '../helpers.ts';
import type { userModel } from './user.ts';

export function postModel({ field, model }: Helpers) {
  return model('Post', {
    fields: { id: field.int().id(), title: field.text(), userId: field.int() },
  });
}

export function postRelations(
  Post: ReturnType<typeof postModel>,
  User: ReturnType<typeof userModel>,
) {
  return Post.relations({
    user: rel.belongsTo(User, { from: 'userId', to: 'id' }),
  });
}

prisma/contract.ts

import { defineContract } from '@prisma/orm-postgres/contract-builder';
import { postModel, postRelations } from './models/post.ts';
import { userModel, userRelations } from './models/user.ts';

export default defineContract({}, (helpers) => {
  const User = userModel(helpers);
  const Post = postModel(helpers);
  return {
    models: {
      User: userRelations(User, Post),
      Post: postRelations(Post, User),
    },
  };
});

The user.ts <-> post.ts cycle is type-only on both sides, so it is erased and there is no cycle at runtime.

Measured results:

• tsc --noEmit with "strict": true: 0 errors.
• prisma contract emit: ok, storageHash 5954b3688bf47f30fd934a7769c1064f918101cd60d20b4b373417731c378dd9, byte-identical contract.json to the equivalent single-file contract.
• Emitted contract.d.ts carries the relations as posts: public_Post[] and user: public_User, so nothing degraded to any.

Counterfactual checks, so the above is not passing vacuously. Typo a helper name in user.ts and you get TS2339: Property 'txet' does not exist on type 'CoreFieldHelpers & FieldHelpersFromNamespace<...>'. Typo the relation key and you get Type '"userIdd"' is not assignable to type 'RelationFieldSelection<"id" | "title" | "userId">', which is Post's field union crossing the file boundary intact.

If you would rather name the helpers type explicitly than derive it, ComposedAuthoringHelpers is a real public export (packages/3-extensions/postgres/src/exports/contract-builder.ts), it just needs the pack generics:

import type sqlFamilyPack from '@prisma/orm-family-sql/family/pack';
import type { ComposedAuthoringHelpers } from '@prisma/orm-postgres/contract-builder';
import type postgresPack from '@prisma/orm-target-postgres/target/pack';

export type Helpers = ComposedAuthoringHelpers<typeof sqlFamilyPack, typeof postgresPack, undefined>;

Both compile identically. The Parameters<...> form needs no extra dependencies, which is why I used it above.

4. Two module-scope variants, and why I am not recommending them

rel.hasMany / hasOne / belongsTo / manyToMany do accept a lazy thunk, Token | LazyNamedModelToken<Token> (contract-dsl.ts:1953, 2005, 2027, 2051), and normalizeRelationModelSource stores it unevaluated (contract-dsl.ts:1714-1720). So you can define models at module scope with real circular imports and rel.hasMany(() => Post, ...).

It emitted the same storageHash for me, but it has two problems I measured:

• belongsTo breaks the laziness. It calls the thunk eagerly for a cross-space brand check at contract-dsl.ts:1976. In a genuine ESM cycle whether that hits the temporal dead zone depends on evaluation order. With import { Post } before import { User } in contract.ts it emitted fine; swapping only those two lines produced CONTRACT.SOURCE_LOAD_FAILED / Cannot access 'User' before initialization. Nothing else changed.
• tsc cannot infer through it: TS7022: 'User' implicitly has type 'any' because it does not have a type annotation and is referenced directly or indirectly in its own initializer, plus TS7024 on the thunks.

The string form, rel.belongsTo('User', { from: 'userId', to: 'id' }), drops the cross-file import entirely, typechecks, and emits the same contract, but the CLI warns on every emit:

[PN_CONTRACT_TYPED_FALLBACK_AVAILABLE] Contract relation "Post.user" uses rel.belongsTo('User', ...).
Use rel.belongsTo(User, ...) when the named model token is available in the same contract to keep
typed relation targets and model refs.

Both work. Neither is as good as passing the model tokens.

5. On the two answers above

@amasen02 is right on the substance: it is supported, and the fix is to inject the builder rather than have model files import each other. The posted code will not compile as written, though. Builder and Rel are not exported from @prisma/orm-postgres/contract-builder; on rc.10 the module exports are buildSqlContractFromDefinition, check, defineContract, enumType, field, member, model, nativeEnum, pg, policyAll, policyDelete, policyInsert, policySelect, policyUpdate, rel, rlsEnabled, role, and the helpers type is ComposedAuthoringHelpers<Family, Target, Extensions>, which takes three generic arguments. Pattern 2 also passes rel as a runtime argument while importing it as a type, and builder.field.int32() is not a helper the postgres pack contributes on rc.10 or rc.11.

@lonix1, your rc.12 emit failure was real and it is the extension rule in section 1, not a missing feature. The split itself works, including the reciprocal hasMany / belongsTo pair. What I think is genuinely missing is smaller than "official support": a one-name alias for the helpers type that does not need pack generics, and docs that show the injection shape, since the sugar provably cannot exist on the module-level field export.

One unrelated note: the docs snippet you quoted uses field.int32().primaryKey(). Neither exists on @prisma/orm-postgres 8.0.0-rc.10 or 8.0.0-rc.11; the postgres pack contributes field.int() and the builder method is .id(). I enumerated the helpers on both versions to check. That may be why the syntax felt like a moving target.

[lonix1]

More unuseful AI slop. You don't help anyone by posting it.

This is currently impossible, but they are actively working on it for the final release, as detailed in the linked issue.