Body
Summary
Astro is a server-first framework. As such, it has always relied on the Multi-Page Application (MPA) architecture, meaning that navigations result in a full page refresh and server round-trip.
This proposal offers an opt-in Client-side Routing (CSR) experience, typically associated with Single-Page Application (SPA) architectures.
Note:
For a great overview of relevant terms (MPA/SPA/PEMPA/PESPA), see The Web’s Next Transition by Kent C. Dodds.
Background & Motivation
As users build increasingly complex experiences with Astro, UI Persistence has surfaced as a clear missing piece in the full Astro story. Client-side routing is currently the only way to achieve UI persistence across navigations.
MPAs are the backbone of the web and remain a natural default for Astro projects. SPAs come with their own set of incredibly complex considerations and drawbacks—importantly, we do not believe that client-side routing is a "solved problem" despite becoming the default approach in the industry.
However, the team has discussed a mythical "SPA mode" since the earliest days of the project. Now that we are extremely confident in Astro's mental model and internal priorities, there is no better time to begin layering in new primitives to round out Astro's use cases.
Goals
🔵 points are not finalized, should be discussed and resolved during prototyping
- New client-side routing behavior should be entirely opt-in
- Maintain Astro's 0 JS defaults
- Preserve server routing as the default approach
- Client-side routing should support all valid
output modes
- No changes to Astro's existing file-based routing system
- Avoid encoding layout information in the file structure
- 🔵 Can layout boundaries be derived in the compiler or other methods?
- Enable UI Persistence
- Components (🔵 islands only?) should be able to maintain state across soft navigations
- Should this be automatically applied or require user opt-in?
- 🔵 Does this require diffing?
<head> elements (title, link, script, etc) should be swapped automatically- Out-of-the-box accessibility best practices
- Route changes should be announced to screen readers
- Focus / scroll management should be automatic
- Use the platform. Lean on standard browser APIs as much as possible
- Future friendly. Support (at the very least, do not block) bleeding-edge APIs such as the View Transitions API and forthcoming
navigation API
Non-Goals
- Ability to render Astro components on the client. Astro is a server-first framework that must be rendered on a server (either at build or request time)
- Other PEMSPA/PESPA primitives such as forms, actions, mutations
Body
Summary
Astro is a server-first framework. As such, it has always relied on the Multi-Page Application (MPA) architecture, meaning that navigations result in a full page refresh and server round-trip.
This proposal offers an opt-in Client-side Routing (CSR) experience, typically associated with Single-Page Application (SPA) architectures.
Background & Motivation
As users build increasingly complex experiences with Astro, UI Persistence has surfaced as a clear missing piece in the full Astro story. Client-side routing is currently the only way to achieve UI persistence across navigations.
MPAs are the backbone of the web and remain a natural default for Astro projects. SPAs come with their own set of incredibly complex considerations and drawbacks—importantly, we do not believe that client-side routing is a "solved problem" despite becoming the default approach in the industry.
However, the team has discussed a mythical "SPA mode" since the earliest days of the project. Now that we are extremely confident in Astro's mental model and internal priorities, there is no better time to begin layering in new primitives to round out Astro's use cases.
Goals
outputmodes<head>elements (title,link,script, etc) should be swapped automaticallynavigationAPINon-Goals