From cfb678216feb2b5521af494897f5cc45d5b6c4dd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?V=C3=ADctor=20Fern=C3=A1ndez=20de=20Alba?=
 <sneridagh@gmail.com>
Date: Wed, 22 Jan 2025 12:11:11 +0100
Subject: [PATCH] Document routes API (#6604)

Co-authored-by: Steve Piercy <web@stevepiercy.com>
---
 .../how-to-guides/instantiate-registry.md     |  1 +
 .../docs/how-to-guides/register-routes.md     | 55 +++++++++++++++++++
 packages/registry/docs/index.md               |  3 +-
 packages/registry/news/6604.documentation     |  1 +
 4 files changed, 59 insertions(+), 1 deletion(-)
 create mode 100644 packages/registry/docs/how-to-guides/register-routes.md
 create mode 100644 packages/registry/news/6604.documentation

diff --git a/packages/registry/docs/how-to-guides/instantiate-registry.md b/packages/registry/docs/how-to-guides/instantiate-registry.md
index f915e983fe..40db6fce10 100644
--- a/packages/registry/docs/how-to-guides/instantiate-registry.md
+++ b/packages/registry/docs/how-to-guides/instantiate-registry.md
@@ -46,6 +46,7 @@ export type ConfigData = {
   widgets: WidgetsConfig | Record<string, never>;
   addonReducers?: AddonReducersConfig;
   addonRoutes?: AddonRoutesConfig;
+  routes?: Array<ReactRouterRouteEntry>;
   slots: SlotsConfig | Record<string, never>;
   components: ComponentsConfig | Record<string, never>;
   utilities: UtilitiesConfig | Record<string, never>;
diff --git a/packages/registry/docs/how-to-guides/register-routes.md b/packages/registry/docs/how-to-guides/register-routes.md
new file mode 100644
index 0000000000..41b79656c0
--- /dev/null
+++ b/packages/registry/docs/how-to-guides/register-routes.md
@@ -0,0 +1,55 @@
+---
+myst:
+  html_meta:
+    "description": "How to register new routes in @plone/registry"
+    "property=og:description": "How to register new routes in @plone/registry"
+    "property=og:title": "How to register new routes in @plone/registry"
+    "keywords": "Volto, Plone, frontend, React, configuration, routes, React Router"
+---
+
+# Register new routes
+
+The `config.registerRoute` method adds a route to the configuration registry.
+It saves the routes in the `config.routes` key in the configuration object.
+You should provide one route at a time.
+Each route must have the following data shape.
+
+```ts
+type ReactRouterRouteEntry = {
+  type: 'route' | 'index' | 'layout' | 'prefix';
+  path: string;
+  file: string;
+  options?: {
+    id?: string;
+    index?: boolean;
+    caseSensitive?: boolean;
+  };
+  children?: ReactRouterRouteEntry[];
+};
+```
+
+The `type`, `path`, and `file` are mandatory.
+The `type` key specifies the route type to create, specifically one of `route`, `index`, `layout`, or `prefix`.
+The type `route` can contain nested routes.
+
+```{info}
+The routes registered with this method must be compliant with React Router 7 routes.
+They are loaded by a helper provided by `@plone/react-router` in an existing React Router 7 app.
+Check the official [React Router 7 documentation](https://reactrouter.com/start/framework/routing) for more information on how to define React Router 7 routes.
+```
+
+Register a route as shown in the following example.
+
+```ts
+config.registerRoute({
+  type: 'route',
+  path: '/login',
+  file: '@plone/cmsui/components/login.tsx',
+  options: {
+    id: 'login',
+    index: true,
+  },
+});
+```
+
+You must set the module's full path name of the registered route component to make `@plone/registry` correctly address it.
diff --git a/packages/registry/docs/index.md b/packages/registry/docs/index.md
index ad433cc9b6..d70b5ce51c 100644
--- a/packages/registry/docs/index.md
+++ b/packages/registry/docs/index.md
@@ -4,7 +4,7 @@ myst:
     "description": "@plone/registry provides support for building an add-on and configuration registry with infrastructure for JavaScript and TypeScript-based apps."
     "property=og:description": "@plone/registry provides support for building an add-on and configuration registry with infrastructure for JavaScript and TypeScript-based apps."
     "property=og:title": "@plone/registry"
-    "keywords": "@plone/registry, registry, add-on, configuration, component, utility, JavaScript, TypeScript, app"
+    "keywords": "@plone/registry, registry, add-on, configuration, component, routes, React Router, utility, JavaScript, TypeScript, app"
 ---
 
 # `@plone/registry`
@@ -29,6 +29,7 @@ how-to-guides/access-registry
 how-to-guides/register-and-retrieve-components
 how-to-guides/register-and-retrieve-utilities
 how-to-guides/shadow-a-component
+how-to-guides/register-routes
 ```
 
 
diff --git a/packages/registry/news/6604.documentation b/packages/registry/news/6604.documentation
new file mode 100644
index 0000000000..bd10235aba
--- /dev/null
+++ b/packages/registry/news/6604.documentation
@@ -0,0 +1 @@
+Document the route API. @sneridagh