diff --git a/.changeset/app-routes-redirect-config.md b/.changeset/app-routes-redirect-config.md index a04ddec744..ce43e3c159 100644 --- a/.changeset/app-routes-redirect-config.md +++ b/.changeset/app-routes-redirect-config.md @@ -3,3 +3,15 @@ --- Added support for configuring URL redirects on the `app/routes` extension. Redirects can be configured through `app-config` as an array of `{from, to}` path pairs, which will cause navigation to the `from` path to be redirected to the `to` path. + +For example: + +```yaml +app: + extensions: + - app/routes: + config: + redirects: + - from: /old-path + to: /new-path +``` diff --git a/docs/frontend-system/building-apps/03-built-in-extensions.md b/docs/frontend-system/building-apps/03-built-in-extensions.md index 05e60b54b7..637aded411 100644 --- a/docs/frontend-system/building-apps/03-built-in-extensions.md +++ b/docs/frontend-system/building-apps/03-built-in-extensions.md @@ -183,6 +183,30 @@ Be careful when overriding this extension, as to do so correctly you must consid - Remember to user the route refs for getting paths dynamically, otherwise if an adopter modifies a path through configuration, the route is not going to point to the configured path; - Adopters expect to be able to customize the `NotFoundErrorPage` component via Components API, you should render this component for routes not configured. +#### Configurations + +| Key | Type | Default value | Description | +| ----------- | -------------------------------- | ------------- | -------------------------------------------------------------------- | +| `redirects` | `{ from: string, to: string }[]` | - | A list of URL redirects. Navigation to `from` will redirect to `to`. | + +##### Configuring redirects + +You can configure redirects for the `app/routes` extension to automatically redirect users from one path to another. This is useful when restructuring your app's routes, for example after moving or renaming plugin pages. + +```yaml title="app-config.yaml" +app: + extensions: + - app/routes: + config: + redirects: + - from: /old-path + to: /new-path + - from: /legacy/page + to: /updated/page +``` + +Redirects are matched before any regular routes and use the [`replace`](https://developer.mozilla.org/en-US/docs/Web/API/History/replaceState) strategy, so the old path will not appear in the browser history. + #### Inputs | Name | Description | Type | Optional | Default | Extension creator | diff --git a/docs/frontend-system/building-apps/08-migrating.md b/docs/frontend-system/building-apps/08-migrating.md index ceba8fd868..2784b10b7a 100644 --- a/docs/frontend-system/building-apps/08-migrating.md +++ b/docs/frontend-system/building-apps/08-migrating.md @@ -800,6 +800,22 @@ If you are using [app feature discovery](../architecture/10-app.md#feature-disco Continue this process for each of your legacy routes until you have migrated all of them. For any plugin with additional extensions installed as children of the `Route`, refer to the plugin READMEs for more detailed instructions. For the entity pages, refer to the [separate section](#catalog-entity-page). +##### Migrating `` routes + +If your old routes include `` elements to forward users from one path to another, you can replace them with the built-in redirect configuration on the `app/routes` extension: + +```yaml title="app-config.yaml" +app: + extensions: + - app/routes: + config: + redirects: + - from: /old-path + to: /new-path +``` + +See the [`app/routes` built-in extension documentation](./03-built-in-extensions.md#configuring-redirects) for more details. + ### Migrating core, internal and third-party plugins For certain core plugins — such as the Catalog plugin's entity page — we provide a dedicated step-by-step migration guide, since these plugins often require a more gradual approach due to their complexity.