aws-amplify/amplify-backend

Home to all tools related to Amplify's code-first DX (Gen 2) for building fullstack apps on AWS

Reporting Bugs / Feature Requests

Note aws-amplify 6 has been released. If you are looking for upgrade guidance click here

AWS Amplify is a JavaScript library for frontend and mobile developers building cloud-enabled applications

AWS Amplify provides a declarative and easy-to-use interface across different categories of cloud operations. AWS Amplify goes well with any JavaScript based frontend workflow and React Native for mobile developers.

Our default implementation works with Amazon Web Services (AWS), but AWS Amplify is designed to be open and pluggable for any custom backend or service.

Visit our documentation site to learn more about AWS Amplify. Please see the Amplify JavaScript page for information around the full list of features we support.

• Contributing

Features

Category	AWS Provider	Description
Authentication	Amazon Cognito	APIs and Building blocks to create Authentication experiences.
Analytics	Amazon Pinpoint	Collect Analytics data for your application including tracking user sessions.
REST API	Amazon API Gateway	Sigv4 signing and AWS auth for API Gateway and other REST endpoints.
GraphQL API	AWS AppSync	Interact with your GraphQL or AWS AppSync endpoint(s).
DataStore	AWS AppSync	Programming model for shared and distributed data, with simple online/offline synchronization.
Storage	Amazon S3	Manages content in public, protected, private storage buckets.
Geo (Developer preview)	Amazon Location Service	Provides APIs and UI components for maps and location search for JavaScript-based web apps.
Push Notifications	Amazon Pinpoint	Allows you to integrate push notifications in your app with Amazon Pinpoint targeting and campaign management support.
Interactions	Amazon Lex	Create conversational bots powered by deep learning technologies.
PubSub	AWS IoT	Provides connectivity with cloud-based message-oriented middleware.
Internationalization	---	A lightweight internationalization solution.
Cache	---	Provides a generic LRU cache for JavaScript developers to store data with priority and expiration settings.
Predictions	Various*	Connect your app with machine learning services like NLP, computer vision, TTS, and more.

• Predictions utilizes a range of Amazon's Machine Learning services, including: Amazon Comprehend, Amazon Polly, Amazon Rekognition, Amazon Textract, and Amazon Translate.

Getting Started

AWS Amplify is available as aws-amplify on npm.

To get started pick your platform from our Getting Started home page

Notice:

Amplify 6.x.x has breaking changes. Please see the breaking changes on our migration guide

Amplify 5.x.x has breaking changes. Please see the breaking changes below:

• If you are using default exports from any Amplify package, then you will need to migrate to using named exports. For example:

  - import Amplify from 'aws-amplify';
  + import { Amplify } from 'aws-amplify'
  
  - import Analytics from '@aws-amplify/analytics';
  + import { Analytics } from '@aws-amplify/analytics';
  // or better
  + import { Analytics } from 'aws-amplify';
  
  - import Storage from '@aws-amplify/storage';
  + import { Storage } from '@aws-amplify/storage';
  // or better
  + import { Storage } from 'aws-amplify';

• Datastore predicate syntax has changed, impacting the DataStore.query, DataStore.save, DataStore.delete, and DataStore.observe interfaces. For example:

  - await DataStore.delete(Post, (post) => post.status('eq', PostStatus.INACTIVE));
  + await DataStore.delete(Post, (post) => post.status.eq(PostStatus.INACTIVE));
  
  - await DataStore.query(Post, p => p.and( p => [p.title('eq', 'Amplify Getting Started Guide'), p.score('gt', 8)]));
  + await DataStore.query(Post, p => p.and( p => [p.title.eq('Amplify Getting Started Guide'), p.score.gt(8)]));

  • To use the new syntax with 5.x.x you may need to rebuild your Datastore models with the latest version of Amplify codegen. To do this:
    • Upgrade the Amplify CLI
      • npm install -g @aws-amplify/cli
    • Re-generate your models with Amplify codegen
      • amplify codegen models

• Storage.list has changed the name of the maxKeys parameter to pageSize and has a new return type that contains the results list. For example:

  - const photos = await Storage.list('photos/', { maxKeys: 100 });
  - const { key } = photos[0];
  
  + const photos = await Storage.list('photos/', { pageSize: 100 });
  + const { key } = photos.results[0];

• Storage.put with resumable turned on has changed the key to no longer include the bucket name. For example:

  - let uploadedObjectKey;
  - Storage.put(file.name, file, {
  -   resumable: true,
  -   // Necessary to parse the bucket name out to work with the key
  -   completeCallback: (obj) => uploadedObjectKey = obj.key.substring( obj.key.indexOf("/") + 1 )
  - }
  
  + let uploadedObjectKey;
  + Storage.put(file.name, file, {
  +   resumable: true,
  +   completeCallback: (obj) => uploadedObjectKey = obj.key
  + }

• Analytics.record no longer accepts string as input. For example:

  - Analytics.record('my example event');
  + Analytics.record({ name: 'my example event' });

• The JS export has been removed from @aws-amplify/core in favor of exporting the functions it contained.

• Any calls to Amplify.Auth, Amplify.Cache, and Amplify.ServiceWorker are no longer supported. Instead, your code should use the named exports. For example:

  - import { Amplify } from 'aws-amplify';
  - Amplify.configure(...);
  - // ...
  - Amplify.Auth.signIn(...);
  
  + import { Amplify, Auth } from 'aws-amplify';
  + Amplify.configure(...);
  + // ...
  + Auth.signIn(...);

Amplify 4.x.x has breaking changes for React Native. Please see the breaking changes below:

• If you are using React Native (vanilla or Expo), you will need to add the following React Native community dependencies:
  • @react-native-community/netinfo
  • @react-native-async-storage/async-storage

// React Native
yarn add aws-amplify amazon-cognito-identity-js @react-native-community/netinfo @react-native-async-storage/async-storage
npx pod-install

// Expo
yarn add aws-amplify @react-native-community/netinfo @react-native-async-storage/async-storage

Amplify 3.x.x has breaking changes. Please see the breaking changes below:

• AWS.credentials and AWS.config don’t exist anymore in Amplify JavaScript.
  • Both options will not be available to use in version 3. You will not be able to use and set your own credentials.
  • For more information on this change, please see the AWS SDK for JavaScript v3
• [email protected] has been removed from [email protected] in favor of version 3 of aws-sdk-js. We recommend to migrate to aws-sdk-js-v3 if you rely on AWS services that are not supported by Amplify, since aws-sdk-js-v3 is imported modularly.

If you can't migrate to aws-sdk-js-v3 or rely on [email protected], you will need to import it separately.

• If you are using exported paths within your Amplify JS application, (e.g. import from "@aws-amplify/analytics/lib/Analytics") this will now break and no longer will be supported. You will need to change to named imports:

  import { Analytics } from 'aws-amplify';

• If you are using categories as Amplify.<Category>, this will no longer work and we recommend to import the category you are needing to use:

  import { Auth } from 'aws-amplify';

DataStore Docs

For more information on contributing to DataStore / how DataStore works, see the DataStore Docs

amplify-backend's Issues

consider moving create-amplify tests into e2e suite

Once we have an e2e suite, consider moving the "unit tests" from create-amplify into this suite. These these are more heavyweight than a typical unit test and require more overhead

Create test mock/stub package for platform interfaces

Feature vertical packages need a way to write tests that inject test implementations of platform types into their packages. Currently many of these tests directly import the platform implementation of these classes but this leads to overexposing implementation details just for testing.

Instead we should have a "backend-test-utils" or similarly named package that provides stub implementations of platform interfaces for feature verticals to test with

For hotswap, hotswappable changes in nested stacks causes the full CFN deployment

For example, if I change a resolver in a nested stack, the API stack would need to update which triggers a fallback deployment. In other environments, it would tell me that resolver isn’t hotswappable, hence it needs to fallback to full CFN deployment.

Could not perform a hotswap deployment, because the CloudFormation template could not be resolved: We don’t support attributes of the ‘AWS::CloudFormation::Stack’ resource. This is a CDK limitation. Please report it at https://github.com/aws/aws-cdk/issues/new/choose
Falling back to doing a full deployment

`npm create amplify` should execute `npm init -y` if `package.json` does not exist rather than `npm init`

use top-level client config format

As defined here: https://docs.amplify.aws/lib/client-configuration/configuring-amplify-categories/q/platform/js/

Rename methods on OutputStorageStrategy

Per this comment rename OutputStorageStrategy.storeOutput => OutputStorageStrategy.addOutput

Also consider renaming the type to BackendOutputStorageStrategy because we refer to this output as "BackendOutput" in other places

sandbox should use `--no-rollback`

This flag prevents CFN from rolling back failed deployments. This is useful in a watch / sandbox context as ephemeral failed states are expected and this allows subsequent updates to be deployed sooner.

function build command should execute using bash shell

The current function build command does not execute using a shell which means that any bash specific features cannot be used in build scripts (which is pretty much everything except just calling an executable). We should update the execa call to run using bash so that build scripts can use expected scripting syntax

Store construct output when not using `amplify.Backend` wrapper

When using amplify.Backend wrapper the output necessary for client config generation is stored by amplify.Backend.

import { amplify, Stack } from 'aws-cdk-lib'
import { Auth } from './auth.ts'
import { Data } from './data.ts' // new Data(this, ..., {...})


export class HelloCdkStack extends Stack {
  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
                              //^ --stack
    super(scope, id, props);

    const backend = new amplify.Backend(this, "my-amplify-backend", {
      auth: Auth,
      data: Data
    })
  }
}

The outputs for client config generation should also be stored using Amplify constructs without amplify.Backend.

import { amplify } from 'aws-cdk-lib'

// TK add CDK stack names
export class HelloCdkStack extends Stack {
  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
                              //^ --stack
    super(scope, id, props);
    const data = new amplify.Data(this, "my-api", {
      schema: `...`,
      authorizationModes: [/*...*/]
    })
  }
}

When CDK destroy is called on Sandbox, the client config remains

When the customer stops the sandbox watch process and choses to destroy their sandbox:

[Sandbox] Watching for file changes...
^C[Sandbox] Shutting down
? Would you like to delete all the resources in your sandbox environment (This cannot be undone)? y
[Sandbox] Deleting all the resources in the sandbox environment...
[Sandbox] Executing cdk destroy
amplify-simple-react-srquinn-sandbox: destroying... [1/1]

 ✅  amplify-simple-react-srquinn-sandbox: destroyed

[Sandbox] Finished deleting.

The amplifyconfiguration.json file remains where it was produced. Since the resources associated with this file no longer exist, it would be best to remove this file from the project as well.

`create-amplify` should prompt whether to install dependencies

During create-amplify flow, CLI should prompt whether to install project dependencies, printing the intended install command in the event the user opts not to install

Amplify will run the following command:
If you skip this step, you can always run it yourself later

╭──────────────────────────────────────────────────────────╮
│ npm add -D [email protected] && \                │
| npm add [email protected]                                │
╰──────────────────────────────────────────────────────────╯

? Continue? › (Y/n)

Implement translation layer between stack outputs and client config files

Current client config generation is implemented as a passthrough of stack outputs. We need to implement the translation layer to actually create the frontend config files

revisit backend-deployer deployProps

Based on feedback here: #126 (comment)
We may want to change this API to provide a higher level of abstraction

Reconsider how stack SSM parameter is generated

See discussion and code comment here

Installation erros after running `npm create amplify`

Implement secret custom resource for secret inheritance and override

[Sandbox] Stream output and error logs instead of printing at the end

Using node's child process with promisify causes the stdio and stdin to be available after the executing of the command and not streamed in the code below

https://github.com/aws-amplify/samsara-cli/blob/40c9f108ebe7ea88bdd56fa1a64803512d89d549/packages/sandbox/src/sandbox.ts#L99-L119

This is currently done to use mocks available from node:test which currently doesn't allow mocking exported functions such as execa library.

sandbox crashes on synth / deploy failure

If the synth or deploys fails during sandbox, this causes the entire sandbox process to crash.

Instead we should catch these errors, print them, but keep the sandbox watcher running.

Repro:

1. create a test project
2. start sandbox
3. update the test project to have a syntax error, or some other issue that would cause the deployment to fail
4. observe that sandbox crashes after picking up the faulty update

`create-amplify` should install dependencies using the package manager it was called with

npm create amplify should prompt to install dependencies and print a command if the developer opts to not install using the create* flow

pnpm create amplify, yarn create amplify, and bun create amplify should prompt to install with the respective package manager.

When destroying resources in sandbox - the resources stay in my account such as the Cognito userpool

When in Sandbox and after existing out to destroy my resources, they are not being completely removed from my account. We should not "retain" resources once they are destroyed from Sandbox.

run tests using node instead of tsx

Now that we are building our test code, we don't need to run our tests with tsx. In some preliminary testing, running with node natively speeds up test execution significantly. There's a bit of work to update some test paths and build the integration tests cases.

Unable to install vNext tooling into existing Amplify vClassic project

1. Open existing Amplify project with amplify directory

2. npm create amplify@alpha

3. Error /Users/kevold/work/dynamic-amplify-projects/202211021107-amplify-cna-nextjs-13-launch-blog-post-demo/amplify already exists. Either delete this file/directory or initialize the project in a different location.

Impact: Developers will not be able to install vNext tooling into existing Amplify vClassic projects
AC: Developers can install vNext tooling into existing Amplify vClassic projects

sandbox should ensure cdk bootstrap

When running amplify sandbox we should check the CDK Bootstrap SSM parameter before trying a deployment. If the account/region is not bootstrapped, we should run cdk bootstrap before doing a deployment.

When initiating a new project gitignore file is not excluding out directory and frontend config

When initiating a new project gitignore file is not excluding out directory and frontend config.

CDK artifacts to be stored in `.amplify/`

Currently CDK artifacts are stored in their default top-level cdk.out directory. Instead, artifacts should be stored in a top-level .amplify/ directory.

./my-project
|- .amplify/
|- amplify/
|- .gitignore
|- package.json

`--platform` flag seems to be ignored when running client-config generation

1. npx amplify generate config --stack testing-stack --platform dart

Expected:

• amplifyconfiguration.dart file is created

Actual:

• amplifyconfiguration.js file is created

`npx sandbox delete` gives unclear error message

renbran@50ed3c3831ed new-alpha % amplify sandbox delete
🛑 The "delete" command does not expect additional arguments.
Perhaps you meant to use the "remove" command instead of "delete"?

Resolution: If you intend to delete this project and all backend resources, try the "delete" command again without any additional arguments.
Learn more at: https://docs.amplify.aws/cli/project/troubleshooting/

Session Identifier: e7242a62-a2d3-4c64-8a78-d963f03d94de
renbran@50ed3c3831ed new-alpha % npx amplify sandbox remove
amplify sandbox

Starts sandbox, watch mode for amplify deployments

Commands:
  amplify sandbox delete  Deletes sandbox environment

Options:
  --version     Show version number                                    [boolean]
  --help        Show help                                              [boolean]
  --dirToWatch  Directory to watch for file changes. All subdirectories and file
                s will be included. defaults to the current directory.  [string]
  --exclude     An array of paths or glob patterns to ignore. Paths can be relat
                ive or absolute and can either be files or directories   [array]
  --name        An optional name to distinguish between different sandbox enviro
                nments. Default is the name in your package.json        [string]
  --out         A path to directory where config is written. If not provided def
                aults to current process working directory.             [string]

Unknown command: remove

Told me that I shouldn't add any additional arguments but I didn't add them. Also suggested to run remove when remove isn't a valid command.

`aws-amplify` package should be in `dependencies` rather than `devDependencies` in package.json

1. npm create amplify
2. open package.json

Expected:

• aws-amplify is part of dependencies

Actual:

• aws-amplify is part of devDependencies

The client config writer uses ES module syntax which makes the config file unusable in CommonJS

The config writer generates the .js config file using ES module syntax. This makes the config file unusable in a CommonJS environment. E.g. the next.config.js of Next.js. This issue blocks some use cases with Amplify JS V6.

Related issue in Amplify CLI: aws-amplify/amplify-cli#13174

https://github.com/aws-amplify/samsara-cli/blob/c1ce1230185dbb242faa0dd144036281e6918984/packages/client-config/src/client-config-writer/client_config_writer.ts#L20

Use package exports to namespace concerns within packages

See #43 (comment)

There is some issue with our current TS/Node setup that is not building when trying to use the exports field in package.json files.

Using this feature would allow us to create namespaces for different functionality. There may also be some missing feature in TS that we need to wait on before we will be able to utilize this properly

Sandbox should only throw CDK errors at debug level

Today, when a lower level error happens in sandbox the entire stack trace is exposed to the customer. We should capture lower level errors and only expose them on DEBUG level logging to keep default output clean and free from exposing our internal implementation details.

sandbox should perform a deployment on startup

Currently when sandbox starts up, it starts watching files but does not perform a deployment until a file change is detected. Instead, sandbox should start the file watcher and also kick off an initial deployment. This allows sandbox to "catch up" to any changes that were made while sandbox was not watching files

`create-amplify` should prompt for the project directory

> pwd
/Users/josef/my-projects/

> npm create amplify

Welcome to AWS Amplify!

? Where should we create your new project? ./my-app

Sandbox does not catch SIGINT when a deployment is in progress

Calling SIGNIT on the Sandbox process while a deployment is in progress results in an uncaught exception. An option for the DX would be to warn the developer and confirm before sending SIGINT.

@aws-amplify/backend missing dep on @aws-amplify/plugin-types

@aws-amplify/backend exposes some types from @aws-amplify/plugin-types in it's API. For consumers of @aws-amplify/backend to get proper typings, @aws-amplify/plugin-types needs to be a peer dep of the backend package.

create lint rule to disallow arrow function class methods

In some cases they are necessary, but in general we should prefer "normal" method syntax

Strategy for E2E tests to get AWS credentials for making service calls

For critical path scenarios, we need some E2E tests that make real calls to AWS services. To do this, we need a secure way to get test credentials to our test runner

E2E test for backend secret mechanism

To write an integration test for backend secret.
This task has dependency on Auth construct milestone 2 to support secret fields.

Sandbox watch process is triggered on ignored files

The watch process is currently picking up changes on node_modules cache which causes unnecessary deployment attempts on changes outside of the /amplify folder.

We need a requirement here around how to handle "ignoring" files. We can either respect gitignore or if that is too exclusive, we might need to consider an amplify specific ignore file.

`--out` flag in `amplify generate config` seems to lead to failure

renbran@50ed3c3831ed stack-test % npx amplify generate config --stack amplify-stack-test-sandbox --out app/
amplify generate config

Generates client config

Stack identifier
  --stack  A stack name that contains an Amplify backend                [string]

Project identifier
  --appId   The Amplify App ID of the project                           [string]
  --branch  A git branch of the Amplify project                         [string]

Options:
  --version  Show version number                                       [boolean]
  --help     Show help                                                 [boolean]
  --out      A path to directory where config is written. If not provided defaul
             ts to current process working directory.                   [string]

Error: Unknown client config file extension
    at ClientConfigWriter.writeClientConfig (file:///Users/renbran/Projects/beast-unleashed/node_modules/@aws-amplify/client-config/lib/client-config-writer/client_config_writer.js:23:23)
    at generateClientConfigToFile (file:///Users/renbran/Projects/beast-unleashed/node_modules/@aws-amplify/client-config/lib/generate_client_config_to_file.js:9:30)
    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
    at async ClientConfigGeneratorAdapter.generateClientConfigToFile (file:///Users/renbran/Projects/beast-unleashed/node_modules/@aws-amplify/backend-cli/lib/commands/generate/config/client_config_generator_adapter.js:18:9)
    at async Object.handler (file:///Users/renbran/Projects/beast-unleashed/node_modules/@aws-amplify/backend-cli/lib/commands/generate/config/generate_config_command.js:43:9)

sandbox stuck in loop when synth produces files that are being watched

If the CDK synth process produces or modifies a file that is part of what is being watched by sandbox, this causes sandbox to get stuck in a infinite loop of deployments. For example, a function build process may produce compiled function assets.

We may want to have logic such that all output paths are computed relative to a gitignored directory like .amplify-build and this directory is always excluded from sandbox watch.

implement --name param on sandbox

This param should allow developers to specify their own disambiguator in the sandbox stack name instead of the default os.userInfo().username that is used

Figure out project and environment name for sandbox

Determine how project and environment name will be identified for sandbox. Questions

1. What are the defaults if user doesn't provide anything?
2. How will users be able to override them?
3. Can a user have multiple sandbox environments?

sandbox isn't passing model introspection information into the the amplifyconfiguration.js file

npx amplify sandbox generates the client config correctly but doesn't yet pass in the required data for model introspection to be used in TypeBeast

Package naming release blockers

This ticket is to track package naming changes that we need to make when dropping the alpha tag for our release.

1. Exit prerelease mode in changesets (see https://github.com/changesets/changesets/blob/main/docs/prereleases.md)
2. Update the install command in create_amplify.test.ts to run the non-alpha version of create-amplify

Get product requirements on function construct

Several open questions from this thread regarding how we want to support building functions. We need to have a discussion with product around some long-term decisions like relying on Docker for builds, using CDK function build logic vs our own logic, async vs sync building, etc.

Consider shared utility types package

Per this comment we may want to refactor some utility types into a shared location if we end up needing them in multiple places

sandbox should generate client config as part of watch loop

sandbox should generate a TypeScript config when in TypeScript projects and a JS config when in non-TypeScript projects

1. npx create-next-app ...
2. Pick TypeScript "Yes"
3. npm create amplify@alpha
4. npx amplify sandbox

Expected:

• See a amplifyconfiguration.ts file

Actual:

• See a amplifyconfiguration.js file

Sandbox should ignore files that are in .gitignore

Sandbox watch process is currently picking up changes in .gitignored files. Ignored files should be filtered out of the watch process.