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
    }
  }
}

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

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

graphQLTransformer

Feature Flag related to GraphQL Transformer

addMissingOwnerFields

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

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.

validateTypeNameReservedWords

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

useExperimentalPipelinedTransformer

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

enableIterativeGsiUpdates

Enable multiple GSI updates through iterative incremental deployments.

secondaryKeyAsGSI

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

skipOverrideMutationInputTypes

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

transformerVersion

Sets which version of the GraphQL Transformer will be used

suppressSchemaMigrationPrompt

Prevent the CLI from prompting for schema migration

securityEnhancementNotification

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

showFieldAuthNotification

Adds a notification of @auth security change.

useSubUsernameForDefaultIdentityClaim

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

useFieldNameForPrimaryKeyConnectionField

Changes the naming convention for primary key connection fields.

enableAutoIndexQueryNames

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

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.

shouldDeepMergeDirectiveConfigDefaults

Performs a deep merge with default directives and custom directives.

populateOwnerFieldForStaticGroupAuth

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

subscriptionsInheritPrimaryAuth

Toggles whether subscriptions will inherit related authorization when relational fields are set as required

frontend-ios

Feature Flag related to iOS projects

enableXcodeIntegration

Automatically add DataStore / API models to the Xcode project.

auth

Feature Flag related to auth

enableCaseInsensitivity

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

useInclusiveTerminology

Toggles terminology used for allow and deny lists.

breakCircularDependency

Toggles the creation of auth triggers

forceAliasAttributes

Forces the use of aliasAttributes with Cognito rather than usernameAttributes

useEnabledMfas

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

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

useDocsGeneratorPlugin

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

useTypesGeneratorPlugin

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

cleanGeneratedModelsDirectory

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

retainCaseStyle

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

addTimestampFields

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

enableDartNullSafety

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

handleListNullabilityTransparently

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

emitAuthProvider

Adds auth provider details to iOS models

generateIndexRules

Adds key/index details to iOS models

generateModelsForLazyLoadAndCustomSelectionSet

Generate models for lazy loading and custom selection set

latestRegionSupport

Feature Flags related to region mapping support.

comprehend

Controls Comprehend region mapping

pinpoint

Controls Pinpoint region mapping

rekognition

Controls Rekognition region mapping

textract

Controls Textract region mapping

transcribe

Controls Transcribe region mapping

translate

Controls Translate region mapping

project

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

overrides

Enables support for overrides