Ember Nested Routing: Path Matching and Resolution Design

You define a route for /articles/:id in Ember, expecting the ArticleShow component to render inside an outlet, but the outlet remains empty and the URL resolves only to the parent layout. In Ember's router, nested route rendering depends on two conventions: the child route must be defined under its parent in the router file, and the child's path segments are appended to the parent's path segment. Get the hierarchy or path ordering wrong, and Ember's PathMatcher never evaluates the child route, leaving the outlet unmatched.

Requirements

To follow the design described here you need Ember CLI 3.5 or newer. Older router implementations use a different segment-matching strategy and may not support the activated lifecycle hooks or resolver suspension behavior described in this note. Familiarity with Ember's route definition syntax in router.js (or router.ts) is also required.

Smallest Suitable Design

The minimal route hierarchy that resolves a dynamic segment and renders its corresponding component looks like this:

import EmberRouter from '@ember/router';

const Router = EmberRouter.extend({
  location: 'history'
});

Router.map(function() {
  this.route('articles', { path: '/articles' }, function() {
    this.route('show', { path: '/:id' });
  });
});

export default Router;

In this setup the articles route defines the parent path /articles. The child route show inherits that segment and adds /:id, resulting in the full URL /articles/42. Ember's PathMatcher evaluates URL segments in definition order, stopping at the first match. Because show is defined as a child of articles, the router knows to render the articles outlet and then the show outlet when the URL matches.

The ArticleShow component receives the resolved route context via the activated lifecycle. This hook fires after the router resolves the route, making the id parameter available for conditional rendering or data fetching.

Trust / Data Boundaries

When a route needs to fetch data before its view renders, Ember provides the route resolver pattern. A resolver hook can return a promise that the router suspends rendering until it resolves:

export default Ember.Route.extend({
  model(params) {
    return fetch(`/api/articles/${params.id}`).then(r => r.json());
  },
  activate() {
    // called after model resolves; safe to update DOM
  }
});

Because the router suspends rendering, the view never commits until the data is available. This eliminates race conditions where a component renders with missing or stale parameters. The activated hook then runs in the rendered context, guaranteeing that this refers to the component instance with its bound parameters.

Operational Checks

1. Run ember serve from the project root. No special permissions are required beyond read access to the running app and the router file.
2. Open http://localhost:4200/articles/42 in a browser.
3. Open the Ember inspector (typically http://localhost:4200/inspect).
4. Expand the route tree under articles. Confirm that the show route appears as a child and that the id parameter reads 42.
5. Check the console for any suspension warnings if you have a resolver that returns a pending promise; the view should not render until the promise resolves.

Risk: If the child route path overlaps a sibling definition or if the parent route path is omitted, the PathMatcher may match an unintended route, causing the wrong outlet to populate or the URL to resolve to an empty state.

Failure Modes and Design-Changing Conditions

• CLI version < 3.5: The router may not support resolver suspension or the activated lifecycle in the form described here. Upgrade the CLI or adjust the resolver pattern to match the older router API.
• Incorrect nesting: Defining the child route outside the parent's this.route() callback causes the path segments to not inherit, and the PathMatcher evaluates the child as a top-level route with a mismatched URL.
• Path-segment collision: If a sibling route defines a path that shares prefix segments with the nested route, the order of definitions in the router map determines which route wins. Reordering or disambiguating paths may be required.
• Resolver rejection: If a route resolver throws or its promise rejects, the router aborts rendering and surfaces an error state. Ensure resolvers handle failures gracefully.

To check whether a condition invalidates the design, repeat the operational checks after modifying the router file or CLI version. If the route tree in the inspector no longer shows the expected hierarchy, the current design does not apply.