What's the difference between Apollo Server's gql tag and a schema.gql file?

Question

The Apollo Server documentation presents only one way to define your GraphQL schema typeDefs, which is by using the gql tag. However, I've seen an alternative used where a schema.gql file is used instead.

Is one of these methods out of date?

Are there any advantages or disadvantages to using one method or the other?

Why don't the Apollo Server docs mention the .gql file type even though it's supported?

Answer 1

ApolloServer uses makeExecutableSchema from graphql-tools under the hood to actually generate the schema used by the service from the type definitions and resolver map you provide. The typeDefs you pass to makeExecutableSchema can be a parsed DocumentNode object (which is what the gql tag produces), or they can be a string, in which case they will be parsed for you. You can also pass in an array of either one.

If you have your type definitions inside one or more .gql files (or .graphql, or whatever), you're typically just using something like fs.read to get the file contents as strings and using that as your typeDefs parameter. This is technically fine and will work just as well as using already parsed DocumentNode objects.

The only issue is that, unlike graphql-tools, apollo-server explicitly does not support this approach. This is reflected in the TypeScript definitions for the module. While using plain strings as typeDefs works for now, it's possible that doing so may result in some unexpected behavior in the future, so do so with caution.

Outside of the above, there's a practical reason to use separate files for your schema -- it's easier to take advantage of syntax highlighting and code-completion since there are editor plugins that support these files. It's also note pointing out that if you happen to transpile your code with babel, it's also possible to take advantage of something like babel-plugin-import-graphql to import your files as parsed DocumentNodes.