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:

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:

1
"input": {
2
    "schemaSearchPaths": [
3
        "**/*.graphqls"
4
    ],
5
    "operationSearchPaths": [
6
        "**/*.graphql"
7
    ]
8
}

1
let configuration = ApolloCodegenConfiguration(
2
    // Other properties not shown
3
    input: ApolloCodegenConfiguration.FileInput(
4
        schemaSearchPaths: ["**/*.graphqls"],
5
        operationSearchPaths: ["**/*.graphql"]
6
    ),
7
)

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:

1
"output": {
2
    "schemaTypes": {
3
        "moduleType": {
4
            "swiftPackageManager": {}
5
        },
6
        "path": "./generated/schema/"
7
    },
8
    "operations": {
9
        "inSchemaModule": {}
10
    },
11
    "testMocks": {
12
        "none": {}
13
    },
14
    "operationIdentifiersPath": "./generated/"
15
}

1
let configuration = ApolloCodegenConfiguration(
2
    // Other properties not shown
3
    output: ApolloCodegenConfiguration.FileOutput(
4
        schemaTypes: ApolloCodegenConfiguration.SchemaTypesFileOutput(
5
            path: "./generated/schema/",
6
            moduleType: .swiftPackageManager
7
        )
8
        operations: .inSchemaModule,
9
        testMocks: .none,
10
        operationIdentifiersPath: "./generated/"
11
    )
12
)

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:

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.

The possible values for moduleType are:

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.

1
"output": {
2
    "schemaTypes": {
3
        "moduleType": {
4
            "embeddedInTarget": {
5
                "name": "MyApplicationTarget"
6
            }
7
        },
8
        "path": "./generated/schema/"
9
    }
10
}

1
let configuration = ApolloCodegenConfiguration(
2
    // Other properties not shown
3
    output: ApolloCodegenConfiguration.FileOutput(
4
        schemaTypes: ApolloCodegenConfiguration.SchemaTypesFileOutput(
5
            path: "./generated/schema/",
6
            moduleType: .embeddedInTarget(name: "MyApplicationTarget")
7
        )
8
        ...
9
    )
10
)

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.

1
"output": {
2
    "schemaTypes": {
3
        "moduleType": {
4
            "swiftPackageManager": {}
5
        },
6
        "path": "./generated/schema/"
7
    }
8
}

1
let configuration = ApolloCodegenConfiguration(
2
    // Other properties not shown
3
    output: ApolloCodegenConfiguration.FileOutput(
4
        schemaTypes: ApolloCodegenConfiguration.SchemaTypesFileOutput(
5
            path: "./generated/schema/",
6
            moduleType: .swiftPackageManager
7
        )
8
        ...
9
    )
10
)

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.

1
"output": {
2
    "schemaTypes": {
3
        "moduleType": {
4
            "other": {}
5
        },
6
        "path": "./generated/schema/"
7
    }
8
}

1
let configuration = ApolloCodegenConfiguration(
2
    // Other properties not shown
3
    output: ApolloCodegenConfiguration.FileOutput(
4
        schemaTypes: ApolloCodegenConfiguration.SchemaTypesFileOutput(
5
            path: "./generated/schema/",
6
            moduleType: .other
7
        )
8
        ...
9
    )
10
)

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.

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

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.

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.

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.

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

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".

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.

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.

1
{
2
    "b02d2d734060114f64b24338486748f4f1f00838e07a293cc4e0f73f98fe3dad": {
3
        "name": "TestQuery",
4
        "source": "query TestQuery {\\n  test\\n}"
5
    },
6
    "50ed8cda22910b3b708bc69402626f9fe4f1bbaeafb40df9084d029fade5bab1": {
7
        "name": "TestMutation",
8
        "source": "mutation TestMutation {\\n  update {\\n    result\\n  }\\n}"
9
    },
10
    "55f75259c34f0ccc6b131d23545d9fa79885c93ec785176bd9b6d3c4062fcaed": {
11
        "name": "TestSubscription",
12
        "source": "subscription TestSubscription {\\n  watched\\n}"
13
    }
14
}

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:

1
"options": {
2
    "additionalInflectionRules": [{
3
        "pluralization": {
4
            "replacementRegex": "animals",
5
            "singularRegex": "animal"
6
        }
7
    }],
8
    "queryStringLiteralFormat": "multiline",
9
    "deprecatedEnumCases": "include",
10
    "schemaDocumentation": "include",
11
    "selectionSetInitializers" : {
12
        "operations": false,
13
        "namedFragments": false,
14
        "localCacheMutations" : true,
15
        "definitionsNamed": [
16
            "MyOperation",
17
            "MyFragment"
18
        ]
19
    },
20
    "apqs": "disabled",
21
    "cocoapodsCompatibleImportStatements": false,
22
    "warningsOnDeprecatedUsage": "include",
23
    "conversionStrategies": {
24
        "enumCases": "camelCase"
25
    },
26
    "pruneGeneratedFiles": true
27
}

1
let configuration = ApolloCodegenConfiguration(
2
    // Other properties not shown
3
    options: ApolloCodegenConfiguration.OutputOptions(
4
        additionalInflectionRules: [
5
            .pluralization(
6
                singularRegex: "animal",
7
                replacementRegex: "animals"
8
            )
9
        ],
10
        queryStringLiteralFormat: .multiline,
11
        deprecatedEnumCases: .include,
12
        schemaDocumentation: .include,
13
        selectionSetInitializers: [
14
            .localCacheMutations,
15
            .operation(named: "MyOperation"),
16
            .fragment(named: "MyFragment)
17
        ],
18
        apqs: .disabled,
19
        cocoapodsCompatibleImportStatements: false,
20
        warningsOnDeprecatedUsage: .include,
21
        conversionStrategies: ApolloCodegenConfiguration.ConversionStrategies(
22
            enumCases: .camelCase
23
        ),
24
        pruneGeneratedFiles: true
25
    )
26
)

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.

The current supported experimental features are:

1
"experimentalFeatures": {
2
    "clientControlledNullability": false,
3
    "legacySafelistingCompatibleOperations": false
4
}

1
let configuration = ApolloCodegenConfiguration(
2
    // Other properties not shown
3
    experimentalFeatures: ApolloCodegenConfiguration.ExperimentalFeatures(
4
        clientControlledNullability: false,
5
        legacySafelistingCompatibleOperations: false
6
    )
7
)

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:

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:

1
"schemaDownloadConfiguration": {
2
    "downloadMethod": {
3
        "apolloRegistry": {
4
            "_0": {
5
                "graphID": "your-graphid",
6
                "apiKey": "your-api-key",
7
                "variant": "current"
8
            }
9
        }
10
    },
11
    "downloadTimeout": 60,
12
    "headers": {
13
        "Accept-Encoding" : "gzip",
14
        "Authorization" : "Bearer <token>"
15
    },
16
    "outputPath": "./graphql/"
17
}

1
let configuration = ApolloCodegenConfiguration(
2
  // Other properties not shown
3
  schemaDownloadConfiguration: ApolloSchemaDownloadConfiguration(
4
    using: .apolloRegistry(.init(
5
      apiKey: "your-api-key",
6
      graphID: "your-graphid",
7
      variant: "current")),
8
    timeout: 60.0,
9
    headers: [
10
      .init(key: "Accept-Encoding", value: "gzip"),
11
      .init(key: "Authorization", value: "Bearer <token>")
12
    ],
13
    outputPath: "./graphql/")
14
)

2. GraphQL introspection

A GraphQL service supports introspection over its schema.

The properties you will need to configure are:

1
"schemaDownloadConfiguration": {
2
    "downloadMethod": {
3
        "introspection": {
4
            "endpointURL": "https://server.com",
5
            "httpMethod": {
6
                "POST": {}
7
            },
8
            "includeDeprecatedInputValues": false,
9
            "outputFormat": "SDL"
10
        }
11
    },
12
    "downloadTimeout": 60,
13
    "headers": [],
14
    "outputPath": "./graphql/"
15
}

1
let configuration = ApolloCodegenConfiguration(
2
    // Other properties not shown
3
    schemaDownloadConfiguration: ApolloSchemaDownloadConfiguration(
4
        using: .introspection(
5
            endpointURL: URL(string: "https://server.com")!),
6
        timeout: 60.0,
7
        headers: [],
8
        outputPath: "./graphql/")
9
)

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