docs(build-a-backend): add AWS Blocks integration section by harsh62 · Pull Request #8606 · aws-amplify/docs

harsh62 · 2026-06-29T17:07:14Z

Adds an AWS Blocks section under Build a Backend documenting how customers can provision AWS Blocks (Preview) within an existing Amplify Gen 2 app. Framed so Blocks complements Gen 2 (not a replacement). Pages: overview, get-started, how-it-works, connect-your-frontend, add-an-agent, use-basic-auth. Also extends develop-with-ai/steering-files with a Blocks steering recipe and registers pages in directory.mjs (top of Build a Backend, New badge). All 9 platforms; JS/native fork via InlineFilter.

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

harsh62 · 2026-06-29T17:15:08Z

Code review

Found 1 issue:

Broken internal link in the "Next steps" section — the path is missing the build-a-backend/ segment, so it resolves to a non-existent route (404). The correct route is /[platform]/build-a-backend/aws-blocks/connect-your-frontend/, as used correctly earlier in the same file (line 68) and registered in directory.mjs.

docs/src/pages/[platform]/build-a-backend/aws-blocks/how-it-works/index.mdx

Lines 101 to 104 in a92cc26

    
           ## Next steps 
        
           - [Connect your frontend](/[platform]/aws-blocks/connect-your-frontend/) and call the typed API. 
        
           - Review the full architecture in the [AWS Blocks Developer Guide](https://docs.aws.amazon.com/blocks/latest/devguide/what-is-blocks.html).

…t-works Add the missing build-a-backend/ path segment so the Next steps link resolves instead of 404ing.

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.

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.

…uides 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).

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.

- 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.

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.

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.

pranavosu

Cross-checked the AWS Blocks content against the devguide and the aws-devtools-labs/aws-blocks source. Accurate overall, and the Amplify auto-integration (create-blocks-app, initBlocks, CognitoVerifier, generated client.js) matches the upstream amplify template. A few notes on the agent page plus one categorization nit below.

pranavosu · 2026-07-02T17:01:12Z

+});
+
+const agent = new Agent(scope, 'support-agent', {
+  model: { deployed: BedrockModels.DEFAULT },


BedrockModels.DEFAULT is deprecated (it aliases to BALANCED). model is optional and defaults to BALANCED, so drop it or use BedrockModels.BALANCED.

Fixed in 28ce0d9: switched to BedrockModels.BALANCED and noted that model is optional (defaults to BALANCED). My local aws-blocks clone was 31 commits stale, so I'd missed the preset refactor (#16) and the optional-model change (#18) — re-verified against current main.

pranavosu · 2026-07-02T17:01:12Z

+
+const conversationId = await api.startConversation();
+
+const chat = useChat({


This adapter doesn't match the current UseChatOptions interface in bb-agent (src/index.hooks.ts). sendMessage takes a channelId, and createConversation/getConversation/subscribe each return specific shapes. Please check the interface and mirror the README's useChat example so this compiles and runs.

Fixed in 28ce0d9. The backend now returns { conversationId } and { messages } and sendMessage takes a channelId, so the adapter matches UseChatOptions and mirrors the README end-to-end example. (Same root cause as the model comment: stale local clone.)

pranavosu · 2026-07-02T17:01:12Z

+
+<Callout info>
+
+`useChat` is a factory function, not a React hook — call it once (for example, in a ref or outside your component), not on every render.


This is accurate, though it reads as contradicting the upstream "hook" naming. Consider "despite the name, useChat is a factory function...". Non-blocking.

Done in 28ce0d9 — reworded to "Despite the name, useChat is a factory function...".

pranavosu · 2026-07-02T17:01:12Z

+| Authentication | `AuthBasic`, `AuthCognito`, `AuthOIDC` |
+| Compute & background | `AsyncJob`, `CronJob` |
+| AI | `Agent`, `KnowledgeBase` |
+| Communication | `Realtime`, `EmailClient` |


Realtime sits under "Real-time and async" in the Blocks reference, not Communication (which lists only EmailClient). Aligning categories avoids confusion. Low priority.

Fixed in 28ce0d9: moved Realtime into a "Real-time & async" row (with AsyncJob/CronJob) and left EmailClient under Communication, matching the Blocks reference.

Update: after pulling aws-blocks to latest main, I checked the in-repo grouping. The root README catalog (the authoritative in-repo source) lists Realtime under Communication and AsyncJob/CronJob under Compute & background, and the "Real-time and async" label doesn't appear anywhere in the repo. So in aefcbce I kept Realtime under Communication to match the README rather than the devguide. Happy to flip both the README and these docs if the devguide grouping is the intended source of truth — let me know which is canonical.

Simone319 · 2026-07-02T17:02:05Z

+    sendMessage: (conversationId, message) =>
+      api.sendMessage(conversationId, message),
+    createConversation: () => api.startConversation(),
+    getConversation: (id) => api.getMessages(id)


This useChat example won't compile. useChat expects createConversation to return { conversationId } and getConversation to return { messages }, but the raw agent methods return a bare string and a bare Message[] — so wiring them in directly fails to compile.

The README "Full Examples" wraps them in the backend before they reach the hook; this example skips that step. Quick fix in the adapters:

createConversation: async () => ({ conversationId: await api.startConversation() }), getConversation: async (id) => ({ messages: await api.getMessages(id) }),

(Minor: useChat calls sendMessage with a third channelId arg this example doesn't pass — see the README adapter.)

Thanks — fixed in 28ce0d9. The backend methods now return { conversationId } / { messages } (wrapped as you noted) and sendMessage takes the third channelId arg, so the useChat wiring compiles and matches the README "Full Examples".

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...").

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-gen2-integration branch from 5d5877e to a92cc26 Compare June 29, 2026 17:09

harsh62 requested a review from a team as a code owner June 29, 2026 17:09

harsh62 added 3 commits June 29, 2026 13:17

docs(build-a-backend): fix Connect your frontend link in Blocks how-i…

4cd3d4d

…t-works Add the missing build-a-backend/ path segment so the Next steps link resolves instead of 404ing.

harsh62 requested a review from a team as a code owner June 29, 2026 21:17

harsh62 added 4 commits June 29, 2026 17:42

fix(modal): add spacing between modal action label and icon

2103e1f

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): rename secondary CTA to "Get Started with Blocks"

0f89d54

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.

harsh62 mentioned this pull request Jul 2, 2026

docs(develop-with-ai): AWS Blocks steering-file recipe + modal icon fix #8608

Open

docs(build-a-backend): move steering-file recipe to a separate PR

aa3a1e5

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.

osama-rizk previously approved these changes Jul 2, 2026

View reviewed changes

pranavosu reviewed Jul 2, 2026

View reviewed changes

Simone319 reviewed Jul 2, 2026

View reviewed changes

harsh62 dismissed osama-rizk’s stale review via 28ce0d9 July 2, 2026 18:17

harsh62 requested review from Simone319 and pranavosu July 2, 2026 18:48

Simone319 previously approved these changes Jul 2, 2026

View reviewed changes

harsh62 dismissed Simone319’s stale review via aefcbce July 2, 2026 19:02

pranavosu approved these changes Jul 2, 2026

View reviewed changes

harsh62 enabled auto-merge (squash) July 2, 2026 19:52

ekjotmultani approved these changes Jul 2, 2026

View reviewed changes

harsh62 merged commit e7894f5 into main Jul 2, 2026
13 checks passed

harsh62 deleted the docs/aws-blocks-gen2-integration branch July 2, 2026 20:10

harsh62 mentioned this pull request Jul 3, 2026

fix(modal): consistent line-art icons for AWS Blocks feature points #8609

Closed


		const conversationId = await api.startConversation();

		const chat = useChat({


		<Callout info>

		`useChat` is a factory function, not a React hook — call it once (for example, in a ref or outside your component), not on every render.

Uh oh!

Conversation

harsh62 commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

harsh62 commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code review

Uh oh!

pranavosu left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

harsh62 commented Jun 29, 2026 •

edited

Loading

harsh62 commented Jun 29, 2026 •

edited

Loading