Split Convex Schema by Feature

[trim ocean]

How can I have separate schema declarations by feature and merge them all in schema.ts?

[coral relic]

Hi @trim ocean. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

---

You can split your Convex schema by feature by defining the schema fields for each feature in separate files, then importing and merging them in your main schema.ts file. This approach is supported and commonly used in Convex projects to keep codebases organized as they grow.

Example approach:

1. Define feature schemas in separate files:

For example, in convex/users/schema.ts:

// convex/users/schema.ts
import { v } from "convex/values";
import { defineTable } from "convex/server";

export const usersTable = {
  users: defineTable({
    name: v.string(),
    email: v.string(),
  }),
};

And in convex/posts/schema.ts:

// convex/posts/schema.ts
import { v } from "convex/values";
import { defineTable } from "convex/server";

export const postsTable = {
  posts: defineTable({
    title: v.string(),
    content: v.string(),
    authorId: v.id("users"),
  }),
};

2. Merge and export in convex/schema.ts:

// convex/schema.ts
import { defineSchema } from "convex/server";
import { usersTable } from "./users/schema";
import { postsTable } from "./posts/schema";

export default defineSchema({
  ...usersTable,
  ...postsTable,
});

This pattern allows you to keep each feature's schema isolated and maintainable, then combine them in a single schema for Convex to use.

This approach is referenced in Convex documentation and community discussions, where splitting schema definitions and merging them in schema.ts is a recommended practice for larger codebases Types and Validators: A Convex Cookbook.

If you need to add indexes or further customize tables, you can do so in the feature schema files before merging.

Note: Always ensure that table names are unique across your features to avoid conflicts when merging.

This modular approach is widely used and helps keep your Convex project organized as it scales Argument Validation without Repetition.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@trim ocean Kapa.ai is still learning and improving, please let me know how I did by reacting below.

[trim ocean]

@coral relic What if i have more than one table per feature that I want to merge

[coral relic]

Let me check the knowledge base for you again. One moment! :books:

---

If you have more than one table per feature, you can still use the same approach: export an object containing all the tables for that feature from the feature's schema file, and then merge these objects in your main schema.ts.

For example, in a feature schema file you might have:

// convex/featureA/schema.ts
import { defineTable } from "convex/server";
import { v } from "convex/values";

export const featureATables = {
  tableOne: defineTable({
    fieldA: v.string(),
  }),
  tableTwo: defineTable({
    fieldB: v.number(),
  }),
};

Then, in your main schema.ts:

// convex/schema.ts
import { defineSchema } from "convex/server";
import { featureATables } from "./featureA/schema";
import { featureBTables } from "./featureB/schema";

export default defineSchema({
  ...featureATables,
  ...featureBTables,
});

This pattern is supported and recommended in Convex documentation and community discussions for organizing larger codebases, as it allows you to keep related tables grouped by feature and then merge them into a single schema object using object spread syntax. Just ensure that table names are unique across all features to avoid conflicts when merging Types and Validators: A Convex Cookbook.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: