HarperFast / HarperFast/harper

static: support URL-glob to file-path mapping for SPA fallback (follow-up to #1574)

Open
#1,716 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
89
Forks
10
Avg merge
2d 6h
Merged PRs (30d)
200

Description

## Context

Raised in review of #1574 (which fixes the history-mode SPA / REST fallthrough ordering footgun via `static: { after: 'rest' }`): https://github.com/HarperFast/harper/pull/1574#issuecomment-4880616338

The static handler's `notFound` fallback maps *any* unmatched URL to a single file (e.g. `index.html`) — the "real looking URLs and query string parameters" case for SPA client-side routing. #1574 makes the ordering correct (REST/auth match first, only unmatched URLs fall through), but the fallback itself is still all-or-nothing: one URL space (`urlPath`) maps to one `notFound` file.

## Question / proposal

Should Harper support an explicit URL-glob → file-path mapping for the static handler, rather than (or in addition to) the single catch-all `notFound` fallback? This would let a config say something like "requests matching `/app/**` fall back to `app/index.html`, requests matching `/admin/**` fall back to `admin/index.html`" — useful for:

- Multi-SPA / multi-entry-point deployments served from one Harper instance.
- Explicit, fast glob→file dispatch instead of relying on ordering + a single fallback to get the right file for the right route family.

## Scope

Design question, not yet scoped to an implementation. Worth discussing whether this belongs on the static handler's existing `notFound` option (extended to accept a list of `{ match, file }` rules) or as a separate feature.

Contributor guide

Open the contributing guide

Research direction

Start by reading the static handler's existing notFound option and the linked #1574 review discussion. Compare the proposed list of { match, file } rules with the current single-file fallback, then define the configuration shape and behavior for /app/** and /admin/** mappings before implementation.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, node.js
Domain
backend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.