Local sandbox
The local sandbox runs the storefront in a development environment before changes are pushed to Amplify Hosting. The Next.js process runs locally. The backend is an isolated Amplify Gen 2 sandbox in your AWS account: AppSync, DynamoDB, Cognito, Lambda, and S3. That stack is separate from the Hosting environment that serves customers.
AWS documents this Gen 2 workflow, including per-developer sandboxes, in the video below.
Prerequisites
| Tool | Requirement | Reference |
|---|---|---|
| Node.js | 20 or newer. | nodejs.org |
| npm | Bundled with the Node.js install. | Downloading and installing Node.js and npm |
| AWS CLI | Credentials that can create resources in the target account. | Installing or updating the AWS CLI, then aws configure |
Quickstart
Two terminals. The sandbox process stays in the foreground in the first terminal.
1. Install
From the project directory created in Unzip and repository. Replace the path with the local working directory:
cd /path/to/your-project
npm install
.env is optional. It supplies fallbacks for the Blog Content API and SMTP when those values are unset in the admin:
cp .env.example .env
Payment credentials are set under System → Payment Settings. See System and global settings.
2. Sandbox
In the first terminal:
npm run sandbox
Continue when the process reports the sandbox is ready. Keep this process in the foreground. The command reference is Use cloud sandbox in dev environment.
3. Storefront
In a second terminal, from the same project directory:
cd /path/to/your-project
npm run dev
Open http://localhost:3000. The app redirects to a locale prefix, for example http://localhost:3000/en.
On a new sandbox with an empty Cognito user pool, create the first administrator at http://localhost:3000/en/setup. The session then opens http://localhost:3000/en/admin. If the user pool already contains an account, the setup route is disabled. Create an administrator in the Cognito console, or under Admin → Users after sign-in.
Under the Hood
npm install installs @aws-amplify/backend-cli as a project dependency. npm run sandbox invokes that local CLI. A separate global install is unnecessary.
| Behavior | Detail |
|---|---|
| Environment | Loads .env when the file is present. |
| Command | npx ampx sandbox --identifier amplify-shop |
| Identifier | Fixed name amplify-shop. Each workstation in that AWS account targets the same sandbox stack. |
| Watch | Redeploys when files under amplify/ change. |
| Output | Writes amplify_outputs.json at the repository root. The storefront reads this file. |
| Scope | One sandbox process at a time. The stack is independent of the Amplify Hosting backend. |
Branches
main is the production branch connected in Launch to Amplify. Each push deploys the customer store.
The sandbox identifier is independent of the checked-out Git branch. Two concurrent npm run sandbox processes in the same AWS account share the amplify-shop stack.
| Branch | Runtime | Role |
|---|---|---|
| Short-lived feature branch | Local sandbox and npm run dev | Implementation and local verification. |
staging | Second Amplify Hosting branch, with a dedicated backend and URL | Shared deployment and functional testing. |
main | Production Hosting branch and the custom domain | Customer traffic. Merge from staging after verification. |
Connect staging in the Amplify console with the same repository flow as main. That branch receives a separate backend, so orders and accounts remain isolated from production. Branch access control is Hosting → Access control. See Custom domain and security.
A single-operator deployment can omit staging and push to main after sandbox verification.
Verification
| Component | Expected result |
|---|---|
| Storefront | http://localhost:3000 serves the storefront. |
| Admin | http://localhost:3000/en/admin is available after setup or sign-in. |
| Sandbox | The first terminal remains in the foreground, and amplify_outputs.json exists at the repository root. |
| Mock checkout | Enable Mock under System → Payment Settings, then complete a test order at http://localhost:3000/en/checkout. Disable Mock before production traffic. |
| Configure SMTP and IMAP under System → Email Settings. Procedure: System and global settings. |
References
| Guide | Scope |
|---|---|
| Use cloud sandbox in dev environment | Official npx ampx sandbox procedure. |
| nodejs.org | Node.js 20 or newer. |
| Downloading and installing Node.js and npm | npm bundled with Node.js. |
| Installing or updating the AWS CLI | AWS CLI install. |
aws configure | Local credential profile. |
Next step
Import a catalog from Sample data, then configure public languages in Storefront locales.