Skip to content

docs: expand the Customize checklist (src, Actions secrets) - #23

Merged
fabianzimber merged 1 commit into
shiftbloom-studio:mainfrom
dchaudhari7177:docs/expand-customize-checklist
Aug 18, 2026
Merged

fabianzimber merged 1 commit into
shiftbloom-studio:mainfrom
dchaudhari7177:docs/expand-customize-checklist

Conversation

@dchaudhari7177

Copy link
Copy Markdown
Contributor

Closes #19. README only.

Method

Rather than adding the three items named in the issue, I grepped the tree for template placeholders so the checklist is exhaustive by construction. Everything that ships containing your-org, your-scope, YEAR or TODO:

File Placeholder
package.json @your-scope/your-package, TODO: describe your package, your-org/your-repo ×3, empty author
.changeset/config.json changelog[1].repo → your-org/your-repo
LICENSE Copyright (c) YEAR YOUR_NAME
.github/ISSUE_TEMPLATE/bug_report.md @your-scope/your-package in the environment block
src/index.ts TEMPLATE_PACKAGE_NAME
tests/index.test.ts asserts on TEMPLATE_PACKAGE_NAME

The last two rows were not in the issue and are the ones most likely to bite.

Structure

Three groups — Identity, Your code, Publishing — as checkboxes, ending with a "run the four checks once" line.

Two traps get explicit treatment, because in both cases the thing you must change is not in the file you are looking at:

  1. tests/index.test.ts asserts on the placeholder constant. Replace src/index.ts as instructed and the test suite fails, which reads like you broke something.

  2. Deleting src/server.ts is not sufficient. tsup.config.ts has a second config object with entry: { server: "src/server.ts" } and package.json has a ./server export block. I verified this rather than assuming — removing only the file gives:

$ npm run build
Cannot find server: src/server.ts
EXIT=1

with dist/ containing only the index outputs. So the checklist says to remove all three together.

The NPM_TOKEN / NODE_AUTH_TOKEN naming comes from .github/workflows/release.yml (lines 19–20 accept either via secrets.NPM_TOKEN || secrets.NODE_AUTH_TOKEN), and the deliberate guard at line 50 emits Missing npm token. Add a repo secret named NPM_TOKEN (or NODE_AUTH_TOKEN) with an npm Automation token. — so the README now matches the message a user will actually see. "Automation token" is quoted from that message rather than invented.

Also added publishConfig.access and engines.node, since both are decisions a new package should make once and neither was mentioned anywhere.

Verification

npm run build, npm run lint, npm test (1 suite, 1 test passing) all green on Node v24.17.0; git diff --check clean. Only README.md is modified — I did not fill in any placeholder, since this is the template repo.

Customize listed package.json fields and the changeset repo, which is
about half of what actually ships with a placeholder in it. Someone
following it to the end still has your-org, your-scope, YEAR and TODO
in their package.

Rewrite it as a grouped checklist covering identity (including LICENSE
and the bug-report issue template), the source entrypoints, and
publishing. Every item was found by grepping the tree for placeholders,
and the secret names were read from .github/workflows/release.yml rather
than assumed.

Two traps are called out because neither is discoverable from the file
you are editing: tests/index.test.ts asserts on the placeholder constant
in src/index.ts and fails the moment you delete it, and dropping
src/server.ts without also removing the ./server export and the second
tsup config object breaks the build.

Closes shiftbloom-studio#19

@fabianzimber fabianzimber left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@dchaudhari7177 Much thanks for the contribution 👍 the customization documentation looks really good 💯

@fabianzimber
fabianzimber merged commit f1b6f40 into shiftbloom-studio:main Aug 18, 2026
2 of 4 checks passed
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.

docs: expand the Customize checklist (src, Actions secrets)

2 participants