Join us for GraphQL Summit, October 10-12 in San Diego. Super Early Bird registration ends soon!
Docs
Try Apollo Studio

Codegen configuration


The Apollo iOS Code Generation Engine is flexible and can be configured for different behaviors.

The configuration options for code generation are represented by the ApolloCodegenConfiguration struct.

When using the Codegen CLI, your configuration is represented by the apollo-codegen-configuration.json JSON file created by the CLI's init command.

When running code generation in your own Swift code, the configuration options are represented by the ApolloCodegenConfiguration struct.

Most of the configuration properties have defaults that provide a good starting point.

There are a number of base configuration properties, each representing a specific characteristic of the codegen engine:

Property NameDescription
schemaNamespaceNamespace used to scope the generated schema types.
inputSearch patterns that will be used to locate the schema and operation definition files.
outputLocation and structure of the generated files and modules.
optionsRules and options to customize the generated code.
experimentalFeaturesUsed to enable experimental features.
Note: These features could change at any time and are not guaranteed to always be available.
schemaDownloadConfigurationConfiguration to fetch a GraphQL schema before generation.

Schema namespace

schemaNamespace: String

This option defines the name of your schema module or namespace.

Along with your operation definitions, Apollo iOS generates a set of metadata objects that represent the types in your schema. All of these object are grouped within a namespace with the provided name.

  • If you are embedding your generated schema types within another target, this will be the name of a caseless namespace enum.

  • If you are including your schema types as a stand-alone target that can be imported by your other project targets, this will be the name of that target.

You can configure how you would like to include your schema types in your project using the output.schemaTypes.moduleType option.

File input

input: FileInput

The code generation engine requires a GraphQL schema and at least one operation to be able to generate Swift code. Read the introductory section on GraphQL source files for more information.

The properties to configure input are:

Property NameDescription
schemaSearchPathsAn array of path matching pattern strings used to find GraphQL schema files. Schema extension files can be included in these search paths.

Note: JSON format schema files must have the .json file extension.
operationSearchPathsAn array of path matching pattern strings used to find GraphQL operation files.
CLI Configuration JSON
"input": {
"schemaSearchPaths": [
"**/*.graphqls"
],
"operationSearchPaths": [
"**/*.graphql"
]
}
Swift Codegen Setup
let configuration = ApolloCodegenConfiguration(
// Other properties not shown
input: ApolloCodegenConfiguration.FileInput(
schemaSearchPaths: ["**/*.graphqls"],
operationSearchPaths: ["**/*.graphql"]
),
)

Search Path Patterns

Each file input property is a [String] search path array. Search paths can be used to search your project directory for files matching a glob pattern. You can use absolute or relative paths in path matching patterns. Relative paths will be based off the current working directory.

Each path matching pattern can include the following characters:

  • * matches everything but the directory separator (shallow), eg: *.graphql
  • ? matches any single character, eg: file-?.graphql
  • ** matches all subdirectories (deep), eg: **/*.graphql
  • ! excludes any match only if the pattern starts with a ! character, eg: !file.graphql

File output

output: FileOutput

The FileOutput options are used to configure which files are generated and their output locations.

The properties to configure output are:

Property NameDescription
schemaTypesLocation and structure of the generated schema types files.
operationsLocation and structure of the generated operation files such as queries, mutations, subscriptions, and fragments.
testMocksLocation and structure of the test mock operation object files.

If .none, test mocks will not be generated.
operationIdentifiersPathAn absolute location to an operation identifier JSON map file. This can be used in conjunction with APQs.
CLI Configuration JSON
"output": {
"schemaTypes": {
"moduleType": {
"swiftPackageManager": {}
},
"path": "./generated/schema/"
},
"operations": {
"inSchemaModule": {}
},
"testMocks": {
"none": {}
},
"operationIdentifiersPath": "./generated/"
}
Swift Codegen Setup
let configuration = ApolloCodegenConfiguration(
// Other properties not shown
output: ApolloCodegenConfiguration.FileOutput(
schemaTypes: ApolloCodegenConfiguration.SchemaTypesFileOutput(
path: "./generated/schema/",
moduleType: .swiftPackageManager
)
operations: .inSchemaModule,
testMocks: .none,
operationIdentifiersPath: "./generated/"
)
)

Schema types

output.schemaTypes: SchemaTypesFileOutput

Schema types are common to all generated operation models and are required for the generated Swift code to compile.

The properties to configure output.schemaTypes are:

Property NameDescription
pathA file path where the generated schema types should be output.

Relative to your project root
moduleTypeHow generated schema types will be linked to your project.

Module type

output.schemaTypes.moduleType: ModuleType

Use the ModuleType value to configure how your schema types are linked to your project. The Code Generation Engine uses this to determine the structure of the generated files, including import statements.

For single target applications, embeddedInTarget(name:) can be used.

For multi-module projects, it is recommended that the schema types be created in a separate module to help with separation of concerns. If using Swift Package Manager, the swiftPackageManager option can help automate module creation.

Note: This option must be set correctly for your project structure or generated code will fail to compile.

The possible values for moduleType are:

ValueDescription
embeddedInTarget(name:)Indicates that you would like to include the generated module directly in your application target.
swiftPackageManagerCreates a schema module as an SPM package that can be included in your project.
otherIndicates that you would like to manually define a schema module using a third party package manager (such as Cocoapods).

Embedded in target

ModuleType.embeddedInTarget(name: String)

This option indicates that you would like to include the generated module directly in your application target.

The name parameter must specify the name of the target the schema types will be included in. This will be used to generate import statements for generated operations.

No module will be created for the schema types. Instead, generated schema types will be enclosed in a caseless namespace enum.

When creating a single target application, this option allows you to include Apollo iOS's generated module directly in your application target.

Note: When using this module type, you are responsible for ensuring the generated files are linked to your application target.

CLI Configuration JSON
"output": {
"schemaTypes": {
"moduleType": {
"embeddedInTarget": {
"name": "MyApplicationTarget"
}
},
"path": "./generated/schema/"
}
}
Swift Codegen Setup
let configuration = ApolloCodegenConfiguration(
// Other properties not shown
output: ApolloCodegenConfiguration.FileOutput(
schemaTypes: ApolloCodegenConfiguration.SchemaTypesFileOutput(
path: "./generated/schema/",
moduleType: .embeddedInTarget(name: "MyApplicationTarget")
)
...
)
)

Swift package manager

ModuleType.swiftPackageManager

This option automates the creation of an SPM package for your schema types. This generates a Package.swift file that is suitable for linking the generated schema types files to your project using Swift Package Manager.

The schema types will be contained in a stand-alone module with the schemaNamespace provided. Other targets in your application that contain generated operation models must have a dependency on this target.

For multi-module projects using Swift Package Manager, this is the recommended configuration option.

Including schema types in your own Package.swift file:

This option generates an SPM package with its own Package.swift file. This is ideal if you want to share your schema module across multiple projects or using Xcode's Package Dependency GUI.

If you would like to include your schema module as a target in your own Package.swift file, you can define a target with the name and path of the generated files in your Package.swift file.

CLI Configuration JSON
"output": {
"schemaTypes": {
"moduleType": {
"swiftPackageManager": {}
},
"path": "./generated/schema/"
}
}
Swift Codegen Setup
let configuration = ApolloCodegenConfiguration(
// Other properties not shown
output: ApolloCodegenConfiguration.FileOutput(
schemaTypes: ApolloCodegenConfiguration.SchemaTypesFileOutput(
path: "./generated/schema/",
moduleType: .swiftPackageManager
)
...
)
)

Other schema module types

ModuleType.other

This option should be used when you would like to define a schema module using another package management system, such as CocoaPods, or manually creating Xcode targets.

ModuleType.other indicates to the Code Generation Engine that your schema types will be contained in their own target, rather than embedded in your application target. This affects the import statements in your generated operation definition files.

Using this option, you are required to create a target for your schema module using your preferred package manager.

Note: The name of the target for your schema module must be the schemaNamespace provided in your configuration, as this will be used in the import statements of generated operation files.

CLI Configuration JSON
"output": {
"schemaTypes": {
"moduleType": {
"other": {}
},
"path": "./generated/schema/"
}
}
Swift Codegen Setup
let configuration = ApolloCodegenConfiguration(
// Other properties not shown
output: ApolloCodegenConfiguration.FileOutput(
schemaTypes: ApolloCodegenConfiguration.SchemaTypesFileOutput(
path: "./generated/schema/",
moduleType: .other
)
...
)
)

Operations

Operation files are generated from all the GraphQL operation definitions matched by your configuration's operationSearchPaths. Each operation (query, mutation, or subscription) and fragment definition will be created in a separate file.

To learn more about GraphQL operations, check out Defining operations

The output.operations property value determines the location of the generated operation files:

ValueDescription
inSchemaModuleOperation models will be included in the schema types module.
relative(subpath:)Operation models will be output relative to their defining .graphql files.
absolute(path:)All operation object files will be located in the specified path.

Operations in the schema module

OperationsFileOutput.inSchemaModule

This option includes the generated operation models in the same module as your schema types.

This means the output location or your operation models is determined by the output.schemaTypes.path option. When using this option the directory of your schema module will include a Schema folder for your schema types, as well as folders for your operations, fragments, and local cache mutations.

When using this option, generated operation models are expected to be included in the same target as the schema types. Therefore they will not include import statements to import the schema module.

Relative operations output

OperationsFileOutput.relative(subpath: String?)

This option outputs your generated operation models relative to their GraphQL definition (.graphql files).

Using relative operation outputs, you have complete control over where your operation definitions are generated. It is common practice to co-locate your operation and fragment models with the parts of your project that will use them.

An optional subpath parameter can be provided to generate operation models in a subfolder that will be created within the directory of their defining GraphQL definition file. If no subpath is specified then all operation files will be generated alongside thier GraphQL definition files.

Operation Models in a multi-module project:

If your project constists of multiple modules you can use relative operation output, to generate operation models into directories that are part of different modules in your project. In order to generate relative operation models for a multi-module project, all of your operation models should be generated at the same time. This means the Code Generation Engine should be run in a context that has access to the source files of all of your modules.

After generating your operation models ensure that:

  • All modules containing generated operation models are linked to the target containing your schema types.
  • All fragments referenced by your operation models are either:
    • Included in the same target as the referencing operation; or
    • Included in the schema module directly

In the future, we plan to allow you to include fragments in other modules and share them between multiple modules in your project.

Absolute operations output

OperationsFileOutput.absolute(path: String)

This option outputs all of your generated operation models in a single directory.

Specify the directory for your operation models using the path parameter. This is resolved as a relative path from the directory containing your apollo-codegen-config.json file when using the CLI.

Test mocks

output.testMocks: TestMockFileOutput

Test mock objects can be created for your operation models, to configure whether test mocks are generated and how they are added to your project, use this option.

To learn more about using test mocks to mock your operation models, see the Test mocks documentation.

The output.testMocks option can be configured with the following values:

ValueDescription
noneTest mocks will not be generated.
swiftPackage(targetName:)Test mock files will be generated and included in a target defined in an SPM package.
absolute(path:)Test mock files will be generated at the specified path.

Test mocks in a Swift Package

TestMockFileOutput.swiftPackage(targetName: String?)

This option generates test mock files and defines a target in the schema modules generated Package.swift file that is suitable for linking the test mock files to your test target using Swift Package Manager.

The name of the test mock target can be specified with the targetName parameter. If no targetName is provided, the target name defaults to "${schemaNamespace}TestMocks".

Note: Using this option requires your output.schemaTypes.moduleType to be .swiftPackageManager. If this option is provided without the .swiftPackageManager module type, code generation will fail.

Absolute test mocks output

TestMockFileOutput.absolute(path: String)

This option outputs all of your generated test mocks in a single directory.

Specify the directory for your test mocks using the path parameter. This is resolved as a relative path from the directory containing your apollo-codegen-config.json file when using the CLI.

Note: When using this option, you are responsible for ensuring the generated test mocks are linked to your test target.

Test mocks generated this way may also be manually embedded in a test utility module that is imported by your test target.

Operation identifiers

Providing a path for this property will generate a JSON document with all your operations and their computed identifier hashes. This document can be used to pre-register the identifiers for your operations with an Apollo Server instance for use with Automatic Persisted Queries.

CLI Configuration JSON
{
"b02d2d734060114f64b24338486748f4f1f00838e07a293cc4e0f73f98fe3dad": {
"name": "TestQuery",
"source": "query TestQuery {\\n test\\n}"
},
"50ed8cda22910b3b708bc69402626f9fe4f1bbaeafb40df9084d029fade5bab1": {
"name": "TestMutation",
"source": "mutation TestMutation {\\n update {\\n result\\n }\\n}"
},
"55f75259c34f0ccc6b131d23545d9fa79885c93ec785176bd9b6d3c4062fcaed": {
"name": "TestSubscription",
"source": "subscription TestSubscription {\\n watched\\n}"
}
}

Output options

The code generation engine supports a number of configuration options to change the behaviour of the generator and tailor the generated Swift code to your specific needs.

The top-level properties are:

Property NameDescription
additionalInflectionRulesAny non-default rules for pluralization or singularization of type names.
queryStringLiteralFormatFormatting of the GraphQL query string literal that is included in each generated operation object.
deprecatedEnumCasesAnnotate generated Swift enums with the Swift @available attribute for GraphQL enum cases annotated with the built-in @deprecated directive.
schemaDocumentationInclude or exclude schema documentation in the generated files.
selectionSetInitializersGenerate initializers for your generated selection set models.
apqsWhether the generated operations should use Automatic Persisted Queries.
cocoapodsCompatibleImportStatementsGenerate import statements that are compatible with including Apollo via Cocoapods.
warningsOnDeprecatedUsageAnnotate generated Swift code with the Swift @available attribute and @deprecated argument for parts of the GraphQL schema annotated with the built-in @deprecated directive.
conversionStrategiesRules for how to convert the names of values from the schema in generated code.
pruneGeneratedFilesWhether unused generated files will be automatically deleted.
CLI Configuration JSON
"options": {
"additionalInflectionRules": [{
"pluralization": {
"replacementRegex": "animals",
"singularRegex": "animal"
}
}],
"queryStringLiteralFormat": "multiline",
"deprecatedEnumCases": "include",
"schemaDocumentation": "include",
"selectionSetInitializers" : {
"operations": false,
"namedFragments": false,
"localCacheMutations" : true,
"definitionsNamed": [
"MyOperation",
"MyFragment"
]
},
"apqs": "disabled",
"cocoapodsCompatibleImportStatements": false,
"warningsOnDeprecatedUsage": "include",
"conversionStrategies": {
"enumCases": "camelCase"
},
"pruneGeneratedFiles": true
}
Swift Codegen Setup
let configuration = ApolloCodegenConfiguration(
// Other properties not shown
options: ApolloCodegenConfiguration.OutputOptions(
additionalInflectionRules: [
.pluralization(
singularRegex: "animal",
replacementRegex: "animals"
)
],
queryStringLiteralFormat: .multiline,
deprecatedEnumCases: .include,
schemaDocumentation: .include,
selectionSetInitializers: [
.localCacheMutations,
.operation(named: "MyOperation"),
.fragment(named: "MyFragment)
],
apqs: .disabled,
cocoapodsCompatibleImportStatements: false,
warningsOnDeprecatedUsage: .include,
conversionStrategies: ApolloCodegenConfiguration.ConversionStrategies(
enumCases: .camelCase
),
pruneGeneratedFiles: true
)
)

Experimental features

The code generation engine supports some behaviors where the affect on the generated code is considered experimental. An example of this is a specification of the GraphQL schema that is not yet formalized and undergoing change as the proposal advances.

Note: These features could change at any time and are not guaranteed to always be available.

The current supported experimental features are:

Valueescription
clientControlledNullabilityIf enabled, codegen will understand and parse Client Controlled Nullability. Read the RFC for more detail.
legacySafelistingCompatibleOperationsIf enabled, the generated operations will be transformed using a method that attempts to maintain compatibility with the legacy behavior from apollo-tooling for registering persisted operation to a safelist.

Note: Safelisting queries is a deprecated feature of Apollo Server that has reduced support for legacy use cases. This option may not work as intended in all situations.
CLI Configuration JSON
"experimentalFeatures": {
"clientControlledNullability": false,
"legacySafelistingCompatibleOperations": false
}
Swift Codegen Setup
let configuration = ApolloCodegenConfiguration(
// Other properties not shown
experimentalFeatures: ApolloCodegenConfiguration.ExperimentalFeatures(
clientControlledNullability: false,
legacySafelistingCompatibleOperations: false
)
)

Schema download configuration

An optional step in the code generation process is to fetch a GraphQL schema from a remote server. This step ensures that you always have an up-to-date schema on which to base your operations and it eliminates the need to manually download the schema outside of the automated process.

The properties to configure the schema download are:

Property NameDescription
downloadMethodHow to download the schema.
downloadTimeoutThe maximum time (in seconds) to wait before indicating that the download timed out.
headersAny additional headers to include when retrieving your schema. This is useful when the schema download requires authentication.
outputPathThe local path where the downloaded schema should be written to.

Download method

There are two supported sources for fetching a GraphQL schema:

1. Apollo server registry

The Apollo schema registry serves as a central hub for managing your graph.

The properties you will need to configure are:

Property NameDescription
apiKeyAPI key to use when retrieving your schema from the Apollo Registry.
graphIDIdentifier of the graph to fetch. Can be found in Apollo Studio.
variantVariant of the graph in the registry.
CLI Configuration JSON
"schemaDownloadConfiguration": {
"downloadMethod": {
"apolloRegistry": {
"_0": {
"graphID": "your-graphid",
"apiKey": "your-api-key",
"variant": "current"
}
}
},
"downloadTimeout": 60,
"headers": {
"Accept-Encoding" : "gzip",
"Authorization" : "Bearer <token>"
},
"outputPath": "./graphql/"
}
Swift Codegen Setup
let configuration = ApolloCodegenConfiguration(
// Other properties not shown
schemaDownloadConfiguration: ApolloSchemaDownloadConfiguration(
using: .apolloRegistry(.init(
apiKey: "your-api-key",
graphID: "your-graphid",
variant: "current")),
timeout: 60.0,
headers: [
.init(key: "Accept-Encoding", value: "gzip"),
.init(key: "Authorization", value: "Bearer <token>")
],
outputPath: "./graphql/")
)

2. GraphQL introspection

A GraphQL service supports introspection over its schema.

Note: Many production servers disable introspection for security reasons. If your introspection query is failing check that it is not disabled.

The properties you will need to configure are:

Property NameDescription
endpointURLURL of the GraphQL introspection service.
httpMethodHTTP request method.
outputFormatOutput format for the downloaded schema.
includeDeprecatedInputValuesSpecify whether input values annotated with the built-in @deprecated directive should be included in the fetched schema.
CLI Configuration JSON
"schemaDownloadConfiguration": {
"downloadMethod": {
"introspection": {
"endpointURL": "https://server.com",
"httpMethod": {
"POST": {}
},
"includeDeprecatedInputValues": false,
"outputFormat": "SDL"
}
},
"downloadTimeout": 60,
"headers": [],
"outputPath": "./graphql/"
}
Swift Codegen Setup
let configuration = ApolloCodegenConfiguration(
// Other properties not shown
schemaDownloadConfiguration: ApolloSchemaDownloadConfiguration(
using: .introspection(
endpointURL: URL(string: "https://server.com")!),
timeout: 60.0,
headers: [],
outputPath: "./graphql/")
)

For more details, see the section on downloading a schema.

Edit on GitHub
Previous
The Codegen CLI
Next
Downloading a Schema