svelte-spa-router: Hash Routing for Svelte 5

Why svelte-spa-router Fits Static Svelte 5 Applications

svelte-spa-router solves client-side route selection for applications built with Svelte 5 and packaged as a Single Page Application. Its defining choice is to keep the route in the fragment after `#`, so a static `index.html` can expose application views such as `index.html#/profile` and `index.html#/book/42`. The page component can change without requiring the server to return a different document.

That design is aimed at applications deployed as static files, internal tools, and interfaces behind authentication where search engine indexing is not a primary concern. It also suits projects that need shareable fragment links but cannot or do not want to configure server-side fallback rules. The README contrasts this with routers using the HTML5 history API, which can produce URLs such as `http://example.com/profile` but require backend processing when users open or refresh those paths.

The trade-off appears in the URL itself. Fragment routes are easy for a static host to serve, but they carry the application state after `#`. Applications that need clean paths for indexing, external consumers, or existing server infrastructure should confirm that this routing model matches those requirements before choosing the package.

Route Matching Through Fragments and regexparam

The router reads navigation state from the portion of the URL following `#`. A link to `#/book/42` therefore identifies the `book/42` route, while the base `index.html` remains the document loaded by the host. Changing the fragment changes the selected view without requiring the server to understand `/book/42` as a separate resource.

Route patterns are parsed with `regexparam`, the package the README describes as tiny. Patterns can include parameters and optional segments, with `/book/:id?` given as the example. The repository also exposes focused package entry points for `./active` and `./wrap`, alongside the main `.` export for `Router.svelte`. These export declarations show that consumers can import separate Svelte-related entry points rather than relying on one undifferentiated module.

The repository layout includes source under `src/`, generated package output under `dist/`, documentation under `docs/`, examples under `examples/`, and browser tests under `test/` with Playwright configuration. Based on that layout, the router is packaged as compiled Svelte output with TypeScript declaration files. The README does not document the complete route-matching algorithm or every advanced API, so the linked documentation is the appropriate place to verify those details.

Building svelte-spa-router and Running Its Basic Example

The README directs contributors to the repository's examples. Its documented sequence installs workspace dependencies, builds the router package, changes into an example, installs that example's dependencies, and starts its development server. The commands below reproduce that sequence. The reader should see the basic-routing application at `http://localhost:5173` after `pnpm run dev` starts.

From the repository root, install dependencies and build the package:

pnpm install
pnpm run build

Then change into the basic routing example and start its development server:

cd examples/basic-routing
pnpm install
pnpm run dev

The repository declares `[email protected]` in `package.json`. It also defines `pnpm run check`, `pnpm run lint`, and Playwright-based test scripts. The README's sample walkthrough only documents installation, building, and development startup, so those additional scripts are relevant to contributors and maintainers rather than the basic example tutorial.

For an application consumer rather than a contributor, the README links to a Getting Started page but does not include the package installation command or a complete application component example. The repository's online documentation and `examples/basic-routing/` directory are the documented places to verify the first consumer-facing setup.

Static Hosting Benefits and URL Boundaries

The main operational advantage is that a static host can serve one application document for every fragment route. Refreshing `http://example.com/#/profile` still leaves the browser requesting `http://example.com/`, with `/profile` carried in the fragment. Sharing the link therefore does not require the host to resolve `/profile` as a server resource. The README presents this as especially suitable for fully static SPAs and applications where SEO is not the concern.

That benefit also defines the package's boundary. Fragment-based navigation does not turn application views into ordinary server paths. If another system expects routes such as `http://example.com/profile`, or if the product requires those paths to be indexed as separate documents, this router does not provide that URL model. It should not be treated as a substitute for server rendering, static route generation, or host rewrite configuration.

Browser support is aimed at recent Chrome, Edge, Firefox, and Safari versions. Internet Explorer is outside the project's support goal. The README notes that some users reportedly used the router with IE11 after transpilation, but explicitly says that behavior is not guaranteed. That distinction matters for organizations that still carry an Internet Explorer support obligation.

Svelte 5 Compatibility and Package Maintenance

The current `package.json` identifies version `5.1.1`, targets Svelte 5, uses ES modules through `"type": "module"`, and publishes only the `dist` directory. The README separately directs Svelte 3 and 4 users to the `v4` branch. This is a clear compatibility boundary rather than an incidental version difference: an application on an older Svelte generation should not assume that the current package line supports it.

Release records show `[email protected]` on 2026-06-25, `[email protected]` on 2026-04-28, and `v5.0.1` on 2026-04-02. The repository was last pushed on 2026-10-15 and is not archived. Those facts support recent project activity, but the repository does not establish a fixed support window, a long-term compatibility policy, or the exact contents of each release.

The MIT license permits use, modification, distribution, and reuse under its conditions. It does not establish compatibility with every Svelte compiler version or deployment environment. Applications upgrading from Svelte 3 or 4 should treat the documented `v4` branch as a separate compatibility target. Svelte 5 applications should review the repository's upgrading documentation before changing package versions.

Fragment Routing Versus History-Based Routing

The real alternative described by the project is a router based on the HTML5 history API. Such a router can display cleaner paths such as `http://example.com/profile`, but the README says that opening, sharing, or refreshing those URLs requires server processing. For a fully static deployment, the host must provide fallback behavior so that the application document is returned for application routes.

This difference should drive the decision. Choose svelte-spa-router when static hosting, a small integration, and simple refresh behavior matter more than clean paths. Inspect a history-based router instead when route URLs must resemble conventional site paths, the application already has a server capable of handling direct requests, or server-side rendering and search-engine treatment are central requirements.

The comparison is not about component syntax. Both approaches address client-side navigation in an SPA, but they assign different responsibilities to the URL and hosting layer. The README specifically positions svelte-spa-router where server-side processing is undesirable or unavailable. Choosing it for an application that assumes ordinary path-based routing would create a mismatch at deployment time.

Editorial conclusion

Adopt svelte-spa-router for a Svelte 5 SPA deployed as static files or one that does not depend on search-engine-readable paths. Do not choose it when clean server-backed URLs, indexable application routes, or guaranteed Internet Explorer support are priorities. Before adoption, verify that the host serves the base application document, consult the getting-started documentation, and test refresh and shared-link behavior in the intended browsers. URL fragments are handled by the browser and are not sent to the server.

Frequently asked questions

Official sources

1. ItalyPaleAle/svelte-spa-router on GitHub
2. License: MIT
3. Project website
4. README
5. Releases