Skip to content

docs(blocks,create-blocks-app,create-block): one rule per item in the guide; shorter template READMEs - #1641

Draft
xyos wants to merge 7 commits into
aws:mainfrom
xyos:docs/readme-guide-scaffold
Draft

xyos wants to merge 7 commits into
aws:mainfrom
xyos:docs/readme-guide-scaffold

Conversation

@xyos

@xyos xyos commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Problem

  • The guide (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.
  • Some statements were wrong. The guide said WAF and API Gateway throttling are "not included by default"; throttling is on by default. The create-blocks-app README linked an anchor that does not exist and listed four of the five backend-only templates.
  • The 13 app template READMEs repeated the command table, stack naming, dev server settings and JSON-RPC notes that the AGENTS.md in the same scaffolded app states, and in two places contradicted it (port flags; curl shown as normal usage).
  • Across the 20 files: 26,785 → 21,076 words, prose lines over 400 characters 75 → 40 (29 of the 40 are in resources/AGENTS.md, where only three sentences change).

Issue #, if available:

Changes

packages/blocks/README.md

  • Correction, security list: throttling is on by default from defaults.throttling (packages/core/src/cdk/blocks-defaults.ts:459,476). WAF is off by default; enable it with apiWaf: { enabled: true } on BlocksStack or BlocksBackend (packages/core/src/common/index.ts:708-711, packages/core/src/cdk/blocks-backend.ts:113), or with frontDoor: { features: { waf: { enabled: true } } } on Hosting when its CloudFront distribution serves the API (packages/core/src/hosting.ts:631).
  • Correction: "the services your cdk-blocks deploy" → "the services your app deploys".
  • Tables: blocks.dev keys with defaults and frontend detection order (packages/blocks/src/cli/config.ts:24-31,51,65-70); task → JSON result and npm run docs call → 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".
  • Lists, one rule per item: "AWS credentials", "Deployment target", "CDK bootstrap", "Deploy progress and signals", "Global options" (packages/blocks/src/cli/registry.ts:140-173), "Telemetry". New statement: npm run sandbox:destroy asks only in a terminal (packages/blocks/src/cli/commands.ts:733-735).
  • "Testing", "Best practices", "Security Considerations" and "VPC Support" come before "Local development and deploying".
  • Removed: the tagline and feature bullets; "Common mistakes" (each item is stated in another section); the Cognito prices (Auth README); the IAM hardening report details (@aws-blocks/core README).

packages/blocks/MIGRATING-FROM-SCRIPTS.md

  • Commit 8b6b236ec moves the migrate bullets out of the guide into this file, verbatim, and adds it to packages/blocks/package.json files. The guide keeps how to run migrate, when it refuses, the exit codes and the two commands that behave differently afterwards.
  • The next commit splits the ten bullets (the longest about 2,800 characters) into seven sections. One sentence is new: a wrapper in use is kept and reported with the file that uses it (packages/blocks/src/cli/commands/migrate.ts:932-935).

packages/create-blocks-app/README.md and DESIGN.md

  • Corrections: the guide link is #migrating-an-existing-app; observability is a backend-only template (templates/observability/package.json:42-45); the Amplify overlay's blocks.dev has generateClient: false (src/index.ts:952); an existing project gets every Blocks task, renamed blocks:<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).
  • Added: an argument and options table from printUsage and the parser (src/index.ts:1258-1306), including --skip-install and -y/--yes; a table of scripts and blocks.dev per mode.
  • Removed: the two source listings and 25 of 26 script lines; text the guide states. Template registration and dependency-range stamping move to the new DESIGN.md.

packages/create-blocks-app/resources/AGENTS.md: three sentences. Update the tests when the API changes and never delete test/ or test:e2e; get npm run test:e2e passing before every npm run deploy; add the functional check to test/e2e.test.ts instead of using curl or fetch against the local API.

13 template READMEs

  • Corrections: recipe dependency versions in backend, cron, observability (templates/react/package.json:53,54,61,63); api-only and sql point to npm run docs Hosting; default test sections (templates/default/test/e2e.test.ts:126-284); nextjs says await auth.requireAuth(context).
  • Removed where AGENTS.md or npm run help states it: command tables, stack naming, dev server settings, the storage, start-file and JSON-RPC paragraphs.
  • Kept: npm run typegen and its commit rule; .cdk-blocks-sandbox/sandbox-id.txt in six READMEs; "run npm run typecheck after code changes" in the five backend-only READMEs; the process-model table and the recipe in backend, cron, observability.

packages/create-block: the primitive template README gains an ## Errors table seeded from templates/primitive/src/errors.ts:9-11, a Default column and TODO markers.

File Lines Words Lines over 400 chars
packages/blocks/README.md 419 → 523 7932 → 6392 28 → 8
packages/blocks/MIGRATING-FROM-SCRIPTS.md (new) 95 1312 0
packages/create-blocks-app/README.md 216 → 128 1932 → 1246 9 → 3
packages/create-blocks-app/DESIGN.md (new) 15 216 0
packages/create-blocks-app/resources/AGENTS.md 269 → 269 4797 → 4876 29 → 29
templates/agent/README.md 92 → 57 851 → 418 0 → 0
templates/api-only/README.md 132 → 109 1056 → 744 0 → 0
templates/auth-oidc/README.md 91 → 64 838 → 443 0 → 0
templates/auth/README.md 106 → 72 935 → 514 0 → 0
templates/backend/README.md 127 → 104 827 → 500 1 → 0
templates/bare/README.md 59 → 36 656 → 196 2 → 0
templates/cron/README.md 143 → 112 923 → 567 1 → 0
templates/default/README.md 74 → 49 874 → 348 2 → 0
templates/demo/README.md 101 → 70 915 → 485 0 → 0
templates/nextjs/README.md 94 → 63 895 → 452 0 → 0
templates/observability/README.md 164 → 133 1129 → 775 1 → 0
templates/react/README.md 68 → 45 831 → 313 2 → 0
templates/sql/README.md 111 → 100 872 → 698 0 → 0
packages/create-block/README.md 46 → 45 329 → 319 0 → 0
packages/create-block/templates/primitive/README.md 43 → 56 193 → 262 0 → 0

templates/ rows are under packages/create-blocks-app/.

Look hardest at:

  • The three AGENTS.md sentences: the file is copied into every scaffolded app, so each one is an instruction to every coding assistant that works in one.
  • The guide's paragraphs turned into tables and lists: each row should say what the paragraph said. The guide is 104 lines longer for it.
  • The template READMEs losing text that the app's own AGENTS.md carries: a reader of only the README no longer sees the command table or stack naming.

Not changed on purpose:

  • The recipe's "build": "tsc && vite build" (see the first open question).
  • "Writing SQL for Aurora DSQL" in the sql README, and the step that replaces "*" ranges in older apps in the create-blocks-app README.
  • DESIGN.md is not in the package's files; the README links it by repository URL.

Open questions:

  • Should the recipe's build script be npm run typecheck && vite build? In a backend-only app tsconfig.json sets "outDir": "build-temp" and no noEmit, so tsc emits there. No test runs the recipe.
  • Should the .cdk-blocks-sandbox/sandbox-id.txt fact move into AGENTS.md, so "Stack naming" can leave six READMEs?
  • Should npm run help typegen state the commit rule for .blocks/hosting-values.d.ts, so the last shared line can leave the 13 READMEs?
  • "API Gateway, no CloudFront" for sandbox:preview is now only in npm run help sandbox:preview (packages/blocks/src/cli/registry.ts:335). Is that enough?
  • If the guide's length matters more than scanning, "Global options", "Telemetry" and "Output and exit codes" could become a topic file.

Carried from main: the directory rename to .cdk-blocks-sandbox (#1644) is applied to the revised text: one line of packages/blocks/MIGRATING-FROM-SCRIPTS.md and 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.md sentences). Open pull requests that touch the same files; whichever merges second rebases:

Part 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, on main 8940cfd2f, with Node 22. All pass:

  • npm run build
  • the shipped-docs tests in packages/blocks (readme-links, docs-pointers, doc-snippets, imports-reference)
  • packages/blocks sandbox-dir-coverage (no tracked file names the old directory .blocks-sandbox)
  • packages/core readme-policies (the IAM policy JSON)
  • packages/bb-auth readme-recipes, first-admin, multi-block-snippets, users-cli, gate-diagnostics
  • packages/auth-common ui.react-types
  • packages/bb-kv-store readme.generated (every README snippet compiled) and legacy/runtime
  • packages/create-blocks-app npm test
  • npm run sync-docs:check
  • npm run check:imports
  • changeset-guard.ts validate-structure
  • changeset-guard.ts verify-coverage
  • changeset-guard.ts verify-umbrella
  • changeset-guard.ts block-major
  • every relative link and #anchor in 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 main commit (e1e484465), and not run again after the rebases: packages/core unit suite, packages/blocks unit suite, packages/bb-kv-store unit suite, packages/bb-auth unit suite, packages/auth-common unit suite, npm run lint, npm run lint:deps and npm run check:api. All passed.

Not run locally: the full npm test across all workspaces, npm run test:e2e:local and 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

  • PR description included
  • Tests are changed or added
  • Relevant documentation is changed or added (and PR referenced)

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

@changeset-bot

changeset-bot Bot commented Nov 18, 2026

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 06072c0

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages
Name Type
@aws-blocks/blocks Patch
@aws-blocks/create-blocks-app Patch
@aws-blocks/create-block Patch

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

xyos added 7 commits November 19, 2026 05:47
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
xyos force-pushed the docs/readme-guide-scaffold branch from 5aec7f3 to 33fa5f7 Compare November 19, 2026 06:11

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant