docs(static-files): document before/after handler ordering

[dawsontoth]

Draft until HarperFast/harper#1574 merges and its release version is confirmed — the v5.2.0 badges and changelog line in this page assume the next feature release; adjust if it ships under a different version.

What

Documents the static plugin's before / after handler-ordering options added in HarperFast/harper#1574, and fixes the SPA client-side routing example, which currently documents a config that breaks REST.

Why

The static handler runs before authentication — and therefore before the REST handler — by default. The existing "SPA client-side routing" example (notFound + fallthrough: false) therefore answers every unmatched GET with index.html, including GETs for exported REST resources: the application's API silently becomes unreachable over GET. This bit the create-harper SPA templates, fixed in HarperFast/create-harper#109.

With harper#1574 in place, one line makes the recipe work as readers assume it does:

rest: true

static:
  files: 'dist/**'
  after: 'rest' # let REST match first; only unmatched URLs get the fallback
  notFound:
    file: 'dist/index.html'
    statusCode: 200
  fallthrough: false

Changes to reference/static-files/overview.md

• New Handler Ordering section: default position in the middleware chain, why it exists (file requests skip credential parsing), the fallthrough: false trap, the after: 'rest' recipe with request mappings, and the new startup warning.
• before and after added to Additional Options (with v5.2.0 badges), including before: false to clear the default constraint.
• SPA client-side routing example corrected to include after: 'rest', with a note about pre-5.2 behavior and a pointer to hash-based routing as the version-independent alternative (also keeps index.html cacheable at a single URL).
• Custom 404 page example notes when after: 'rest' is needed.

Verification

• npm run format:check clean; npm run build succeeds (the one broken-anchor warning is pre-existing in release-notes/v5-lincoln/5.1, unrelated to this page).
• The behavior described was verified end-to-end against a built harper#1574 dist: with after: 'rest', REST resources return JSON while unmatched deep links receive the index.html fallback.

Related: HarperFast/harper#1574 - HarperFast/create-harper#109

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request updates the static files documentation to cover the new before and after handler ordering options introduced in v5.2.0, including a new section on handler ordering and updated SPA client-side routing examples. The review feedback focuses on improving clarity and technical accuracy, such as replacing colloquial terms like 'answers' with more standard terminology, and resolving a potential inconsistency regarding whether configuration changes require a restart.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-562

This preview will update automatically when you push new commits.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-562

This preview will update automatically when you push new commits.