Page updated Nov 8, 2023

Feature flags

Feature flags makes it possible to fine tune given functionality in the Amplify CLI.

They are grouped into sections based on the area of the functionality. An area can be a category or some other scope. There are different type of feature flags defined, their lifetime is controlled the lifecycle process.

Types of feature flags

Release

These types of feature flags are used to enable or disable a given functionality in Amplify CLI that is under active development. These feature flags are removed and become unsupported once a feature has been shipped.

Feature

During the history of the Amplify CLI there are enhancements that can benefit for new projects but potentially can cause breaking changes in existing deployments. These feature flags are controlled by the lifecycle process to provide time for mitigation and migration. These type of flags are disabled for existing projects and enabled for new ones.

Examples

  • Breaking existing projects by generating different code and would require a backend deployment.
  • The push operation of a changed resource would require a resource recreation that could lead to data loss.
  • The push operation of a changed resource would require data backfill to make the client application operable.
  • The generated code for client applications would require a rebuild and republish to be compatible with the newly pushed backend.

Experimental

Experimental feature flags are to enable experimentation with given functionality, to provide feedback to the Amplify CLI team. Enabling these feature in production is highly discouraged.

The outcome of experimental features can be:

  • The feature will make into the product so it will be turned into a Release type feature flag.
  • The experimental feature is not making into the product and removed from the codebase together with the code itself.

Lifecycle

Each type of feature flags are managed under a lifecycle management process. When a feature flag is added to the Amplify CLI it will be mentioned in the release notes and also this page will be updated with the detailed information. After adding a feature flag this page will contain information about what version a feature flag was added, what is the planned deprecation date - if there is one -, in which version the feature flag was deprecated, in which version the feature flag was removed.

When a feature flag is deprecated it still can be used but when used a warning will be printed on the screen during the execution of Amplify CLI commands.

Before removal a removal date is added to the feature flag, and after a feature flag is removed Amplify CLI will shows an error message about it and the version the feature flag was removed added to the page.

Configuration

Configuration of feature flags are primarily done by having an cli.json file in the project's amplify folder. If the file does not exist Amplify CLI creates it during the amplify init command. The emitted values are representing the default values for new projects. This file must be under version control, to make sure that the same features are used locally, in CI/CD environments, between team members. If an environment specific file exists for the currently checked out environment, during amplify env add command the same file will be copied for the newly created environment as well.

Example configuration file

{ "features": { "graphQLTransformer": { "addMissingOwnerFields": true, "validateTypeNameReservedWords": true, "useExperimentalPipelinedTransformer": false, "enableIterativeGSIUpdates": false }, "frontend-ios": { "enableXcodeIntegration": true }, "auth": { "enableCaseInsensitivity": true, "useInclusiveTerminology": true, "breakCircularDependency": true }, "codegen": { "useAppSyncModelgenPlugin": true } } }
1{
2 "features": {
3 "graphQLTransformer": {
4 "addMissingOwnerFields": true,
5 "validateTypeNameReservedWords": true,
6 "useExperimentalPipelinedTransformer": false,
7 "enableIterativeGSIUpdates": false
8 },
9 "frontend-ios": {
10 "enableXcodeIntegration": true
11 },
12 "auth": {
13 "enableCaseInsensitivity": true,
14 "useInclusiveTerminology": true,
15 "breakCircularDependency": true
16 },
17 "codegen": {
18 "useAppSyncModelgenPlugin": true
19 }
20 }
21}

If for some reason different functionality is needed to be enabled for a given Amplify CLI environment a copy can be made of the project level file with the following naming convention: cli.{environment name}.json.

Environment variables

Amplify CLI supports the definition and override of feature flags values from environment variables and .env files as well.

The environment variables must follow a naming convention, to be picked up by Amplify CLI:

  • Project level override: AMPLIFYCLI_{SECTION}__{PROPERTY}, for example: AMPLIFYCLI_GRAPHQLTRANSFORMER__TRANSFORMERVERSION
  • Environment specific override: AMPLIFYCLI_{ENVNAME}_{SECTION}__{PROPERTY}, for example: AMPLIFYCLI_PROD_GRAPHQLTRANSFORMER__TRANSFORMERVERSION

If a .env file is used in the project's root folder, then it is being merged on top of the current process' environment variables, overwriting those.

Order of evaluation

Due to the multiple levels of configuration options and overrides, Amplify CLI does a top-to-bottom evaluation as follows:

  • cli.json
  • cli.{environment name}.json
  • Project level environment variables
  • CLI Environment level environment variables

Feature flags

Note: feature flags are case-insensitive, however are described here in camelCase for readability

appSync

Feature Flags related to AppSync backed APIs.

generateGraphQLPermissions

Changes the permission format to grant access to graphql operations instead of appsync control plane operations

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature4.42.0May 1st 2021
ValueDescriptionDefault for existing projectsDefault for new projects
trueCreates IAM policies to allow Query/Mutations
falseUses previous policy format which allows control plane access to AppSync

graphQLTransformer

Feature Flag related to GraphQL Transformer

addMissingOwnerFields

Automatically add owner field to type when owner fields are not in the type

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature4.30.0
ValueDescriptionDefault for existing projectsDefault for new projects
trueInserts the owner field from auth rules when its missing in type
falseDoesn't insert the owner field automatically

improvePluralization

Use word specific pluralization instead of only appending an "s" to every word. Note: this feature flag is only respected when using GraphQL Transformer v1.

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature5.0.2
ValueDescriptionDefault for existing projectsDefault for new projects
trueWhen pluralizing values i.e. for list resolvers, 'Match' becomes 'Matches'
falseWhen pluralizing values i.e. for list resolvers, 'Match' becomes 'Matchs'

validateTypeNameReservedWords

Throw an error when compiling the GraphQL schema if a type name is a reserved word.

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature4.32.1May 1st 2021
ValueDescriptionDefault for existing projectsDefault for new projects
trueThrows an error if a type name is a reserved word.
falseAllows compilation to pass with reserved words as type names. However, you may encounter downstream GraphQL errors.

useExperimentalPipelinedTransformer

Use pipeline resolver-based GraphQL Transformer (GraphQL Transformer vNext).

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature4.32.4
ValueDescriptionDefault for existing projectsDefault for new projects
trueEnable pipeline resolver-based GraphQL Transformer (GraphQL Transformer vNext).
falseDisables pipeline resolver-based GraphQL Transformer.

enableIterativeGsiUpdates

Enable multiple GSI updates through iterative incremental deployments.

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature4.38.0May 1st 2021
ValueDescriptionDefault for existing projectsDefault for new projects
trueGraphQL schemas changes can contain multiple GSI changes.
falseThrows Error when mutating more than 1 GSIs in update flow. .

secondaryKeyAsGSI

Changes the behaviour of @key directive to always create GSIs.

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature4.41.xMay 1st 2021
ValueDescriptionDefault for existing projectsDefault for new projects
true@key will always create GSIs for named keys.
false@key create an LSI when the named key includes a primary field.

skipOverrideMutationInputTypes

If a custom mutation is defined on a model, prevent the regeneration of that mutation

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature4.45.0
ValueDescriptionDefault for existing projectsDefault for new projects
trueIf a custom create, update, or delete mutation is defined on a model, the input will not be regenerated
falseThe GraphQL Transformer will recreate inputs for models even if they have the custom mutations specified

transformerVersion

Sets which version of the GraphQL Transformer will be used

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature6.4.0
ValueDescriptionDefault for existing projectsDefault for new projects
1The GraphQL Transformer V1 will be used
2The GraphQL Transformer V2 will be used

suppressSchemaMigrationPrompt

Prevent the CLI from prompting for schema migration

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature6.4.0November 10th 2021
ValueDescriptionDefault for existing projectsDefault for new projects
trueGraphQL Transformer V1 projects will not be prompted to migrate to V2
falseGraphQL Transformer V1 projects will be prompted to migrate to V2

securityEnhancementNotification

Adds notification of @auth updates to improve security for @primaryKey and @index

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature7.6.12
ValueDescriptionDefault for existing projectsDefault for new projects
trueA notification with a prompt will appear, after which security updates are automatically applied and no further prompt will appear
falseThere is no notification of security updates

showFieldAuthNotification

Adds a notification of @auth security change.

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature7.6.15
ValueDescriptionDefault for existing projectsDefault for new projects
trueA notification with a prompt will appear, after which security updates are automatically applied and no further prompt will appear
falseThere is no notification of security updates

useSubUsernameForDefaultIdentityClaim

Changes the default identity claim to for owner-based @auth from 'username' to 'sub::username'

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature8.x
ValueDescriptionDefault for existing projectsDefault for new projects
trueUses a default owner field format of '<sub>::<username>' to write records and reads both '<username>' and '<sub>::<username>'
falseUses a default owner field format of '<username>' to write records and reads '<username>'

useFieldNameForPrimaryKeyConnectionField

Changes the naming convention for primary key connection fields.

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature8.3.0
ValueDescriptionDefault for existing projectsDefault for new projects
trueUses 'Id' in the name. (Type + RelatedType + Id)
falseUses the related type field name in the name. (Type + RelatedType + RelatedTypeFieldName)

enableAutoIndexQueryNames

Changes the behaviour of @index directive to auto-generate Queries for indexes if no 'queryField' is provided.

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature8.5.0
ValueDescriptionDefault for existing projectsDefault for new projects
trueAn empty 'queryField' will cause a Query to be auto-generated. Explicit null value will disable this functionality
falseA Query will only be created if the 'queryField' is explicitly set

respectPrimaryKeyAttributesOnConnectionField

Changes the behavior of relational directives on model types that contain a custom primary key by generating connection fields that respect the attributes of the primary key and sort key fields. The changes include naming convention, the number of connected fields, and their field types. In addition, this changes the code generation for DataStore models of all platforms to enable the custom primary key feature.

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature10.0.0
ValueDescriptionDefault for existing projectsDefault for new projects
falseOnly one connection field with type ID generated on connected models. Model-gen with custom primary key feature is disabled.
trueConnection field(s) are generated respecting the attributes of priamry key and sort key fields. Model-gen with custom primary key feature is enabled.

shouldDeepMergeDirectiveConfigDefaults

Performs a deep merge with default directives and custom directives.

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature9.1.0
ValueDescriptionDefault for existing projectsDefault for new projects
falseMerge default directives and custom directives with a single level depth. Custom directives will take precedent.
trueMerge default directives and custom directives with unlimitted depth. Custom directives will take precedent.

populateOwnerFieldForStaticGroupAuth

Populates the owner field automatically if the user is already authorized by static user pool authorization rules

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature9.2.0
ValueDescriptionDefault for existing projectsDefault for new projects
trueIf the user is authorized, the owner field is automatically populated
falseIf the user is authorized by static user pool authorization rules, the owner field needs to be explicitly set by the developer

frontend-ios

Feature Flag related to iOS projects

enableXcodeIntegration

Automatically add DataStore / API models to the Xcode project.

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature4.40.0May 1st 2021
ValueDescriptionDefault for existing projectsDefault for new projects
trueAll newly generated DataStore/API models are auto-added to the Xcode project
falseAll newly generated DataStore/API models are NOT auto-added to the Xcode project.

auth

Feature Flag related to auth

enableCaseInsensitivity

Toggles case insensitivity for Cognito login mechanisms (username, email etc..)

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature4.40.0May 1st 2021
ValueDescriptionDefault for existing projectsDefault for new projects
trueEmails and usernames are case insensitive
falseEmails and usernames are case sensitive.

useInclusiveTerminology

Toggles terminology used for allow and deny lists.

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature4.47.0April 1st 2022
ValueDescriptionDefault for existing projectsDefault for new projects
trueThe terms allowlist and denylist are used.
falseThe legacy terms whitelist and blacklist are used.

breakCircularDependency

Toggles the creation of auth triggers

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature4.51.0December 1st 2021
ValueDescriptionDefault for existing projectsDefault for new projects
trueCreates auth triggers as custom Lambdas to be used with Apis and Storage.
falseCreates auth triggers via Cognito CloudFormation

forceAliasAttributes

Forces the use of aliasAttributes with Cognito rather than usernameAttributes

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature6.0.0
ValueDescriptionDefault for existing projectsDefault for new projects
trueForces the CLI to use aliasAttributes when creating auth, allowing for a preferred_username
falseContinue to use usernameAttributes with Cognito

useEnabledMfas

Allows the use of only TOTP if only phone_number is configured, if another attribute is added SMS MFA is enabled

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature5.3.1
ValueDescriptionDefault for existing projectsDefault for new projects
trueAllow TOTP to be configured for login by itself
falseTOTP cannot be used alone for login with Cognito

codegen

Feature Flag related to Codegen

useAppsyncModelgenPlugin

Choose between implementations of internal DataStore model generator package. Refer https://github.com/aws-amplify/amplify-codegen/blob/main/FeatureFlags.md

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature4.40.0May 1st 2021
ValueDescriptionDefault for existing projectsDefault for new projects
true[Recommended] Use the models generator internal package implementation at https://github.com/aws-amplify/amplify-codegen/tree/main/packages/appsync-modelgen-plugin
falseUse the deprecated models generator package implementation at https://github.com/aws-amplify/amplify-cli/tree/main/packages/amplify-codegen-appsync-model-plugin

useDocsGeneratorPlugin

Choose between implementations of internal GraphQL documents generator package. Refer https://github.com/aws-amplify/amplify-codegen/blob/main/FeatureFlags.md

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature4.40.0May 1st 2021
ValueDescriptionDefault for existing projectsDefault for new projects
true[Recommended] Use the GraphQL documents generator internal package implementation at https://github.com/aws-amplify/amplify-codegen
falseUse the deprecated GraphQL documents generation package implementation at https://github.com/aws-amplify/amplify-cli/tree/main/packages/amplify-graphql-docs-generator

useTypesGeneratorPlugin

Choose between implementations of internal GraphQL types generator package. Refer https://github.com/aws-amplify/amplify-codegen/blob/main/FeatureFlags.md

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature4.40.0May 1st 2021
ValueDescriptionDefault for existing projectsDefault for new projects
true[Recommended] Use the types generator internal package implementation at https://github.com/aws-amplify/amplify-codegen
falseUse the deprecated types generation package implementation at https://github.com/aws-amplify/amplify-cli/tree/main/packages/amplify-graphql-types-generator

cleanGeneratedModelsDirectory

Clears the generated models folder before they are re-generated.

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature4.40.0May 1st 2021
ValueDescriptionDefault for existing projectsDefault for new projects
trueRecommended to be set true when there are no hand-written files in the modelgen output folder.
falseDoes not remove pre-existing files from the modelgen output folder. This would retain the generated models even after the corresponding types are removed from the GraphQL schema.

retainCaseStyle

Retains the case style developer uses while naming the GraphQL types in schema

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature4.40.0May 1st 2021
ValueDescriptionDefault for existing projectsDefault for new projects
trueRetain the case style used for naming the GraphQL types in the schema. Refer https://github.com/aws-amplify/amplify-codegen/pull/89
falseGenerate camelCase/PascalCase variable names for types irrespective of the case style used for naming the types.

addTimestampFields

Add read-only timestamp fields in modelgen. For more infomation please refer change logs of amplify repos

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature4.51.2Nov 1st 2021
ValueDescriptionDefault for existing projectsDefault for new projects
true[Recommended] Add read-only timestamp `createdAt` and `updatedAt` fields in modelgen. Minimum version for amplify library: amplify-ios@1.9.0, amplify-android@1.17.2
falseNo read-only timestamp fields will be added

enableDartNullSafety

Generate Dart models with null safety for Flutter applications using DataStore.

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature5.1.0Jan 1st 2022
ValueDescriptionDefault for existing projectsDefault for new projects
true[Recommended] Generate Dart models with null safety. Minimum supported version for Amplify library: amplify-flutter is 0.2.0
falseGenerate Dart models without null safety

handleListNullabilityTransparently

Configure the nullability of the List and List components in Datastore Models generation

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature5.1.2Nov 1st 2021
ValueDescriptionDefault for existing projectsDefault for new projects
true[Recommended] Respect the nullability of List types as specified in the GraphQL schema. Refer https://docs.amplify.aws/cli/migration/list-nullability for more information.
falseUse the nullability specification of list components to decide the nullability of List.

emitAuthProvider

Adds auth provider details to iOS models

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature5.0.2
ValueDescriptionDefault for existing projectsDefault for new projects
true[Recommended] Adds auth provider details to iOS models
falseiOS models will not be able to access auth provider details

generateIndexRules

Adds key/index details to iOS models

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature5.0.2
ValueDescriptionDefault for existing projectsDefault for new projects
true[Recommended] Adds key/index details to iOS models
falseiOS models will not be able to access key/index details

generateModelsForLazyLoadAndCustomSelectionSet

Generate models for lazy loading and custom selection set

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Featurex.x.x
ValueDescriptionDefault for existing projectsDefault for new projects
true[Recommended] Add support for lazy loading and custom selection set.
falsemodels will not support selection set customization and lazy loading.

latestRegionSupport

Feature Flags related to region mapping support.

comprehend

Controls Comprehend region mapping

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature6.1.0
ValueDescriptionDefault for existing projectsDefault for new projects
0us-west-1, eu-west-3, eu-north-1, ap-northeast-1, ap-northeast-2, ap-south-1, me-south-1, and sa-east-1 are mapped to other regions.
1us-west-1, eu-west-3, eu-north-1, me-south-1, and sa-east-1 are mapped to other regions.

pinpoint

Controls Pinpoint region mapping

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature6.1.0
ValueDescriptionDefault for existing projectsDefault for new projects
0ap-northeast-1, ap-northeast-2, ap-northeast-3, ap-south-1, ap-southeast-1, ap-southeast-2, ca-central-1, cn-north-1, cn-northwest-1, eu-north-1, eu-west-2, eu-west-3, me-south-1, sa-east-1, us-east-2, and us-west-1 are mapped to other regions.
1ap-northeast-3, cn-north-1, cn-northwest-1, eu-north-1, eu-west-3, me-south-1, sa-east-1, us-east-2, and us-west-1 are mapped to other regions.

rekognition

Controls Rekognition region mapping

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature6.1.0
ValueDescriptionDefault for existing projectsDefault for new projects
0ca-central-1, eu-north-1, eu-west-3, me-south-1, and sa-east-1 are mapped to other regions.
1eu-north-1, eu-west-3, me-south-1, and sa-east-1 are mapped to other regions.

textract

Controls Textract region mapping

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature6.1.0
ValueDescriptionDefault for existing projectsDefault for new projects
0ap-northeast-1, ap-northeast-2, ap-south-1, ap-southeast-1, ap-southeast-2, ca-central-1, eu-central-1, eu-north-1, eu-west-2, eu-west-3, me-south-1, and sa-east-1 are mapped to other regions.
1ap-northeast-1, eu-north-1, eu-west-3, me-south-1, and sa-east-1 are mapped to other regions.

transcribe

Controls Transcribe region mapping

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature6.1.0
ValueDescriptionDefault for existing projectsDefault for new projects
0eu-north-1 and ap-northeast-1 are mapped to other regions.
1eu-north-1 is mapped to another region.

translate

Controls Translate region mapping

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature6.1.0
ValueDescriptionDefault for existing projectsDefault for new projects
0ap-southeast-2, eu-west-2, me-south-1, sa-east-1, and us-east-2 are mapped to other regions.
1ap-southeast-2, eu-west-2, and us-east-2 are mapped to other regions.

project

Enables support for overrides, prevents using unsupported versions of the CLI with overridden resources

overrides

Enables support for overrides

TypeAddedDeprecation dateDeprecatedRemoval dateRemoved
Feature7.3.0
ValueDescriptionDefault for existing projectsDefault for new projects
trueThe CLI ignores the value of this flag
falseThe CLI ignores the value of this flag