Lighthouse

# Schema Organisation

As you add more and more types to your schema, it can grow quite large. Learn how to split your schema across multiple files and organise your types.

# Schema Imports

Suppose you created your schema files likes this:

graphql/
|-- schema.graphql
|-- user.graphql

Lighthouse reads your schema from a single entrypoint, in this case schema.graphql. You can import other schema files from there to split up your schema into multiple files.

type Query {
  user: User
}

#import user.graphql

Imports always begin on a separate line with #import, followed by the relative path to the imported file. The contents of user.graphql are pasted in the final schema.

type Query {
  user: User
}

type User {
  name: String!
}

The import statements are followed recursively, so it is easy to organize even the most complex of schemas.

You can also import multiple files using wildcard import syntax. For example, if you have your schema files like this:

graphql/
  |-- schema.graphql
  |-- post/
    |-- post.graphql
    |-- category.graphql

Instead of naming each individual file, you can import multiple files that matches a pattern. It will be loaded using PHP's glob function (opens new window).

#import post/*.graphql

# Type Extensions

Suppose you want to add a new type Post to your schema. Create a new file post.graphql with the schema for that type.

type Post {
  title: String
  author: User @belongsTo
}

Then you add an import to your main schema file.

#import post.graphql

type Query {
  me: User @auth
}

Attention: A valid Query type definition with at least one field must be present in the root schema. This is because extend type needs the original type to get merged into.

You can provide an empty Query type (without curly braces) in the root schema:

type Query

#import post.graphql

The same applies for mutations: if you want to use them, you can define an empty Mutation type (without curly braces) within your root schema:

type Query

type Mutation

#import post.graphql

Now you want to add a few queries to actually fetch posts. You could add them to the main Query type in your main file, but that spreads the definition apart, and could also grow quite large over time.

Another way would be to extend the Query type and colocate the type definition with its Queries in post.graphql.

type Post {
  title: String
  author: User @belongsTo
}

extend type Query {
  posts: [Post!]! @paginate
}

The fields in the extend type definition are merged with those of the original type.

← Relay →