fix(uploader): set the manifest fallback so SPA deep links resolve - #18
Merged
Conversation
An arweave/paths manifest serves only the paths it lists, so a single-page
app deployed with this tool 404s every route that is not a real file — the
root loads and /settings does not. The manifest was built with `index` but
never `fallback`, which is the field gateways use for an unlisted path.
The README has advertised "404 Fallback Detection: Automatically detects and
sets 404.html as fallback" since before this change, but the string
`fallback` appeared nowhere outside that README: documented, never
implemented. This makes the claim true.
`404.html` is used when the build emits one, matching the convention static
hosts already follow. `--fallback-file <path>` overrides it, so an SPA whose
build only produces index.html can point at that rather than inventing a 404
file. A named file that is not in the folder is an error rather than a silent
skip — skipping would ship exactly the broken manifest this prevents.
Note the shape: `fallback` takes an `{ id }` where `index` takes a `{ path }`.
The v0.2.0 spec differs between the two, and a `{ path }` here is silently
ignored by gateways.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The check ran after every file had been uploaded and paid for, so a mistyped --fallback-file billed the whole deploy and then threw.
path.relative yields backslashes on Windows and those strings become arweave/paths keys verbatim, so a deploy from Windows 404s every nested asset and never matches the dir/index.html directory-index rule.
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
An
arweave/pathsmanifest serves only the paths it lists, so any single-page app deployed with this tool 404s every route that isn't a real file — the root loads,/settingsdoesn't.uploadFolderbuilt the manifest withindexbut neverfallback:The README has advertised "404 Fallback Detection: Automatically detects and sets 404.html as fallback", but the string
fallbackappeared nowhere outside that README — documented, never implemented. Found while deploying console.ar.io: every deep link 404'd in production.Change
404.htmlbecomes the manifest fallback when the build emits one--fallback-file <path>overrides it, so an SPA that only buildsindex.htmlcan point at that instead of inventing a 404 fileShape matters:
fallbacktakes an{ id }whereindextakes a{ path }. The v0.2.0 spec differs, and a{ path }here is silently ignored by gateways.Verification
tests/unit/uploader-manifest-fallback.test.ts) covering: 404.html detected; id-not-path shape; no fallback when absent (unchanged behaviour); explicit override; SPA opt-in via index.html; missing file errorstsc --noEmitclean,pnpm buildclean--fallback-fileappears indeploy --helpandupload --help