docs(develop-with-ai): AWS Blocks steering-file recipe + modal icon fix#8608
Merged
Conversation
harsh62
added a commit
that referenced
this pull request
Jul 2, 2026
The AWS Blocks steering-file section now lives in #8608. Restore steering-files/index.mdx to its main version here so this PR is scoped to the Blocks docs only.
harsh62
added a commit
that referenced
this pull request
Jul 2, 2026
* docs(build-a-backend): add AWS Blocks integration section Add an "AWS Blocks" section under Build a Backend covering how to add AWS Blocks to an existing Amplify Gen 2 project, how the integration works, connecting a frontend, and task-based guides for adding an AI agent and using BasicAuth. Add a Blocks integration steering-file recipe for AI coding assistants. - New pages under src/pages/[platform]/build-a-backend/aws-blocks/ - Register pages in directory.mjs (top of Build a Backend, New badge) - Extend develop-with-ai/steering-files with an AWS Blocks section - Add Blocks terminology to cspell dictionary * docs(build-a-backend): fix Connect your frontend link in Blocks how-it-works Add the missing build-a-backend/ path segment so the Next steps link resolves instead of 404ing. * chore: update yarn.lock to v10 format for Yarn 4.17 CI's set_yarn_berry action runs 'yarn set version berry', which resolves to the latest Yarn (now 4.17.0) and rewrites the lockfile to __metadata version 10. The committed lockfile was version 9, so the immutable install step failed on every PR. Regenerate the lockfile and bump packageManager to match what CI resolves. * feat(modal): introduce AWS Blocks in the announcement modal Repurpose the site announcement modal from 'Introducing Amplify Gen 2' to 'Introducing AWS Blocks', since Gen 2 is now established and AWS Blocks is the new capability. Add two feature highlights, an internal link to the Blocks docs section, and an external link to AWS Blocks on AWS. Use a new dismissal key so the announcement re-shows. Remove the now-unused Gen 1 back-link, isGen1 prop, and orphaned useGen1Path helper. * docs(aws-blocks): correct verified API usage in Agent and AuthBasic guides Verified all code examples against the aws-blocks source repo: - add-an-agent: expose getChannel() on the backend API namespace. The frontend useChat subscribe() calls api.getChannel(), but it is not auto-generated and must be defined explicitly (matches the bb-agent README end-to-end example and test-apps/comprehensive). - use-basic-auth: setAuthState() does not throw; it returns an AuthState with errorName. Replace the try/catch + isBlocksError pattern with hasAuthError(next, ...), per the bb-auth-basic README rule of thumb. - get-started: list all four scaffolded npm scripts (sandbox, sandbox:delete, blocks:dev, blocks:generate-client). * fix(modal): add spacing between modal action label and icon The 'AWS Blocks on AWS' button's external-link icon overlapped its label because .modal-action had no inline-flex layout or gap. Add inline-flex + gap (matching .modal-heading) so text and trailing icons are spaced. * feat(modal): differentiate Blocks CTA labels and feature examples - Rename actions so they read distinctly: primary "Explore Blocks with Amplify" (left, into the Amplify docs) and secondary "AWS Blocks documentation" (right, external). Previously both said "AWS Blocks". - Swap feature examples that overlapped Amplify's own categories (AI agents, auth, storage) for differentiated Blocks capabilities: PostgreSQL databases, realtime messaging, metrics, logging. * feat(modal): rename secondary CTA to "Get Started with Blocks" Keeps the external-link icon to signal it opens a new page (the AWS Blocks docs). Pairs with the primary "Explore Blocks with Amplify" action. * docs(build-a-backend): move steering-file recipe to a separate PR The AWS Blocks steering-file section now lives in #8608. Restore steering-files/index.mdx to its main version here so this PR is scoped to the Blocks docs only. * docs(aws-blocks): address PR review feedback on Agent guide Verified against current aws-blocks/main (local clone was 31 commits stale, which is how these were missed): - useChat adapter now compiles: backend returns { conversationId } and { messages } and sendMessage accepts channelId, matching the UseChatOptions interface and the bb-agent README end-to-end example. - Replace deprecated BedrockModels.DEFAULT with BALANCED; note model is optional (defaults to BALANCED). - Move Realtime to a Real-time & async category (matches the Blocks reference), leaving EmailClient under Communication. - Reword the useChat factory callout ("Despite the name..."). * docs(aws-blocks): re-verify examples against latest aws-blocks main Pulled aws-blocks to HEAD e8f3854 and re-verified all examples: - Agent sendMessage now passes userId to agent.stream(); without it the Agent throws PersistenceRequired at runtime (bb-agent agent.ts:407). - Revert Realtime to the Communication category and restore Compute & background (AsyncJob/CronJob) to match the aws-blocks root README grouping (the authoritative in-repo source). - Drop blocks:dev from the scaffolded-scripts list: the CLI points it at aws-blocks/scripts/server.ts, which the amplify template does not ship, so it is non-functional for Amplify projects.
…l icons
Adds an "AWS Blocks integration" section to the steering-files page with
a per-tool recipe (Claude Code, Cursor, Kiro) so AI coding assistants
follow the Blocks integration patterns. All claims verified against the
aws-blocks source (create-blocks-app scaffolds AGENTS.md; backend in
aws-blocks/index.ts with CognitoVerifier + requireAuth; blocks:generate-client;
import { api } from aws-blocks; npm run sandbox).
Also folds in the modal icon fix from #8609: replace the puzzle emoji
with IconStar and size both feature-point icons consistently.
Rebuilt on latest main so the aws-blocks internal links (merged in #8606)
resolve, clearing the earlier CheckPRLinks failure.
harsh62
force-pushed
the
docs/aws-blocks-steering-file
branch
from
0f5b59b to
30f4e08
Compare
harsh62
changed the title
Lead the AWS Blocks steering section with the official aws-blocks skill from the AWS agent toolkit (github.com/aws/agent-toolkit-for-aws) as the recommended, 1-click option for Claude Code, the skills CLI (Cursor), and Codex. Keep the hand-written CLAUDE.md / .cursor / .kiro snippets as a fallback for project-committed rules. Also drop the inaccurate claim that the recipe mirrors an AGENTS.md that create-blocks-app scaffolds: the Amplify-integration path does not scaffold an AGENTS.md (only fresh standalone Blocks apps do).
Simone319
previously approved these changes
Jul 7, 2026
Per Furkan: - Install only the aws-blocks skill: npx skills add aws/agent-toolkit-for-aws/skills --skill aws-blocks (verified the skills CLI supports -s/--skill). - Drop the hand-written CLAUDE.md/.cursor/.kiro rule dumps, which are easy to let drift out of date. Instead direct assistants to the official aws-blocks skill or the AGENTS.md that create-blocks-app scaffolds.
ekjotmultani
previously approved these changes
Jul 9, 2026
pranavosu
previously approved these changes
Jul 9, 2026
|
Tick the box to add this pull request to the merge queue (same as
|
Simone319
reviewed
Jul 10, 2026
|
|
||
| ### Scaffold the project rules | ||
|
|
||
| `create-blocks-app` can generate an `AGENTS.md` that documents the Blocks integration patterns for AI assistants, so in most cases you don't need to write steering rules by hand. To add AWS Blocks to your project, see [Add AWS Blocks to your Amplify project](/[platform]/build-a-backend/aws-blocks/get-started/). |
Contributor
There was a problem hiding this comment.
This is not true as of today. AGENTS.md is created only for fresh project. However, amplify integration is existing project where the AGENTS.md will not be generated. So customers end up still need to write steering rules by hand. Not sure why the AGENTS.md is left it out for existing project though, perhaps we should include it to serve as a reference if customer want to add it to the project level steering file.
Contributor
Author
There was a problem hiding this comment.
You're right, thanks — corrected in f3f508e. Confirmed against aws-blocks main: copySharedResources() (which writes AGENTS.md) is only called from createFreshProject, so the Amplify integration (existing-project path via integrateWithAmplify) does not generate one. Reworded to say plainly that adding Blocks to an existing Amplify project doesn't scaffold an AGENTS.md, so the aws-blocks skill is the simplest option — and if you want file-based rules you add an AGENTS.md/steering file yourself, pointing it at the skill and the standalone-app AGENTS.md rather than copying rules. Agree it'd be nice if the integration path emitted a reference AGENTS.md too — worth raising with the Blocks team.
Simone319
requested changes
Jul 10, 2026
Per review (Simone319): adding AWS Blocks to an existing Amplify project does NOT scaffold an AGENTS.md — create-blocks-app only generates one for a standalone Blocks app (fresh-project path). Reworded so Amplify users are told the aws-blocks skill is the simplest option, and that any file-based rules (AGENTS.md / CLAUDE.md / .cursor / .kiro) must be added by hand and should point at the authoritative sources instead of copying rules.
CI's set_yarn_berry pulls the latest Yarn (now 4.17.1), which rewrites the resolve@patch builtin hash in the lockfile (c3c19d -> 9bd1a5). The committed lock was generated with 4.17.0, so the immutable install failed on every check. Regenerate the lockfile and bump packageManager to match.
Simone319
approved these changes
Jul 13, 2026
ekjotmultani
approved these changes
Jul 13, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds an "AWS Blocks integration" section to the steering-files page with a per-tool recipe (Claude Code / CLAUDE.md, Cursor / .cursor/rules, Kiro / .kiro/steering) so AI coding assistants follow the Blocks integration patterns in an Amplify Gen 2 project.
Also folds in the announcement-modal icon fix (previously #8609, now closed): replaces the puzzle emoji with IconStar and sizes both feature-point icons consistently.
Notes