JavaScript, Android, Swift, and Flutter client code generation

"Codegen" generates native code for Swift (iOS), Java (Android), and JavaScript that represent your GraphQL API's data models. It can also generate GraphQL statements (queries, mutations, and subscriptions) so that you don't have to hand code them.

The design of codegen functionality provides mechanisms to run at different points in your app development lifecycle, including when you create or update an API as well as independently when you want to just update the data fetching requirements of your app but leave your API alone. It additionally allows you to work in a team where the schema is updated or managed by another person. Finally, you can also include the codegen in your build process so that it runs automatically (such as from in Xcode).

Generate GraphQL client helper code for GraphQL APIs deployed with Amplify GraphQL CDK construct

The necessary GraphQL client helper code differ from platform to platform. For JavaScript GraphQL client code, you need to reference the API ID that you receive after you deploy your application. For Android, iOS, and Flutter you can reference the local GraphQL schema to generate models for your API client.

JavaScript / TypeScript GraphQL API client helper code

Go to your frontend app's root directory and run the following command in the Terminal:

npx @aws-amplify/cli codegen add --apiId <...> --region <...>

This will download your API's schema and by default generate client helper code into the src/graphql folder. After every API deployment, you can rerun the following command to generate updated GraphQL statement and types:

npx @aws-amplify/cli codegen

Generate "models" for Android, Swift, Flutter, and JavaScript DataStore

The Android, Swift, Flutter, and DataStore on JavaScript use the "modelgen" pattern to interact with the client library. To generate models, run the following command from your frontend application's root directory:

npx @aws-amplify/cli codegen models \
  --model-schema <path-to-schema.graphql> \
  --target [android|ios|flutter|javascript|typescript] \
  --output-dir ./

Generate GraphQL Client code with Amplify CLI-deployed GraphQL API

Create API then automatically generate code

amplify init
amplify add api (select GraphQL)
amplify push

You’ll see questions as before, but now it will also automatically ask you if you want to generate GraphQL statements and do codegen. It will also respect the ./app/src/main directory for Android projects. After the AppSync deployment finishes the Swift file will be automatically generated (Android you’ll need to kick off a Gradle Build step) and you can begin using in your app immediately.

When you deploy your GraphQL API to the cloud, you are prompted to configure codegen. When a project is configured to generate code with codegen, it stores all the configuration .graphqlconfig.yml file in the root folder of your project. To make changes to the configuration, use amplify configure codegen.

Modify GraphQL schema, push, then automatically generate code

During development, you might wish to update your GraphQL schema and generated code as part of an iterative dev/test cycle. Modify & save your schema in amplify/backend/api/<apiname>/schema.graphql then run:

amplify push

Each time you will be prompted to update the code in your API and also ask you if you want to run codegen again as well, including regeneration of the GraphQL statements from the new schema.

No API changes, just update GraphQL statements & generate code

One of the benefits of GraphQL is the client can define its data fetching requirements independently of the API. Amplify codegen supports this by allowing you to modify the selection set (e.g. add/remove fields inside the curly braces) for the GraphQL statements and running type generation again. This gives you fine-grained control over the network requests that your application is making. Modify your GraphQL statements (default in the ./graphql folder unless you changed it) then save the files and run:

amplify codegen types

A new updated Swift file will be created (or run Gradle Build on Android for the same). You can then use the updates in your application code.

Shared schema, modified elsewhere (e.g. console or team workflows)

Suppose you are working in a team and the schema is updated either from the AWS AppSync console or on another system. Your types are now out of date because your GraphQL statement was generated off an outdated schema. The easiest way to resolve this is to regenerate your GraphQL statements, update them if necessary, and then generate your types again. Modify the schema in the console or on a separate system, then run:

amplify codegen statements
amplify codegen types

You should have newly generated GraphQL statements and Swift code that matches the schema updates. If you ran the second command your types will be updated as well. Alternatively, if you run amplify codegen alone it will perform both of these actions.

Introspection Schema outside of an initialized project

If you would like to generate statements and types without initializing an amplify project, you can do so by providing your introspection schema named schema.json in your project directory and adding codegen from the same directory. To download your introspection schema from an AppSync api, in the AppSync console go to the schema editor and under "Export schema" choose schema.json.

amplify add codegen

Once codegen has been added you can update your introspection schema, then generate statements and types again without re-entering your project information.

amplify codegen

You can update your project and codegen configuration if required.

amplify configure codegen
amplify codegen

When generating types, codegen uses GraphQL statements as input. It will generate only the types that are being used in the GraphQL statements.

Codegen commands

amplify add codegen

amplify add codegen

The amplify add codegen allows you to add AppSync API created using the AWS console. If you have your API is in a different region then that of your current region, the command asks you to choose the region. If you are adding codegen outside of an initialized amplify project, provide your introspection schema named schema.json in the same directory that you make the add codegen call from. Note: If you use the --apiId flag to add an externally created AppSync API, such as one created in the AWS console, you will not be able to manage this API from the Amplify CLI with commands such as amplify api update when performing schema updates. You cannot add an external AppSync API when outside of an initialized project.

amplify configure codegen

amplify configure codegen

The amplify configure codegen command allows you to update the codegen configuration after it is added to your project. When outside of an initialized project, you can use this to update your project configuration as well as the codegen configuration.

amplify codegen statements

amplify codegen statements [--nodownload] [--maxDepth <int>]

The amplify codegen statements command generates GraphQL statements(queries, mutation and subscription) based on your GraphQL schema. This command downloads introspection schema every time it is run, but it can be forced to use previously downloaded introspection schema by passing --nodownload flag.

amplify codegen types

amplify codegen types

The amplify codegen types [--nodownload] command generates GraphQL types for Flow and typescript and Swift class in an iOS project. This command downloads introspection schema every time it is run, but it can be forced to use previously downloaded introspection schema by passing --nodownload flag.

amplify codegen

amplify codegen [--maxDepth <int>]

The amplify codegen [--nodownload] generates GraphQL statements and types. This command downloads introspection schema every time it is run but it can be forced to use previously downloaded introspection schema by passing --nodownload flag. If you are running codegen outside of an initialized amplify project, the introspection schema named schema.json must be in the same directory that you run amplify codegen from. This command will not download the introspection schema when outside of an amplify project - it will only use the introspection schema provided.

Statement depth

In the below schema there are connections between Comment -> Post -> Blog -> Post -> Comments. When generating statements codegen has a default limit of 2 for depth traversal. But if you need to go deeper than 2 levels you can change the maxDepth parameter either when setting up your codegen or by passing --maxDepth parameter to codegen

type Blog @model {
  id: ID!
  name: String!
  posts: [Post] @hasMany
}
type Post @model {
  id: ID!
  title: String!
  blog: Blog @belongsTo
  comments: [Comment] @hasMany
}
type Comment @model {
  id: ID!
  content: String
  post: Post @belongsTo
}

query GetComment($id: ID!) {
  getComment(id: $id) {
    # depth level 1
    id
    content
    post {
      # depth level 2
      id
      title
      blog {
        # depth level 3
        id
        name
        posts {
          # depth level 4
          items {
            # depth level 5
            id
            title
          }
          nextToken
        }
      }
      comments {
        # depth level 3
        items {
          # depth level 4
          id
          content
          post {
            # depth level 5
            id
            title
          }
        }
        nextToken
      }
    }
  }
}