docs: cover the SPA fallback and correct the release process - #25
Merged
Conversation
The fallback is the failure people actually hit, and it appeared only as a feature bullet. Also removes the changesets instructions — there is no .changeset directory and releases run on semantic-release.
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
1 participant
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.
What changed
Leads with the promise. The opening line was
"a Node.js command-line tool designed to streamline the deployment of web applications"— category-first, and the same weakness the old GitHub description had. Now it opens with what you get, and points at the GitHub Action, which the intro never mentioned despite being how most people adopt this.New "Single-page apps" section. The fallback is the failure users actually hit, and it appeared only as one bullet in the feature list. The section explains why a manifest 404s unlisted paths, gives both fixes (
cp index.html 404.htmlor--fallback-file index.html), and warns about the post-deploy cache window that makes a correct deploy look broken for about a minute.--fallback-fileadded to the flag reference. It was missing entirely from Command Options.--deploy-filenow says what it does differently — single file, no manifest, so ArNS resolves straight to the file and manifest-only options do not apply. Previously the README only said "supports a folder or a single file", which hides the surprise.Three new troubleshooting entries for the failures people will search: deep links 404ing, deep links 404ing right after a redeploy, and the relative-path error from
--fallback-file.Corrections
Changesets is documented but does not exist. No
.changesetdirectory, not a dependency, and the contributing steps told people to runpnpm changeset. Replaced with how releases actually work: semantic-release on merge tomain, which commit types trigger what, and that publishing runs over OIDC trusted publishing with no stored token.Also: the Claude skill
examples/claude-skill/deploy.mdhad no fallback guidance at all, so an agent following it would ship exactly the bug this release fixed. Added the SPA section and — importantly — told it to verify a deep link after deploying rather than the homepage, since the homepage returns 200 either way and proves nothing.