Documentation on pathless layout routes VS. pathless route group directories

[nednella]

Hello

I'd like to know if I'm reading the docs correctly regarding pathless layout routes and pathless route group directories.

This is something that has been asked about multiple times with zero clarification. See similar discussions: #4975, #4319, #3837.

Example

Below is a screenshot of a mock routing structure.

The application is grouped as:

• (app) - the application itself.
• (auth) - the public pages, including the landing page and auth pages, that can only be accessed prior to authenticating. Else, the user is redirected to /home.
• (onboarding) - some mock onboarding process that a newly registered user must complete before accessing the application.

Note that in this example, the routeToken has been updated as follows: routeToken: "_layout",.

Required behaviour

Each group will have it's own layout file which provides 1) a beforeLoad function to check authentication and/or onboarding state, and 2) a layout for said group.

Obtaining the required behaviour

According to the docs regardling pathless layouts and pathless route groups, to get this expected behaviour, I would need to use a pathless layout structure, e.g.,

_app/
    posts/
    profile/
    home.tsx
    
_auth/
    index.tsx
    login.tsx
    register.tsx
    sso-callback.tsx
    
_onboarding/
    onboarding.tsx
    
...
_app.tsx
_auth.tsx
_onboarding.tsx
__root.tsx

Where each set of pages has it's own pathless layout file at the routes/ root, which provides both the beforeLoad check and the layout structure.

My confusion

However, the example above using pathless route groups with a nested _layout.tsx file within does also provide the expected behaviour.

The docs clearly state the following regarding pathless route group directories: They are purely organizational and do not affect the route tree or component tree in any way..

If they (to my knowledge) both work the same, 1) why do the docs not reflect this? 2) what's the point in supporting both methods?

Any light shed on this would be great. I'm pleased that I can get the expected behaviour using route groups as I do quite like the NextJS file routing, but I'm very confused as to why the docs urge you towards using pathless layout routes.

Edit: there's prior discussion where @schiller-manuel also indicates that route groups are again, purely organisational, and do not influence anything .

Edit: included a devtools screenshot for additional context.

TIA