Route Manager API by nickschot · Pull Request #1169 · emberjs/rfcs

nickschot · 2026-02-26T15:20:41Z

Propose Route Manager API

Rendered

Summary

This pull request is proposing a new RFC.

To succeed, it will need to pass into the Exploring Stage, followed by the Accepted Stage.

A Proposed or Exploring RFC may also move to the Closed Stage if it is withdrawn by the author or if it is rejected by the Ember team. This requires an "FCP to Close" period.

An FCP is required before merging this PR to advance to Accepted.

Upon merging this PR, automation will open a draft PR for this RFC to move to the Ready for Released Stage.

Exploring Stage Description

This stage is entered when the Ember team believes the concept described in the RFC should be pursued, but the RFC may still need some more work, discussion, answers to open questions, and/or a champion before it can move to the next stage.

An RFC is moved into Exploring with consensus of the relevant teams. The relevant team expects to spend time helping to refine the proposal. The RFC remains a PR and will have an Exploring label applied.

An Exploring RFC that is successfully completed can move to Accepted with an FCP is required as in the existing process. It may also be moved to Closed with an FCP.

Accepted Stage Description

To move into the "accepted stage" the RFC must have complete prose and have successfully passed through an "FCP to Accept" period in which the community has weighed in and consensus has been achieved on the direction. The relevant teams believe that the proposal is well-specified and ready for implementation. The RFC has a champion within one of the relevant teams.

If there are unanswered questions, we have outlined them and expect that they will be answered before Ready for Release.

When the RFC is accepted, the PR will be merged, and automation will open a new PR to move the RFC to the Ready for Release stage. That PR should be used to track implementation progress and gain consensus to move to the next stage.

Checklist to move to Exploring

The team believes the concepts described in the RFC should be pursued.
The label S-Proposed is removed from the PR and the label S-Exploring is added.
The Ember team is willing to work on the proposal to get it to Accepted

Checklist to move to Accepted

This PR has had the Final Comment Period label has been added to start the FCP
The RFC is announced in #news-and-announcements in the Ember Discord.
The RFC has complete prose, is well-specified and ready for implementation.
- All sections of the RFC are filled out.
- Any unanswered questions are outlined and expected to be answered before Ready for Release.
- "How we teach this?" is sufficiently filled out.
The RFC has a champion within one of the relevant teams.
The RFC has consensus after the FCP period.

NullVoxPopuli · 2026-02-26T16:02:23Z

text/1169-route-manager-api.md

+	capabilities: Capabilities;
+
+	// Responsible for the creation of a RouteStateBucket. Returns a RouteStateBucket, defined by the manager implementation.
+	createRoute: (factory, args: CreateRouteArgs) => RouteStateBucket;


pro/cons of this being sync vs async?

would async route creation instead by a router-manager concern?

This instantiates the bucket (which may or may not contain or even be what we'd consider a route instance). I've had a prototype where I did just in time creation of the actual route instance within the 'enter' hook and destroyed on 'exit' for a hypothetical route class where the lifetime of the instance was not singleton but instead only lasted while visiting a route.

This would indeed be a manager concern. 'createRoute' may seem a bit confusing in that sense but it's what the Router would need to handle routes through the manager API.

NullVoxPopuli · 2026-02-26T16:03:21Z

text/1169-route-manager-api.md

+
+The `createRoute` method on the Route Manager is responsible for taking the Route’s factory and arguments and based on that return a `RouteStateBucket` .
+
+***Note:** It is up to the manager to decide whether or not this method actually instantiates the factory or if that happens at a later time, depending on the specific lifecycle the manager implementation wants to provide.*


where could that happen?

I think my other comment answered this already, but this would be left mostly to the route manager implementation. It does have to make sure the bucket has the info it needs for when the router calls the various lifecycle methods on the manager.

NullVoxPopuli · 2026-02-26T16:04:13Z

text/1169-route-manager-api.md

+
+#### `getDestroyable`
+
+The `getDestroyable` method takes a `RouteStateBucket` and will return the `Destroyable` if applicable. This can be used by the manager implementation to wire up the lifetime of the route.


lifetime linking typically happens during creation -- getDestroyable is for getting what was linked

Yes indeed, reading this seems to indeed give the wrong impression. I'll revise the sentence a bit soon.

nickschot · 2026-03-06T19:10:04Z

text/1169-route-manager-api.md

+	capabilities: Capabilities;
+
+	// Responsible for the creation of a RouteStateBucket. Returns a RouteStateBucket, defined by the manager implementation.
+	createRoute: (factory, args: CreateRouteArgs) => RouteStateBucket;


We could likely specify factory as type object, since it needs to work with setRouteManager

nickschot · 2026-03-06T19:31:35Z

text/1169-route-manager-api.md

+The minimal API for a Route Manager consists of `capabilities`, `createRoute` and a `getDestroyable` method.
+
+```typescript
+interface RouteManager {


Clarify that this is NOT the full interface. It is expanded upon further into the RFC.

nickschot · 2026-03-06T19:44:15Z

text/1169-route-manager-api.md

+	signal: AbortSignal;
+
+	// A WeakMap of ancestor promises that can be used to await async ancestor behaviour.
+	ancestorPromises: WeakMap<RouteInfo, ReturnType<RouteManager.enter | RouteManager.update>>


This could be a function that takes a RouteInfo.

@nickschot @mansona I think I need some clarification on this

It means we don't need to specify/expose the internal WeakMap implementation. So we replace this with a function that takes a RouteInfo and returns the promise (in the current design).

I'll mark the WeakMap as private and added a getAncestorPromise() method then.

nickschot · 2026-03-06T19:46:33Z

text/1169-route-manager-api.md

+	ancestorPromises: WeakMap<RouteInfo, ReturnType<RouteManager.enter | RouteManager.update>>
+
+	// Retrieve the resolvedContext of an ancestor route.
+	getResolvedContext: (routeInfo: RouteInfo) => ReturnType<RouteManager.resolvedContext> | undefined;


This might need to be obligatory since the point of enter/update is to provide a context (even if its undefined).

Revisit why we did not tie this into the return value of the enter/update hook. These are tied to the specific navigation.

nickschot · 2026-03-06T20:07:16Z

text/1169-route-manager-api.md

+
+```typescript
+interface RouteManager {
+	getInvokable: (bucket: RouteStateBucket) => object;


Glint should have a better type for this, something like ComponentLike<WithoutArgs>, check that.

Wasn't able to find WithoutArgs, there is WithBoundArgs and WithBoundPositionals but I'm not sure either is wanted here?

nickschot · 2026-03-06T20:25:25Z

text/1169-route-manager-api.md

+	didEnter: (bucket: RouteStateBucket, args: NavigationState) => void;
+
+	// Similar to willEnter, but called on a Route that was also part of the previous navigation.
+	willUpdate: (bucket: RouteStateBucket, args: NavigationState & NavigationActions) => void;


willEnter/didEnter and didEnter/didUpdate may be identical. We need to verify if there is a reason for these to exist separately. Also explicitly check if the classic routes need it, in that case we could also put it on the classic capability.

Did you mean willEnter/didEnter and willUpdate/didUpdate?

I think we've gone back and forth on the need for the update hooks. They are not strictly necessary (the update can be implicated through existing state)

Yes, there's 2 things:

Do we need separate willEnter/willUpdate and didEnter/didUpdate hooks? Timing should be identical between them, so likely not.

Do we need the update hook at all (which we've gone back and forth on). An alternative here is to provide a helper function to do the diffing instead. Main thing we need to check is the compat situation where the interleaving may or may not require a separate method here depending on timing.

I confused myself there a bit.

.*{Enter,Update} have same timing, not {will,did}*.

update is dev sugar for triggering enter on the currently active route, which can be handled outside this manager

Therefore, I'd say we drop it and make it a capability if desired.

nickschot · 2026-03-06T20:32:22Z

text/1169-route-manager-api.md

+
+	serializeQueryParam(bucket: RouteStateBucket, value: unknown, urlKey: string, defaultValueType: string);
+	deserializeQueryParam(bucket: RouteStateBucket, value: unknown, urlKey: string, defaultValueType: string);
+


We seem to be missing the functions that (de)serialize the model id from a passed model. Check if we need that here.

Would potentially not be needed if we fully deprecate passing non-strings to transitions/linkto's.

alexraputa · 2026-03-10T11:51:56Z

I'm trying to better understand the design constraints behind the transitional Route Manager approach.

What are the main reasons for introducing this intermediate layer first, instead of designing a new web-native router API directly? In particular, I'm curious which problems this staged approach is meant to de-risk, and what the main pitfalls would be if Ember tried to jump straight to a new router model.

For example, are the biggest concerns around backwards compatibility, migration strategy, internal architecture, ecosystem impact, or something else?

pichfl · 2026-03-10T12:58:50Z

@alexraputa you summarized the reasoning behind this and many other RFCs for Ember very well in your question.

The Motivation section reflects just that.

We want to:

ensure backwards compatibility
provide deprecations and provide a migration strategy
make internals more resilient and easier to maintain
keep the ecosystem impact low: ship new features without breaking applications

Directly ripping out and replacing the existing router API would go against these concepts.

alexraputa · 2026-03-10T13:11:16Z

One thing I'm still curious about is the maintenance tradeoff: does introducing a transitional Route Manager risk expanding the router surface area for a long time, and if so, what are the intended exit criteria?

I'm wondering how the team thinks about preventing an intermediate abstraction from becoming another permanent layer Ember Core has to support indefinitely.

alexraputa · 2026-03-10T13:11:51Z

Are there specific capabilities of a future web-native router that this Route Manager is explicitly meant to unlock later?

pichfl · 2026-03-10T16:13:42Z

Not sure what a "future web-native router" will be, but the scope of this RFC doesn't cover anything like that. This is not the RFC dealing with a potential replacement.

As stated, the goal is to increase the surface area and provide a clear and consistent interface that replaces the entangled situation we have without causing disruptions and allowing to iterate from there.

As written in the motivation, it is an implementation detail targeted at maintainers of the framework.

alexraputa · 2026-03-10T16:45:39Z

@pichfl thanks, that helps clarify the scope.

github-actions bot added the S-Proposed In the Proposed Stage label Feb 26, 2026

NullVoxPopuli reviewed Feb 26, 2026

View reviewed changes

NullVoxPopuli added S-Exploring In the Exploring RFC Stage and removed S-Proposed In the Proposed Stage labels Feb 27, 2026

nickschot and others added 8 commits March 5, 2026 14:56

Initial RFC draft

20bec75

Cleanup

f12641b

Add proper relative links to sections specified later

f5eccb5

Fix syntax highlighting

39414bd

Less shouting

4d5edf8

Add PR URL to frontmatter

f1eea8c

Add PR number to filename

43b48e7

Clarified phrasing and filled remaining TBDs

b633f2e

pichfl force-pushed the nickschot/route-manager-api branch from 3c87662 to b633f2e Compare March 5, 2026 13:57

nickschot marked this pull request as ready for review March 5, 2026 14:17

nickschot commented Mar 6, 2026

View reviewed changes

Make update hooks optional

4e399eb

pichfl added 2 commits March 10, 2026 18:45

Clarify class shape

6b68259

Improve (pseudo-)typing

bcd03f7


		The `createRoute` method on the Route Manager is responsible for taking the Route’s factory and arguments and based on that return a `RouteStateBucket` .

		*Note: It is up to the manager to decide whether or not this method actually instantiates the factory or if that happens at a later time, depending on the specific lifecycle the manager implementation wants to provide.*


		#### `getDestroyable`

		The `getDestroyable` method takes a `RouteStateBucket` and will return the `Destroyable` if applicable. This can be used by the manager implementation to wire up the lifetime of the route.


		serializeQueryParam(bucket: RouteStateBucket, value: unknown, urlKey: string, defaultValueType: string);
		deserializeQueryParam(bucket: RouteStateBucket, value: unknown, urlKey: string, defaultValueType: string);

Uh oh!

Conversation

nickschot commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Propose Route Manager API

Summary

Checklist to move to Exploring

Checklist to move to Accepted

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nickschot Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nickschot Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alexraputa commented Mar 10, 2026

Uh oh!

pichfl commented Mar 10, 2026

Uh oh!

alexraputa commented Mar 10, 2026

Uh oh!

alexraputa commented Mar 10, 2026

Uh oh!

pichfl commented Mar 10, 2026

Uh oh!

alexraputa commented Mar 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

nickschot commented Feb 26, 2026 •

edited

Loading

nickschot Feb 26, 2026 •

edited

Loading

nickschot Mar 6, 2026 •

edited

Loading