RFC: File-based router configuration

[Legioth]

We plan to introduce a new default way of configuring the router so that any file under frontend/views/ is automatically registered as a route. Additionally, metadata about the views should be available both in Java and in TypeScript to enable automating Spring Security configuration or main menu population.

Files

Any file with an appropriate export default inside frontend/views/ is automatically registered with the router. The route for that view is based on the location of the file inside the views directory. As an example the view exported from frontend/views/foo/bar.tsx get registered with the route /foo/bar.

In addition to that very simple file name convention, we also support some special cases:

• Files with the name starting with _ are ignored.
• $index.tsx is converted to / so that e.g. frontend/views/foo/$index.tsx has the route /foo/.
• $layout.tsx defines an intermediate layout component (React component containing an <Outlet /> as the default export) that will be used for all views in the same directory and all child directories. This corresponds to an intermediate level with the layout component as element in the React Router configuration.
• {name}.tsx for views and {name}/ for directories define path parameters corresponding to :name in React Router.
• {{name}}.tsx for views and {{name}}/ for directories define optional path parameters corresponding to :name? in React Router.
• {{...name}}.tsx defines a catchall parameter which corresponds to /* in React Router. Note that the name is ignored and the parameter will be available as * in e.g. useParams() due to the way React Router works.

Declarative view configuration

There are things you might want to configure for a view that cannot be expressed only using file name conventions. To fill those needs, there is also a way of defining configuration in the view itself. This configurations need to be declared in a way that can be extracted at compile time so that the information can be made available also for server-side Java before the view is rendered. This is done by exporting a JSON5-parsable object literal as config from the same module.

export const config: ViewConfig = {
  title: "My example",
  rolesAllowed: ["ROLE_ADMIN"],
};

export default function MyView() {
  return <h1>Hello</h1>
}

The title is by default shown as <title> in the browser and in the header section of the application's <AppLayout>. If no title is defined, then the name of the exported function is used to define the title.

In addition to title and rolesAllowed, the ViewConfig type also defines properties for things like controlling whether the view implementation loaded eagerly or lazily, defining a custom route for the view, and for defining the ordering in case an automatically populated main menu is used.

Manual configuration

There might be cases where the declarative configuration is not flexible enough. For those cases, the application still has the possibility to maintains its own routes.tsx file similarly to today. The file-system based configuration approach is only a way of automating the routing configuration but the actual routing is still done is the same way as before.

The structure of routes.tsx is thus something like this:

export const routes : RouteObject[] = [
  {
    // Can filter out things from this one if needed. Includes a catch-all at the end to delegate to Flow if there are server-side routes (similar to ...serverSideRoutes today)
    ...fsRouteConfiguration,

    children: [
      // Add your own custom routes here
    
      ...fsRouteConfiguration.children
    ],
  },
];

Unified routing combined with Flow

Making metadata about Hilla views available for server-side Java does also make it possible to handle Hilla and Flow views in a unified way. In applications mixing both Flow and Hilla, it will for example be possible to automatically populate both Flow and Hilla views into a unified main menu.

[rbrki07]

I'm really looking forward to this enhancement, because it simplifies things and makes you more productive, especially when prototyping. Thank you for continuously improving Hilla ❤️

[Legioth]

An alternative approach for the directory structure has come up in discussions. The idea would be to not have a dedicated frontend/views/ directory but instead use frontend/ as the root of the hierarchy and use a something.view.tsx naming convention to mark views.

Route	Original proposal	Alternative
/foo/bar	frontend/views/foo/bar.tsx	frontend/foo/bar.view.tsx
/:foo	frontend/views/{foo}.tsx	frontend/{foo}.view.tsx
/:foo/bar	frontend/views/{foo}/bar.tsx	frontend/{foo}/bar.view.tsx
Related file without route	frontend/views/_fooUtil.ts	frontend/fooUtil.ts
Unrelated file without route	frontend/components/Button.tsx	frontend/components/Button.tsx

Benefits of the alternative would be:

• Makes it straightforward to put helper files related to a specific view in the same directory as the view itself (without having to remember that _ file name prefix). This is more in line with Flow where you can also have views and other files alongside each other without an extra syntax.
• Shallowed directory structure.
• Might be more familiar for Flow developers.

Benefits of the original would be:

• Not everything is a view or associated with a specific view. As an example, a generic Button component might be natural to have in frontend/components/Button.tsx. It's not obvious from looking at the contents of the frontend/ directory whether components/ represents a part of the route structure without also checking its content.
• There's some repetition in writing out .view.tsx for each view.
• Might be more familiar for developers who are used to other frontend frameworks (such as Next.js)

[jojule]

I think the original is easier to understand and leads to simpler project structure.

(That said, the explicitly registered routes are not going away, so people are still free to structure the project as they wish)

[rbrki07]

I also prefer the initial approach. Having dedicated directories like frontend/views, frontend/components or frontend/utils feels very common and natural to me.

[Legioth]

There seems to be a preference for the original structure so let's aim for that. There is a possibility of making this configurable but doing that is currently not among the topmost priorities. Configurability would make things more complicated for e.g. tools so we might choose to not implement that even if time and priorities wouldn't be an issue.

[samie]

One feature that server-based routing can enable is serving different pages and metadata based on the landing URL. Required to make external links to apps display correctly in 3rd party systems. It might be implicit in the design, but it is easy to miss unless there is also a test case.

[Legioth]

That can be handled using a IndexHtmlRequestListener. What changes with this RFC is that your custom logic in that listener could also have access to metadata about client-side views.