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.

[Pascalmh]

What I'm missing is the ability to pass the loader (https://reactrouter.com/en/main/route/loader) configuration.

When a View is missing data from the state const { state } = useLocation() and the App should redirect the user await from the current route you have to get the navigate hook const navigate = useNavigate(), check if all the necessary data is present and then redirect the user in a React.useEffect - where you have to do the check again.

export default function MyView() {
	const { state } = useLocation();
	const navigate = useNavigate();

	const hasAllDataInState = Boolean(state?.importantThing);
	
	React.useEffect(() => {
		if (!hasAllDataInState) {
			navigate('/my-other-route'); // "you should call navigate() in a React.useEffect()"
			return;
		}
	})
	
	if (!hasAllDataInState) {
		return null;
	}
	
	return (<pre>{JSON.stringify(state?.importantThing)}</pre>)
}

moving the verification that all data is present, and the redirect-handling, into the loader would clean up the code of the view a lot and remove the need to duplicate code.

[Legioth]

I'm not sure I understand the use case here. Why is there some data missing from useState() unless the user has followed a bad link? Should that kind of case instead be handled by throwing and letting the closest error boundary show a generic error?

You might also be interested in the view state management RFC that was posted last month. One of the core things there would be to generate code based on the known URL structure which means that all the logic to check that expected values are present could be handled by the framework without any application logic at all.

[Pascalmh]

You need to initiate fetches before you render

https://youtu.be/95B8mnhzoCM?t=314 (you can skip to to 8:55 -> https://youtu.be/95B8mnhzoCM?t=535)

By setting up the Requests to the backend in the loader they are being fetched before the View is rendered - this way the application can be much faster.

[Pascalmh]

Regarding the Error Boundary - I couldn't get it to catch errors that where thrown.

As the Documentation says - https://vaadin.com/docs/latest/hilla/guides/routing#adding-an-error-page - adding an error.tsx file only handels "route not found" cases:

Now, your application is equipped with an error page that’ll be shown when no other route matches a requested URL.

The generated routes will look something like this:

// File Structure:
//   views/foobar
//    @index.tsx
//    errors.tsx

const routes: readonly AgnosticRoute[] = [
    createRoute("", Layout4, [
        createRoute("", Page0),
        createRoute("foobar", [
            createRoute("", Page1), // <-- this is my @index.tsx file
            createRoute("error", Page2) // <---- this is generated when adding a errors.tsx file into the "foobar"-folder
        ])
    ])
];

[Legioth]

By setting up the Requests to the backend in the loader they are being fetched before the View is rendered - this way the application can be much faster.

The question is whether the difference is worth the effort in the typical business web application that Hilla typically targets. The story is different for consumer-facing web sites like e.g. web shops but we're at this point not optimizing for such cases.

With that said, I don't see any reason for why the loader concept from that RFC couldn't also be extended to allow defining the loader outside the view. The input to the loader could then be the same collection of signals that would be available through useViewNameState().

adding an error.tsx file only handels "route not found" cases

What I had in mind was to use something like https://www.npmjs.com/package/react-error-boundary in e.g. @layout.tsx or a custom top-level index.tsx.

[Pascalmh]

React Router v7 will drop File Based Routing - https://www.youtube.com/watch?v=fjTX8hQTlEc&t=726s (but keep backwards compatibility).

They make some arguments against using file-based routing in the video.

[Legioth]

Dropping support doesn't directly affect us since our implementation is anyways built on top of the basic React Router API that remains rather than using their file routing logic.

I see the point behind the arguments presented against file routing in that video but there's one additional requirement in our context that trumps their concerns: there's a Java server that needs to know what routes there are without running TypeScript code. This forces us to use a declarative convention (or lose all the benefits from the server knowing about client-side routes) and in that context a file-based approach seems most appropriate.