{"owner":"aws-amplify","repo":"amplify-js","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md","CLAUDE.md"],"skills":{"AGENTS.md":"# AGENTS.md\n\nGuidance for AI coding agents working in the **AWS Amplify JS** monorepo. Read this before making changes.\n\n## Repository Overview\n\nAmplify JS is a **Yarn + Turborepo** monorepo. Every package lives under `packages/<name>/`, each with its own `src/` and `package.json`. Packages are published under the `@aws-amplify/*` scope (plus the umbrella `aws-amplify` package).\n\nKey packages:\n\n| Package | Purpose |\n|---|---|\n| `@aws-amplify/core` | Shared runtime: config singleton, Hub, utils |\n| `@aws-amplify/auth` | Cognito authentication |\n| `@aws-amplify/storage` | S3 storage (client/utils + server/utils split) |\n| `@aws-amplify/api`, `api-graphql`, `api-rest` | API categories |\n| `@aws-amplify/analytics`, `geo`, `interactions`, `notifications`, `predictions`, `pubsub` | Feature categories |\n| `aws-amplify` | Umbrella package re-exporting category APIs |\n| `@aws-amplify/adapter-nextjs` | Next.js server adapter |\n\n## Environment\n\n| Requirement | Version |\n|---|---|\n| Node.js | 24 (pinned in CI; repo has no local `engines`/`.nvmrc`) |\n| Yarn | 1.22.x |\n\n## Build & Test Commands (MANDATORY: use `yarn`)\n\n**Always drive builds/tests/lint through `yarn`. NEVER invoke `tsc`, `eslint`, `jest`, `npx`, or `tsx` directly** — the workspace scripts wire up the correct config and dependency graph. Single-package targeting goes through Turbo's `--filter` (see below).\n\n```bash\n# Install\nyarn\n\n# Build\nyarn build                              # all packages\nyarn turbo run build --filter=@aws-amplify/auth   # single package (+ its deps)\n\n# Test\nyarn test                               # full suite (use before final confirmation)\nyarn turbo run test --filter=@aws-amplify/auth    # single package\n\n# Lint\nyarn lint                               # lint all packages\nyarn turbo run lint --filter=@aws-amplify/auth    # single package\n\n# Bundle size\nyarn test:size                          # size-limit check (only runs for packages that define it)\nyarn test:size --why                    # debug regression (Statoscope)\n\n# Watch mode for local dev\nyarn build:watch\nyarn link-all                           # make all packages linkable\n\n# Nuclear clean\ngit clean -xdf\n```\n\nRun `yarn` from the **monorepo root or a package root**. During implementation you may narrow with file/suite/test filters, but always run the full `test` / `lint` / `build` for final confirmation.\n\n> **Single-package targeting must go through Turbo directly** — `yarn turbo run <task> --filter=@aws-amplify/<pkg>`. Do **not** pass `--filter` to the top-level `yarn build` / `yarn test` scripts: they are compound (`&&`) scripts, so the flag is misrouted to the trailing command and Turbo still runs unfiltered. (`--scope` is a Lerna flag — not valid for Turbo 2.x at all.)\n\n## Testing Conventions\n\n- **Do NOT mock `getConfig` on the Amplify singleton.** Mock the actual underlying modules/functions instead (real Amplify config approach).\n- Write or update unit tests for any added/modified code. Be especially vigilant with shared code (race conditions).\n- Passing unit tests are required for any PR that changes functionality.\n- **Bundle-size (`size-limit`) checks only apply to packages that configure them.** Eight packages declare a `size-limit` key (`aws-amplify`, `core`, `datastore`, `geo`, `interactions`, `predictions`, `pubsub`, `api-graphql`), but `yarn test:size` only exercises the seven that also define a `test:size` script (all of the above except `api-graphql`). Filtering it to a package without size-limit configured (e.g. `auth`, `storage`) is a no-op.\n\n## Code Conventions\n\n- **License headers are required** on source files (enforced by the `license-test` CI check).\n- **Never commit `tsconfig.tsbuildinfo` files.** A stray `packages/*/tsconfig.tsbuildinfo` causes `license-test` failures (`License not found in ...`). Remove it if generated.\n- Preserve existing comments, JSDoc, and logging statements.\n- Follow existing formatting (Prettier + ESLint config are applied via `yarn` scripts).\n\n## Git Hooks (Husky)\n\nThe repo installs Husky hooks that run automatically — an agent committing or pushing will trigger them:\n\n- **`pre-commit`** — runs `lint-staged` (`eslint --fix` on staged `*.ts`/`*.tsx`). Do not bypass with `--no-verify`.\n- **`pre-push`** — runs a **git-secrets** scan and **blocks the push if git-secrets is not installed**. Install and register it before pushing:\n\n```bash\nbrew install git-secrets   # or: apt-get install git-secrets\ngit secrets --register-aws\n```\n\n## Changesets (required for functional changes)\n\n```bash\nyarn changeset\n```\n\nCreates a file in `.changeset/`:\n\n```markdown\n---\n'@aws-amplify/<package>': patch|minor|major\n---\n\n<type>(<scope>): description of the change.\n```\n\n**Skip a changeset** only for docs-only, formatting, or CI-only changes.\n\n## Branch Naming\n\n```\n<scope>/<type>/<description>\n```\n\n- **scope**: category or alias (e.g. `auth`, `storage`, `core`)\n- **type**: `feat` | `fix` | `docs` | `refactor` | `perf` | `test` | `build` | `ci` | `chore` | `revert`\n\nExamples: `auth/fix/refresh-token-race-condition`, `storage/feat/presigned-urls`\n\n## Commit / PR Flow\n\n1. Make changes in `packages/<category>/`.\n2. Add/update unit tests.\n3. Add a changeset (if functional).\n4. Validate: `yarn build` + `yarn test` (+ `yarn test:size` if bundle-sensitive).\n5. Commit with a conventional message: `<type>(<scope>): summary`.\n6. Push and open a PR filling out the template (description, linked issue, validation steps, checklist).\n\n## CI Checks (must pass before merge)\n\n| Check | Validates |\n|---|---|\n| `unit-tests` | Jest suites across packages |\n| `native-unit-tests` | React Native tests |\n| `bundle-size-tests` | Tree-shaken footprint (size-limit) |\n| `license-test` | License headers present |\n| `tsc-compliance-test` | TypeScript compilation |\n| `dependency-review` | No problematic dependencies |\n| `git-secrets-check` | No leaked AWS credentials |\n| `github-actions-test` | CI config validity |\n\nThe `ci - Unit and Bundle tests have passed` gate turns green only when all above pass.\n\n## Maintenance Branch: `v5-stable`\n\nThe `v5-stable` branch hosts Amplify JS v5 maintenance releases (security patches, critical fixes). **Do not apply this document's conventions there** — it uses different tooling (Lerna instead of Turborepo, no changesets, different setup and CI checks).\n\nWhen backporting a fix to v5: branch off `v5-stable`, target the PR at `v5-stable`, and follow the `AGENTS.md` **on that branch** for its specific conventions.\n\n## Do / Don't Summary\n\n**Do**\n- Use `yarn` for everything\n- Add tests + changesets\n- Keep license headers\n- Mock underlying modules, not `Amplify.getConfig`\n\n**Don't**\n- Run `tsc`/`jest`/`eslint`/`npx` directly\n- Commit `tsconfig.tsbuildinfo`\n- Strip existing comments or logging\n","CLAUDE.md":"# CLAUDE.md\n\nThis project's AI agent guidance lives in [AGENTS.md](./AGENTS.md).\n\nPlease read **[AGENTS.md](./AGENTS.md)** for repository structure, build/test commands, code conventions, changeset requirements, and CI checks.\n"},"files":{"AGENTS.md":"# AGENTS.md\n\nGuidance for AI coding agents working in the **AWS Amplify JS** monorepo. Read this before making changes.\n\n## Repository Overview\n\nAmplify JS is a **Yarn + Turborepo** monorepo. Every package lives under `packages/<name>/`, each with its own `src/` and `package.json`. Packages are published under the `@aws-amplify/*` scope (plus the umbrella `aws-amplify` package).\n\nKey packages:\n\n| Package | Purpose |\n|---|---|\n| `@aws-amplify/core` | Shared runtime: config singleton, Hub, utils |\n| `@aws-amplify/auth` | Cognito authentication |\n| `@aws-amplify/storage` | S3 storage (client/utils + server/utils split) |\n| `@aws-amplify/api`, `api-graphql`, `api-rest` | API categories |\n| `@aws-amplify/analytics`, `geo`, `interactions`, `notifications`, `predictions`, `pubsub` | Feature categories |\n| `aws-amplify` | Umbrella package re-exporting category APIs |\n| `@aws-amplify/adapter-nextjs` | Next.js server adapter |\n\n## Environment\n\n| Requirement | Version |\n|---|---|\n| Node.js | 24 (pinned in CI; repo has no local `engines`/`.nvmrc`) |\n| Yarn | 1.22.x |\n\n## Build & Test Commands (MANDATORY: use `yarn`)\n\n**Always drive builds/tests/lint through `yarn`. NEVER invoke `tsc`, `eslint`, `jest`, `npx`, or `tsx` directly** — the workspace scripts wire up the correct config and dependency graph. Single-package targeting goes through Turbo's `--filter` (see below).\n\n```bash\n# Install\nyarn\n\n# Build\nyarn build                              # all packages\nyarn turbo run build --filter=@aws-amplify/auth   # single package (+ its deps)\n\n# Test\nyarn test                               # full suite (use before final confirmation)\nyarn turbo run test --filter=@aws-amplify/auth    # single package\n\n# Lint\nyarn lint                               # lint all packages\nyarn turbo run lint --filter=@aws-amplify/auth    # single package\n\n# Bundle size\nyarn test:size                          # size-limit check (only runs for packages that define it)\nyarn test:size --why                    # debug regression (Statoscope)\n\n# Watch mode for local dev\nyarn build:watch\nyarn link-all                           # make all packages linkable\n\n# Nuclear clean\ngit clean -xdf\n```\n\nRun `yarn` from the **monorepo root or a package root**. During implementation you may narrow with file/suite/test filters, but always run the full `test` / `lint` / `build` for final confirmation.\n\n> **Single-package targeting must go through Turbo directly** — `yarn turbo run <task> --filter=@aws-amplify/<pkg>`. Do **not** pass `--filter` to the top-level `yarn build` / `yarn test` scripts: they are compound (`&&`) scripts, so the flag is misrouted to the trailing command and Turbo still runs unfiltered. (`--scope` is a Lerna flag — not valid for Turbo 2.x at all.)\n\n## Testing Conventions\n\n- **Do NOT mock `getConfig` on the Amplify singleton.** Mock the actual underlying modules/functions instead (real Amplify config approach).\n- Write or update unit tests for any added/modified code. Be especially vigilant with shared code (race conditions).\n- Passing unit tests are required for any PR that changes functionality.\n- **Bundle-size (`size-limit`) checks only apply to packages that configure them.** Eight packages declare a `size-limit` key (`aws-amplify`, `core`, `datastore`, `geo`, `interactions`, `predictions`, `pubsub`, `api-graphql`), but `yarn test:size` only exercises the seven that also define a `test:size` script (all of the above except `api-graphql`). Filtering it to a package without size-limit configured (e.g. `auth`, `storage`) is a no-op.\n\n## Code Conventions\n\n- **License headers are required** on source files (enforced by the `license-test` CI check).\n- **Never commit `tsconfig.tsbuildinfo` files.** A stray `packages/*/tsconfig.tsbuildinfo` causes `license-test` failures (`License not found in ...`). Remove it if generated.\n- Preserve existing comments, JSDoc, and logging statements.\n- Follow existing formatting (Prettier + ESLint config are applied via `yarn` scripts).\n\n## Git Hooks (Husky)\n\nThe repo installs Husky hooks that run automatically — an agent committing or pushing will trigger them:\n\n- **`pre-commit`** — runs `lint-staged` (`eslint --fix` on staged `*.ts`/`*.tsx`). Do not bypass with `--no-verify`.\n- **`pre-push`** — runs a **git-secrets** scan and **blocks the push if git-secrets is not installed**. Install and register it before pushing:\n\n```bash\nbrew install git-secrets   # or: apt-get install git-secrets\ngit secrets --register-aws\n```\n\n## Changesets (required for functional changes)\n\n```bash\nyarn changeset\n```\n\nCreates a file in `.changeset/`:\n\n```markdown\n---\n'@aws-amplify/<package>': patch|minor|major\n---\n\n<type>(<scope>): description of the change.\n```\n\n**Skip a changeset** only for docs-only, formatting, or CI-only changes.\n\n## Branch Naming\n\n```\n<scope>/<type>/<description>\n```\n\n- **scope**: category or alias (e.g. `auth`, `storage`, `core`)\n- **type**: `feat` | `fix` | `docs` | `refactor` | `perf` | `test` | `build` | `ci` | `chore` | `revert`\n\nExamples: `auth/fix/refresh-token-race-condition`, `storage/feat/presigned-urls`\n\n## Commit / PR Flow\n\n1. Make changes in `packages/<category>/`.\n2. Add/update unit tests.\n3. Add a changeset (if functional).\n4. Validate: `yarn build` + `yarn test` (+ `yarn test:size` if bundle-sensitive).\n5. Commit with a conventional message: `<type>(<scope>): summary`.\n6. Push and open a PR filling out the template (description, linked issue, validation steps, checklist).\n\n## CI Checks (must pass before merge)\n\n| Check | Validates |\n|---|---|\n| `unit-tests` | Jest suites across packages |\n| `native-unit-tests` | React Native tests |\n| `bundle-size-tests` | Tree-shaken footprint (size-limit) |\n| `license-test` | License headers present |\n| `tsc-compliance-test` | TypeScript compilation |\n| `dependency-review` | No problematic dependencies |\n| `git-secrets-check` | No leaked AWS credentials |\n| `github-actions-test` | CI config validity |\n\nThe `ci - Unit and Bundle tests have passed` gate turns green only when all above pass.\n\n## Maintenance Branch: `v5-stable`\n\nThe `v5-stable` branch hosts Amplify JS v5 maintenance releases (security patches, critical fixes). **Do not apply this document's conventions there** — it uses different tooling (Lerna instead of Turborepo, no changesets, different setup and CI checks).\n\nWhen backporting a fix to v5: branch off `v5-stable`, target the PR at `v5-stable`, and follow the `AGENTS.md` **on that branch** for its specific conventions.\n\n## Do / Don't Summary\n\n**Do**\n- Use `yarn` for everything\n- Add tests + changesets\n- Keep license headers\n- Mock underlying modules, not `Amplify.getConfig`\n\n**Don't**\n- Run `tsc`/`jest`/`eslint`/`npx` directly\n- Commit `tsconfig.tsbuildinfo`\n- Strip existing comments or logging\n","CLAUDE.md":"# CLAUDE.md\n\nThis project's AI agent guidance lives in [AGENTS.md](./AGENTS.md).\n\nPlease read **[AGENTS.md](./AGENTS.md)** for repository structure, build/test commands, code conventions, changeset requirements, and CI checks.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\nGuidance for AI coding agents working in the **AWS Amplify JS** monorepo. Read this before making changes.\n\n## Repository Overview\n\nAmplify JS is a **Yarn + Turborepo** monorepo. Every package lives under `packages/<name>/`, each with its own `src/` and `package.json`. Packages are published under the `@aws-amplify/*` scope (plus the umbrella `aws-amplify` package).\n\nKey packages:\n\n| Package | Purpose |\n|---|---|\n| `@aws-amplify/core` | Shared runtime: config singleton, Hub, utils |\n| `@aws-amplify/auth` | Cognito authentication |\n| `@aws-amplify/storage` | S3 storage (client/utils + server/utils split) |\n| `@aws-amplify/api`, `api-graphql`, `api-rest` | API categories |\n| `@aws-amplify/analytics`, `geo`, `interactions`, `notifications`, `predictions`, `pubsub` | Feature categories |\n| `aws-amplify` | Umbrella package re-exporting category APIs |\n| `@aws-amplify/adapter-nextjs` | Next.js server adapter |\n\n## Environment\n\n| Requirement | Version |\n|---|---|\n| Node.js | 24 (pinned in CI; repo has no local `engines`/`.nvmrc`) |\n| Yarn | 1.22.x |\n\n## Build & Test Commands (MANDATORY: use `yarn`)\n\n**Always drive builds/tests/lint through `yarn`. NEVER invoke `tsc`, `eslint`, `jest`, `npx`, or `tsx` directly** — the workspace scripts wire up the correct config and dependency graph. Single-package targeting goes through Turbo's `--filter` (see below).\n\n```bash\n# Install\nyarn\n\n# Build\nyarn build                              # all packages\nyarn turbo run build --filter=@aws-amplify/auth   # single package (+ its deps)\n\n# Test\nyarn test                               # full suite (use before final confirmation)\nyarn turbo run test --filter=@aws-amplify/auth    # single package\n\n# Lint\nyarn lint                               # lint all packages\nyarn turbo run lint --filter=@aws-amplify/auth    # single package\n\n# Bundle size\nyarn test:size                          # size-limit check (only runs for packages that define it)\nyarn test:size --why                    # debug regression (Statoscope)\n\n# Watch mode for local dev\nyarn build:watch\nyarn link-all                           # make all packages linkable\n\n# Nuclear clean\ngit clean -xdf\n```\n\nRun `yarn` from the **monorepo root or a package root**. During implementation you may narrow with file/suite/test filters, but always run the full `test` / `lint` / `build` for final confirmation.\n\n> **Single-package targeting must go through Turbo directly** — `yarn turbo run <task> --filter=@aws-amplify/<pkg>`. Do **not** pass `--filter` to the top-level `yarn build` / `yarn test` scripts: they are compound (`&&`) scripts, so the flag is misrouted to the trailing command and Turbo still runs unfiltered. (`--scope` is a Lerna flag — not valid for Turbo 2.x at all.)\n\n## Testing Conventions\n\n- **Do NOT mock `getConfig` on the Amplify singleton.** Mock the actual underlying modules/functions instead (real Amplify config approach).\n- Write or update unit tests for any added/modified code. Be especially vigilant with shared code (race conditions).\n- Passing unit tests are required for any PR that changes functionality.\n- **Bundle-size (`size-limit`) checks only apply to packages that configure them.** Eight packages declare a `size-limit` key (`aws-amplify`, `core`, `datastore`, `geo`, `interactions`, `predictions`, `pubsub`, `api-graphql`), but `yarn test:size` only exercises the seven that also define a `test:size` script (all of the above except `api-graphql`). Filtering it to a package without size-limit configured (e.g. `auth`, `storage`) is a no-op.\n\n## Code Conventions\n\n- **License headers are required** on source files (enforced by the `license-test` CI check).\n- **Never commit `tsconfig.tsbuildinfo` files.** A stray `packages/*/tsconfig.tsbuildinfo` causes `license-test` failures (`License not found in ...`). Remove it if generated.\n- Preserve existing comments, JSDoc, and logging statements.\n- Follow existing formatting (Prettier + ESLint config are applied via `yarn` scripts).\n\n## Git Hooks (Husky)\n\nThe repo installs Husky hooks that run automatically — an agent committing or pushing will trigger them:\n\n- **`pre-commit`** — runs `lint-staged` (`eslint --fix` on staged `*.ts`/`*.tsx`). Do not bypass with `--no-verify`.\n- **`pre-push`** — runs a **git-secrets** scan and **blocks the push if git-secrets is not installed**. Install and register it before pushing:\n\n```bash\nbrew install git-secrets   # or: apt-get install git-secrets\ngit secrets --register-aws\n```\n\n## Changesets (required for functional changes)\n\n```bash\nyarn changeset\n```\n\nCreates a file in `.changeset/`:\n\n```markdown\n---\n'@aws-amplify/<package>': patch|minor|major\n---\n\n<type>(<scope>): description of the change.\n```\n\n**Skip a changeset** only for docs-only, formatting, or CI-only changes.\n\n## Branch Naming\n\n```\n<scope>/<type>/<description>\n```\n\n- **scope**: category or alias (e.g. `auth`, `storage`, `core`)\n- **type**: `feat` | `fix` | `docs` | `refactor` | `perf` | `test` | `build` | `ci` | `chore` | `revert`\n\nExamples: `auth/fix/refresh-token-race-condition`, `storage/feat/presigned-urls`\n\n## Commit / PR Flow\n\n1. Make changes in `packages/<category>/`.\n2. Add/update unit tests.\n3. Add a changeset (if functional).\n4. Validate: `yarn build` + `yarn test` (+ `yarn test:size` if bundle-sensitive).\n5. Commit with a conventional message: `<type>(<scope>): summary`.\n6. Push and open a PR filling out the template (description, linked issue, validation steps, checklist).\n\n## CI Checks (must pass before merge)\n\n| Check | Validates |\n|---|---|\n| `unit-tests` | Jest suites across packages |\n| `native-unit-tests` | React Native tests |\n| `bundle-size-tests` | Tree-shaken footprint (size-limit) |\n| `license-test` | License headers present |\n| `tsc-compliance-test` | TypeScript compilation |\n| `dependency-review` | No problematic dependencies |\n| `git-secrets-check` | No leaked AWS credentials |\n| `github-actions-test` | CI config validity |\n\nThe `ci - Unit and Bundle tests have passed` gate turns green only when all above pass.\n\n## Maintenance Branch: `v5-stable`\n\nThe `v5-stable` branch hosts Amplify JS v5 maintenance releases (security patches, critical fixes). **Do not apply this document's conventions there** — it uses different tooling (Lerna instead of Turborepo, no changesets, different setup and CI checks).\n\nWhen backporting a fix to v5: branch off `v5-stable`, target the PR at `v5-stable`, and follow the `AGENTS.md` **on that branch** for its specific conventions.\n\n## Do / Don't Summary\n\n**Do**\n- Use `yarn` for everything\n- Add tests + changesets\n- Keep license headers\n- Mock underlying modules, not `Amplify.getConfig`\n\n**Don't**\n- Run `tsc`/`jest`/`eslint`/`npx` directly\n- Commit `tsconfig.tsbuildinfo`\n- Strip existing comments or logging\n","category":"root","tokens":1693},{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# CLAUDE.md\n\nThis project's AI agent guidance lives in [AGENTS.md](./AGENTS.md).\n\nPlease read **[AGENTS.md](./AGENTS.md)** for repository structure, build/test commands, code conventions, changeset requirements, and CI checks.\n","category":"root","tokens":57}]}