Setting the file. One moment.
Subchapter 130.11
references/scaffolding.mdMarkdown6 KBView on GitHub
Prerequisites: Node.js ^18.19.0 || ^20.6.0 || >=22, npm, and AWS credentials configured.
Use official starter templates — hand-crafted structures can break Amplify Hosting deployment detection.
git clone <TEMPLATE_URL> my-app && cd my-app && rm -rf .git && git init && npm install| Framework | Template URL |
|---|---|
| React (Vite) | https://github.com/aws-samples/amplify-vite-react-template |
| Next.js (App Router) | https://github.com/aws-samples/amplify-next-template |
| Next.js (Pages Router) | https://github.com/aws-samples/amplify-next-pages-template |
| Vue | https://github.com/aws-samples/amplify-vue-template |
| Angular | https://github.com/aws-samples/amplify-angular-template |
For existing web projects, add Amplify Gen2 without overwriting application code. You SHOULD use the create command for automatic setup:
npm create amplify@latest -yUse the -y flag for non-interactive execution — without it, the command
prompts interactively and hangs in agent/CI environments. This
scaffolds the amplify/ directory and installs backend dependencies.
For monorepos or custom build pipelines where the create command conflicts, install manually:
npm install --save-dev @aws-amplify/backend@latest @aws-amplify/backend-cli@latest typescriptNote:
aws-cdk-libandconstructsare peer dependencies — npm 7+ installs them automatically. If using--legacy-peer-deps, install them explicitly.
Then create amplify/backend.ts:
import { defineBackend } from '@aws-amplify/backend';
defineBackend({});Install the frontend library:
npm install aws-amplifyNext.js SSR:
npm create amplify@latestdoes NOT install@aws-amplify/adapter-nextjs. Add manually for server-side rendering:npm install @aws-amplify/adapter-nextjs
npx --yes create-expo-app@latest my-app
cd my-app
npm create amplify@latest -y
npm install aws-amplify @aws-amplify/react-native @react-native-async-storage/async-storage react-native-get-random-valuesnpx --yes @react-native-community/cli init MyApp --pm npm
cd MyApp
npm create amplify@latest -y
npm install aws-amplify @aws-amplify/react-native @react-native-async-storage/async-storage react-native-get-random-values
npx --yes pod-install # iOS onlyflutter create --platforms ios,android my_app
cd my_app
npm create amplify@latest -yAdd dependencies to pubspec.yaml:
dependencies:
amplify_flutter: ^2.0.0
amplify_auth_cognito: ^2.0.0Then run flutter pub get.
Do not create the Xcode project from the CLI — assume an existing Xcode project is open in Xcode.
.xcodeproj lives), run:
npm create amplify@latest -yhttps://github.com/aws-amplify/amplify-swift (Up to Next Major Version).amplify_outputs.json to the Xcode project (drag into navigator,
check “Copy items if needed”).Do not create the Android project from the CLI — assume an existing Android Studio project.
In the project root, run: npm create amplify@latest -y
Add dependencies to app/build.gradle.kts:
dependencies {
implementation("com.amplifyframework:core:2.+")
implementation("com.amplifyframework:aws-auth-cognito:2.+")
}Copy amplify_outputs.json into app/src/main/res/raw/.
For mobile projects, this step must be completed before the app can build. Run the sandbox before opening the mobile project.
WARNING: After scaffolding, run npx ampx sandbox --once
(or npx ampx sandbox for local dev) before npm run dev. This
generates amplify_outputs.json, which the frontend imports at build time.
Without it, the app fails to compile because
import outputs from '../amplify_outputs.json' resolves to nothing.
# Terminal 1 — Start sandbox (watch mode, auto-deploys on changes)
npx ampx sandbox
# Terminal 2 — Start dev server (requires amplify_outputs.json from sandbox)
npm run devSandbox modes:
npx ampx sandbox — Watch mode, continuously deploys changes (recommended for development)npx ampx sandbox --once — Single deployment then exits (for CI/CD or initial setup)First time: Run
npx ampx sandboxand wait for it to generateamplify_outputs.jsonbefore starting your dev server.
amplify_outputs.json is gitignored — see deployment.md for generation details.
The sandbox stack name is derived from your project’s root package.json name. If you clone a template, change the name to avoid collisions:
{ "name": "my-unique-app-name" }Running multiple projects with the same name simultaneously causes one sandbox to overwrite another.
npm create amplify@latest -y after the framework scaffold
is the most common mistake — without it, there is no amplify/ directory.@react-native-async-storage/async-storage — the
Amplify SDK uses it for token persistence and will fail at runtime without it.