[RFC] Route navigation inferencing

[Janpot]

Which problem do we want to solve?

• File system based routing allows for setting up application routes without explicitly configuring the site structure in code. However, to show a navigation UI, one needs to still define a site structure in code. This structure needs to be kept in sync with the file system routes. Adding/deleting path segments, or moving folders around always requires a code update as well. Navigation item names are very close, or easily deductible from route segment names.

How will we solve it?

• Inspect the file system routing structure and automatically generate code for a site structure that can be fed to a component to render it.

Routing

From the file system we can deduce the following information:

• route hierarchy
• route name: clever string manipulation can generate a readable title
• In the case of Next.js app router we can deduce subheaders from route groups

What we can’t deduce

1. titles beyond what can be reasonably deduced. e.g. punctuation, capitalization, or a full alias
2. icons for navigation UI
3. custom order of paths
4. routes for dynamic segments
5. hide or “turn off” specific routes

To augment the default navigation structure add a meta.tsx to the route folder which exports this information:

import { RouteMeta } from '@toolpad/core'
import PeopleIcon from '@mui/icons-material/People'

export default {
  hidden: true,
	Icon: PeopleIcon
	title: 'Employees',
	children: [
	  // Routes that discovered but missing in this list are appended
	  // at the end alphabetically
	  // Routes that are in this list but not discovered generate a warning
		'route1',
		'route2',
		'route3'
	]
} satisfies RouteMeta

1. titles beyond what can be reasonably deduced. e.g. punctuation, capitalization, or a full alias
   ⇒ title for a route can be overriden with the title prop
2. icons for navigation UI
   ⇒ Icon component can be provided
3. custom order of paths
   ⇒ children reorders the child routes of this segment
4. routes for dynamic segments
   ⇒ Not solved by this RFC. We will create a separate RFC if sufficient interest
5. hide or “turn off” specific routes
   ⇒ Use the hidden prop. To hide a group of routes, add a Route group in next.js and set hidden for this route group.

Navigation Generation

We will provide

• a CLI which takes an optional project folder and output location and generates a navigation.ts file, which can then be either directly referenced by the user, or aliased in tsconfig paths. The CLI will also have a watch mode so it can be run in parallel with the project dev mode.
• a Next.js or Vite plugin that can be added to the config files of the project and that will automatically make available the generated content of the navigation structure under @toolpad/core/navigation. It combines a loader with an alias to make this happen. I’ll also provide types for this module.

Generated content

import { mergeMeta } from '@toolpad/core/navigator';

// generate imports for all the meta.tsx files that have been found
import meta1 from '@/app/myPage/meta';
import meta2 from '@/app/myOtherPage/meta';
import meta3 from '@/app/myPage/deeply/nested/meta';
// ...

// Build structure of discovered meta files, merged with meta files where found
export default {
  name: '',
  title: '',
  children: [
    // if a meta is found, it's merged with the discoverd structure
    mergeMeta(meta1, {
      name: 'myPage',
      title: 'My Page',
      children: [
        {
          name: 'deeply',
          title: 'Deeply',
          children: [
            mergeMeta(meta3, {
              name: 'nested',
              title: 'Nested',
              children: [],
            }),
          ],
        },
      ],
    }),
    mergeMeta(meta2, {
      name: 'myOtherPage',
      title: 'My Other Page',
      children: [],
    }),
    // Segments for which no meta file is found are not wrapped
    {
      name: 'another',
      title: 'Another',
      children: [],
    },
  ],
};

The children property

To keep routes self-contained, the “children” property is only designated for ordering the routes. Options about children need to go in their own meta.ts . This ensures that route folders are maximally portable. One needs to be able to drag a route folder around with its configuration contained in it.

Subheaders

To achieve subheaders in a navigation section, we will leverage Route groups in Next.js

app / myRoute1 / section1 / myRoute2 / myRoute3 / section2 / myRoute4;

Generates the following navigation section:

[
  { name: `myRoute1`, title: 'My Route 1' },
  { kind: 'header', title: 'Section 1' },
  { name: `myRoute1`, title: 'My Route 2' },
  { name: `myRoute1`, title: 'My Route 3' },
  { kind: 'header', title: 'Section 2' },
  { name: `myRoute1`, title: 'My Route 4' },
];

Use a app/myRoute/(section1)/meta.ts to change the title of the subheader.

We will also allow to add { kind: 'header', title: 'Section 2' } entries in the children array of a meta.ts so that environments that don’t support route groups can also have subheaders.