nitrogql logonitrogql

The #import syntax

The #import syntax is an extension to the GraphQL language that allows you to import fragments from other GraphQL documents. This syntax is similar to The Guild's #import extension for schema loading.

In nitrogql, fragments defined in operation documents are scoped within the operation document. This means that you cannot reuse fragments across operation documents. The #import syntax allows you to overcome this limitation.

💡 The #import syntax is not available in schema definition language (SDL) files. This is because unlike operation documents, SDL files are not scoped. All SDL files share the same, global scope.

Usage

The #import syntax is of the following form:

#import Fragment1, Fragment2 from "./path/to/file.graphql"

Above is an example of importing two fragments from path/to/file.graphql (relative to the current file). The fragments are then available for use in the current document. Of course, the imported document must define these fragments.

You can also import all fragments from a document by using the * wildcard:

#import * from "./path/to/file.graphql"

The above imports all fragments from path/to/file.graphql.

The #import syntax can be used in the top level of an operation document. If the syntax is used elsewhere, it will be a syntax error.


#import Fragment1 from "./path/to/file.graphql"
# ↑ This is valid

query {
  #import Fragment2 from "./path/to/file.graphql"
  # ↑ This is invalid!
  # ...
}

🎞️ Since # is also used for comments, failure to use the #import syntax correctly may result in it being treated as a comment instead.