Repository navigation
Conversation
🦋 Changeset detectedLatest commit: 06072c0 The changes in this PR will be included in the next version bump. This PR includes changesets to release 3 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
This was referenced Nov 18, 2026
xyos
force-pushed
the
docs/readme-guide-scaffold
branch
2 times, most recently
from
November 18, 2026 22:39
d13ddaa to
5aec7f3
Compare
The bullets on which scripts and wrappers migrate rewrites, keeps and deletes, how it finds what still uses a wrapper, and its --output json shape move verbatim into MIGRATING-FROM-SCRIPTS.md, added to the package's files. The README keeps how to run it, when it refuses, that a customized wrapper is never deleted, the exit codes and the two scripts that behave differently afterwards.
…graphs into lists and tables The security list said WAF and API Gateway throttling are not included by default; throttling is on by default from `defaults.throttling`, and WAF is off and is enabled with `apiWaf` on `BlocksStack` or `BlocksBackend`, or with `frontDoor.features.waf` on `Hosting` when its CloudFront distribution serves the API. The credentials text said "the services your cdk-blocks deploy" and now says "the services your app deploys". Credentials, deployment target, CDK bootstrap, deploy signals, global options, telemetry, output formats, the `blocks.dev` keys, frontend detection and the migrate exit codes are lists and tables with one rule per item, where each was a paragraph. "Common mistakes" is removed because each item repeated another section, the Cognito prices are left to the `Auth` README, and the IAM hardening report details are left to the `@aws-blocks/core` README. "Testing", "Best practices", "Security Considerations" and "VPC Support" come before "Local development and deploying", and the test helpers table moves from "Reference" to "Testing". `MIGRATING-FROM-SCRIPTS.md` splits its ten bullets into seven sections with the same rules.
…r mode, move contributor notes The README linked a guide anchor that does not exist, listed four of the five backend-only templates (`observability` was missing), gave the Amplify overlay's `blocks.dev` without `generateClient: false`, said an existing project gets seven named scripts, and said the CLI has the same version number as `@aws-blocks/blocks`. It now links `#migrating-an-existing-app`, and a table states the scripts and `blocks.dev` value for each mode: an existing project gets every Blocks task, and a task whose script name is taken is added as `blocks:<name>`. "Usage" starts with the command synopsis and a table of the argument and options, including `--skip-install` and `-y`/`--yes`, which the README did not mention. The listings of `aws-blocks/index.ts` and `aws-blocks/index.cdk.ts` (the second had a hard-coded stack name the template does not use) and the full script list are removed; one script and the `blocks.dev` block remain, with a pointer to the guide. The notes on template registration and on how the CLI stamps `@aws-blocks/*` dependency ranges move to a new `DESIGN.md`, which the README links.
…s the e2e test before a deploy The "Tests" bullet now says to update `test/e2e.test.ts` when the API changes and never to delete `test/` or the `test:e2e` script. Workflow step 2 now says to get `npm run test:e2e` passing before every `npm run deploy`, and that it exercises the API through the typed client, not the UI, so a frontend change also needs a check in a browser. Workflow step 4 said not to use curl or fetch against the API unless troubleshooting connectivity; it now says not to use them against the local API as the functional test and to add the check to `test/e2e.test.ts` instead. Nothing else in the file changes.
…ecific to that template The "Adding a Frontend Later" recipe in `backend`, `cron` and `observability` listed `react` `^19.0.0`, `@vitejs/plugin-react` `^4.3.0` and `vite` `^5.0.0`; it now lists the versions the `react` template uses. `api-only` and `sql` pointed to the `backend` template's README, which a scaffolded app does not contain; they now point to `npm run docs Hosting` and a scaffolded `react` app. `default` names the sections its test file has, `nextjs` says `await auth.requireAuth(context)`, `agent` points to `npm run docs Agent`, and the curl examples in the five backend-only READMEs open with when a direct call is appropriate. The command tables, the stack naming section, the dev server settings and the paragraphs on storage, start files and JSON-RPC are removed from all 13 READMEs because the app's `AGENTS.md` and `npm run help` state them. Each README keeps `npm run typegen` with its commit rule, the sandbox id file where it was named, and, in the backend-only templates, the rule to run `npm run typecheck` after code changes. `auth-oidc` and `demo` gain a "Before deploying to production" section with the steps that were inside other paragraphs.
…enerated block README The generated README had no place for the block's errors and no `Default` column in its options table. It now has an `## Errors` table (Constant, `error.name`, Thrown when) seeded with `InvalidInput` / `InvalidInputException` from the template's `src/errors.ts`, a `Default` column, and `TODO` markers on the paragraphs the block author replaces. The package README says in one sentence that `create-block --help` prints every option and the next steps, and no longer uses the word "primitive" without defining it.
xyos
force-pushed
the
docs/readme-guide-scaffold
branch
from
November 19, 2026 06:11
5aec7f3 to
33fa5f7
Compare
This branch has not been deployed
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
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.
Problem
packages/blocks/README.md) had 28 prose lines over 400 characters. Credentials, the deployment target and CDK bootstrap were three paragraphs of about 900 to 1,300 characters each, so a reader looking for one default or one exit code read a whole paragraph.AGENTS.mdin the same scaffolded app states, and in two places contradicted it (port flags; curl shown as normal usage).resources/AGENTS.md, where only three sentences change).Issue #, if available:
Changes
packages/blocks/README.mddefaults.throttling(packages/core/src/cdk/blocks-defaults.ts:459,476). WAF is off by default; enable it withapiWaf: { enabled: true }onBlocksStackorBlocksBackend(packages/core/src/common/index.ts:708-711,packages/core/src/cdk/blocks-backend.ts:113), or withfrontDoor: { features: { waf: { enabled: true } } }onHostingwhen its CloudFront distribution serves the API (packages/core/src/hosting.ts:631).blocks.devkeys with defaults and frontend detection order (packages/blocks/src/cli/config.ts:24-31,51,65-70); task → JSON result andnpm run docscall → JSON result; migrate exit codes; test helpers (packages/blocks/src/utils.ts:29,165,196,packages/bb-auth/src/testing.ts:156,213), moved from "Reference" to "Testing".packages/blocks/src/cli/registry.ts:140-173), "Telemetry". New statement:npm run sandbox:destroyasks only in a terminal (packages/blocks/src/cli/commands.ts:733-735).AuthREADME); the IAM hardening report details (@aws-blocks/coreREADME).packages/blocks/MIGRATING-FROM-SCRIPTS.md8b6b236ecmoves the migrate bullets out of the guide into this file, verbatim, and adds it topackages/blocks/package.jsonfiles. The guide keeps how to run migrate, when it refuses, the exit codes and the two commands that behave differently afterwards.packages/blocks/src/cli/commands/migrate.ts:932-935).packages/create-blocks-app/README.mdandDESIGN.md#migrating-an-existing-app;observabilityis a backend-only template (templates/observability/package.json:42-45); the Amplify overlay'sblocks.devhasgenerateClient: false(src/index.ts:952); an existing project gets every Blocks task, renamedblocks:<name>when the name is taken (src/index.ts:468-483,549-553); the CLI is released with@aws-blocks/blocks(.changeset/config.json:5) but not at the same version number (0.4.0 and 0.9.0).printUsageand the parser (src/index.ts:1258-1306), including--skip-installand-y/--yes; a table of scripts andblocks.devper mode.DESIGN.md.packages/create-blocks-app/resources/AGENTS.md: three sentences. Update the tests when the API changes and never deletetest/ortest:e2e; getnpm run test:e2epassing before everynpm run deploy; add the functional check totest/e2e.test.tsinstead of using curl or fetch against the local API.13 template READMEs
backend,cron,observability(templates/react/package.json:53,54,61,63);api-onlyandsqlpoint tonpm run docs Hosting;defaulttest sections (templates/default/test/e2e.test.ts:126-284);nextjssaysawait auth.requireAuth(context).AGENTS.mdornpm run helpstates it: command tables, stack naming, dev server settings, the storage, start-file and JSON-RPC paragraphs.npm run typegenand its commit rule;.cdk-blocks-sandbox/sandbox-id.txtin six READMEs; "runnpm run typecheckafter code changes" in the five backend-only READMEs; the process-model table and the recipe inbackend,cron,observability.packages/create-block: theprimitivetemplate README gains an## Errorstable seeded fromtemplates/primitive/src/errors.ts:9-11, aDefaultcolumn andTODOmarkers.packages/blocks/README.mdpackages/blocks/MIGRATING-FROM-SCRIPTS.md(new)packages/create-blocks-app/README.mdpackages/create-blocks-app/DESIGN.md(new)packages/create-blocks-app/resources/AGENTS.mdtemplates/agent/README.mdtemplates/api-only/README.mdtemplates/auth-oidc/README.mdtemplates/auth/README.mdtemplates/backend/README.mdtemplates/bare/README.mdtemplates/cron/README.mdtemplates/default/README.mdtemplates/demo/README.mdtemplates/nextjs/README.mdtemplates/observability/README.mdtemplates/react/README.mdtemplates/sql/README.mdpackages/create-block/README.mdpackages/create-block/templates/primitive/README.mdtemplates/rows are underpackages/create-blocks-app/.Look hardest at:
AGENTS.mdsentences: the file is copied into every scaffolded app, so each one is an instruction to every coding assistant that works in one.AGENTS.mdcarries: a reader of only the README no longer sees the command table or stack naming.Not changed on purpose:
"build": "tsc && vite build"(see the first open question).sqlREADME, and the step that replaces"*"ranges in older apps in the create-blocks-app README.DESIGN.mdis not in the package'sfiles; the README links it by repository URL.Open questions:
npm run typecheck && vite build? In a backend-only apptsconfig.jsonsets"outDir": "build-temp"and nonoEmit, sotscemits there. No test runs the recipe..cdk-blocks-sandbox/sandbox-id.txtfact move intoAGENTS.md, so "Stack naming" can leave six READMEs?npm run help typegenstate the commit rule for.blocks/hosting-values.d.ts, so the last shared line can leave the 13 READMEs?sandbox:previewis now only innpm run help sandbox:preview(packages/blocks/src/cli/registry.ts:335). Is that enough?Carried from
main: the directory rename to.cdk-blocks-sandbox(#1644) is applied to the revised text: one line ofpackages/blocks/MIGRATING-FROM-SCRIPTS.mdand the "Stack naming" line of six template READMEs.Related pull requests: Supersedes the guide part of #1496 (the migrate details move out of the guide, redone on the current text of that section) and carries what was still missing from the closed #794 (the three
AGENTS.mdsentences). Open pull requests that touch the same files; whichever merges second rebases:packages/blocks/README.md: feat(bb-sms-client): add SmsClient building block for SMS and mobile push #49, feat(observability): add OpenTelemetry building blocks (OtelMetrics / OtelLogger / OtelTracer) #50, feat(bb-auth-jwt): provider-agnostic bearer-JWT auth Building Block #297, fix(bb-lambda-compute): Report bbName/bbVersion in telemetry #611, fix(core): destroy and watch every top-level stack of a multi-stack app #968, feat(core): pass --express in the printed cdk bootstrap command #1128, fix(core): explain connection string SSM failures before deploy #1140, feat(core): explain denied deploy requests without risking sandbox data #1163, feat(bb-file-bucket): run a handler when an object is created (onObjectCreated) #1299, feat(core): fail production synth on a permissive or conflicting permissionsBoundary #1402, feat(blocks): registerdashboardas an app task #1472, feat(core)!: follow CDK's telemetry opt-out and remove the AWS Blocks one #1606packages/create-blocks-app/resources/AGENTS.md: feat(core): pass --express in the printed cdk bootstrap command #1128, fix(core): explain connection string SSM failures before deploy #1140, feat(core): explain denied deploy requests without risking sandbox data #1163packages/create-blocks-app/README.md: fix(create-blocks-app): keep Vite template builds working after the sample API is replaced #1010, perf: keep the CDK barrel and SDK client types out of an app's typecheck #1261templates/backend/README.md: fix(core): destroy and watch every top-level stack of a multi-stack app #968, docs(create-blocks-app): fix frontend setup in the backend template #1335templates/api-only,demo,nextjs,sqlREADMEs: fix(core): destroy and watch every top-level stack of a multi-stack app #968Part of a set of README revisions: #1635 (core), #1636 (hosting and pipeline), #1637 (bb-agent and bb-knowledge-base), #1638 (bb-auth and auth-common), #1639 (the storage blocks), #1640 (compute, jobs, realtime, email and observability), #1642 (the native SDKs), #1643 (contributor docs). Each merges on its own.
Validation
Run on this branch alone at
33fa5f7fe, onmain8940cfd2f, with Node 22. All pass:npm run buildpackages/blocks(readme-links,docs-pointers,doc-snippets,imports-reference)packages/blockssandbox-dir-coverage(no tracked file names the old directory.blocks-sandbox)packages/corereadme-policies(the IAM policy JSON)packages/bb-authreadme-recipes,first-admin,multi-block-snippets,users-cli,gate-diagnosticspackages/auth-commonui.react-typespackages/bb-kv-storereadme.generated(every README snippet compiled) andlegacy/runtimepackages/create-blocks-appnpm testnpm run sync-docs:checknpm run check:importschangeset-guard.ts validate-structurechangeset-guard.ts verify-coveragechangeset-guard.ts verify-umbrellachangeset-guard.ts block-major#anchorin the changed files, and every link into them from another Markdown file, resolves (checked with a script)Run once on all the README branches of this set combined, as they were on an earlier
maincommit (e1e484465), and not run again after the rebases:packages/coreunit suite,packages/blocksunit suite,packages/bb-kv-storeunit suite,packages/bb-authunit suite,packages/auth-commonunit suite,npm run lint,npm run lint:depsandnpm run check:api. All passed.Not run locally: the full
npm testacross all workspaces,npm run test:e2e:localand the sandbox e2e suites. CI runs them.Files other than Markdown in this pull request:
packages/blocks/package.json.No test was added: the tests listed above already read these READMEs, and the remaining statements are checked against the source by review.
Checklist
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.