Sandbox features

Sandbox environments include additional features for managing secrets, deploying multiple sandboxes, config generation, and client codegen for your Amplify app.

Secure secrets in your sandbox

Gen 2 offers secure secret storage to manage sensitive data like API keys and database credentials. Secrets are similar to environment variables, but they are encrypted AWS Systems Manager (SSM) Parameter Store key value pairs. Secrets are stored in AWS Parameter Store with the following naming convention: /amplify/<package.json#name>/<sandbox-name>/<key-name>.

Set secrets

You can add secrets while running your cloud sandbox with the following command:

1npx amplify sandbox secret set foo
2? Enter secret value: ###
3Done!
4
5> npx amplify sandbox secret set bar
6? Enter secret value: ###
7Done!

Access secrets

Once you have set a secret, you can access the values in code by calling the secret() function. The example below shows how to set up social sign-in with authentication in your app. Depending on your environment, Amplify will automatically load the correct secret value with no extra configuration.

1import { defineAuth, secret } from '@aws-amplify/backend';
2
3export const auth = defineAuth({
4  loginWith: {
5    email: true,
6    externalProviders: {
7      facebook: {
8        clientId: secret('foo'),
9        clientSecret: secret('bar')
10      }
11    }
12  }
13});

Retrieve secrets

To get the value of a secret from the cloud, run the following command in your terminal:

1npx amplify sandbox secret get foo
2 name: foo
3 version: 1
4 value: 123
5 lastUpdated: Mon Nov 13 2023 22:19:12 GMT-0800 (Pacific Standard Time)

Remove secrets

To remove a secret from the cloud, run the following command in your terminal:

1npx amplify sandbox secret remove foo

Work with multiple AWS profiles

Sometimes you might have multiple AWS profiles set up locally. To run amplify sandbox secret commands, use the --profile flag to deploy to a specific profile. For example, let's say you have two AWS profiles setup locally - default and work. To add secrets to the work profile, run the following command in your terminal:

1npx amplify sandbox secret set foo --profile work

Multiple sandboxes per app

You can create multiple cloud sandbox environments for each app if you want to keep persistent sandbox environments up and running to test against. First, run the following command in the terminal:

1npx amplify sandbox --name s1

Once the deployment completes, exit sandbox s1 and run the following command in the terminal:

1npx amplify sandbox --name s2

After successful deployment, sandboxes s1 and s2 will be ready. Pick sandbox s1 or s2 to activate. You can switch between them but only one can be running at a time.

Generate client config

The client config, or amplifyconfiguration.json, is a file that contains the configuration strings for interacting with AWS resources specific to an environment. It is required by the Amplify client libraries in order for the library APIs to connect to the backend resources. By default, the cloud sandbox generates the client configuration file at the root of the project (e.g. @/amplifyconfiguration.json). If you want to place the file at a different path (for example, monorepo or Android app) run the following command in the terminal:

1npx amplify sandbox --config-out-dir ./path/to/config --format ["mjs", "json", "json-mobile", "ts", "dart"]

Alternatively, if you want to generate the config for a branch environment to test against, run the following command in the terminal.

1npx amplify generate config --app-id <AMPLIFY_APP_ID> --branch main --format ["mjs", "json", "json-mobile", "ts", "dart"] out-dir ./path/to/config

Generate client codegen

"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 manually code them.

Once your sandbox completes a deployment, you can run the following command in the terminal to generate client code specific to your needs:

1npx amplify generate graphql-client-code
2--format [choices: "modelgen", "graphql-codegen", "introspection"]

Delete a sandbox

You can delete a cloud sandbox environment in several ways:

1. Ctrl+C your sandbox and choose to delete resources.
2. Run npx amplify sandbox delete or npx amplify sandbox delete --name
3. Visit the Amplify console and delete sandboxes.