External routes ignore params

Abierto
#349 0 comentarios 0 reacciones 1 asignado Ver en GitHub

@arbrandes ya está trabajando en esto.

Desde el 16/11/2026.

  • #352 de @arbrandes — abierto

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
45/100
Tipo de issue
Error
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
react, typescript
Área
frontend

Línea de trabajo

Start with runtime/routing/utils.ts and runtime/routing/utils.test.ts, especially the existing test for an external route with params; then read types.ts and the migration guide’s URL Config section. The issue establishes that absolute external URLs currently ignore params, but leaves the intended behavior and URL syntax open. Done means the behavior is decided and implemented with tests and matching documentation.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

External routes ignore params. resolveRouteByRole(role, { courseId }) uses courseId when an installed app provides the role, and ignores it when an external route does.

Found while porting Learning's progress tab (openedx/frontend-app-learning#2190), which links to course pages by role. Related to #348.

[!NOTE]
The details below were generated by Claude (Claude Code) and reviewed before posting.

Claude Plan

How a role with params resolves today

  • A role is declared on a route, and the route's path decides which params the role takes: /gradebook/:courseId carries org.openedx.frontend.role.gradebook (src/routes.tsx in openedx/frontend-app-gradebook), instructor-dashboard/:courseId carries org.openedx.frontend.role.instructorDashboard (src/routes.tsx in openedx/frontend-app-instructor-dashboard).
  • A caller passes those params: resolveRouteByRole(gradebookRole, { courseId }) in the instructor dashboard, resolveRouteByRole(instructorDashboardRole, { courseId }) in gradebook.
  • resolveRouteByRole returns isInternal ? generatePath(path, params) : path. A path in this site has its params filled; for anything else the params are ignored, with no warning, and the URL comes back unchanged. The TSDoc says so ("an external URL is returned as configured"), and a test pins it by passing { courseId: 'c1' } for a role whose external URL is https://apps.example.com/profile/ and expecting that URL back.
  • ExternalRoute is a role and a URL. An external route written as https://lms.example.com/courses/:courseId/progress comes back with the literal :courseId in it.
  • The caller cannot tell which case it is in before it calls: who provides a role is a property of the site, not of the role.
  • One exception follows from the same line: an external route written as a path (a single leading /) is classed as internal by isInternalUrl, so its params are filled, and it is linked through react-router.

What the docs say

  • The migration guide's URL Config changes presents the two as interchangeable: URLs "should now be expressed as part of the apps config as route roles, or as externalRoutes, and resolved in code via resolveRouteByRole(). It substitutes route params, drops a trailing splat, and reports whether the result is a path in this site or an external URL". It does not say the substitution applies to one of the two only.
  • No ADR in docs/decisions/ covers route roles with params or external routes; 0013 mentions roles for the course bar's provides.

How it got here

  • #320 added resolveRouteByRole (closing #317 and #319) to replace logic two apps had each written by hand. Both substituted params into whatever the role resolved to, an external URL included: openedx/frontend-app-gradebook#627 called getUrlByRouteRole(instructorDashboardRole)?.replace(':courseId', courseId), and openedx/frontend-app-instructor-dashboard#246's src/utils/routeByRole.ts ran url.replace(`:${name}`, value) for each param before it tested whether the URL was absolute. Neither had a test of an external URL with a param.
  • #320's description states the new behavior ("an external URL is returned as configured") and gives no reason; the PR has no review comments.
  • react-router's generatePath, which #320 uses for the substitution, does not take an absolute URL: on react-router 6.30.6, generatePath('https://lms.example.com/courses/:courseId/progress', { courseId }) returns https:/lms.example.com/courses/<courseId>/progress, the // collapsed.

Where it bites

  • Both call sites above keep a URL of their own for when the role resolves to nothing (gradebookRoute?.url ?? data.gradebookUrl, dashboardRoute?.url ?? instructorDashboardUrl(courseId)), and that fallback is the only way either reaches a destination outside the site with the course in it. A site that declares an external route for one of those roles replaces the fallback with a URL that cannot name the course.
  • The shell's own ProfileLinkMenuItem reaches a user's profile by appending /u/<username> to the profile role's URL, which works for an app route and an external route alike because the role's route takes no param: openedx/frontend-app-profile declares the role on profile and serves the user's page from its child u/:username (src/routes.tsx).
  • Learning declares org.openedx.frontend.role.courseOutline, courseDates, courseProgress and courseware on routes under course/:courseId, and its progress tab links to them by role (openedx/frontend-app-learning#2190). If #348 lets a site point one of them at an external route, the link the site gets has no course in it.

Questions

  • Should a site be able to provide a role whose route takes params with an external route?
  • If so, how does an external route say where the params go?
  • Until then, where does an app author declaring a role, or an operator writing externalRoutes, learn that params are dropped for an external URL?
  • Should the resolver report it when it is handed params it will not use?
Lenguaje dominante
TypeScript
Estrellas
4
Forks
13
Merge medio
3 d 5 h
PR fusionados (30 d)
4

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de openedx/frontend-base

Todos los issues de openedx/frontend-base

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.