Add docs for using pageExtensions to colocate other files with page components

[OzzieOrca]

Feel free to edit this/suggest changes as you see fit to match the style of your docs or how you want this feature represented.

There seemed to be many issues regarding colocating non-page files with page components in the pages directory where pageExtensions was finally suggested as a solution. I think it would be great to document it better since it seems to be a often requested workflow to colocate test, generated files, styles, and other files needed by page components in the pages directory. The note that exists in the docs currently alludes to the ability to do this but it doesn't contain much context that would help make it more discoverable.

Relevant issues:
#11113 (reply in thread)
#8454 (comment)
#8617 (comment)
#3728 (comment)

[OzzieOrca]

Could you guys take a look at this when you get a chance? It is a feature that seems to be implemented but not discoverable by new users and #3728 (comment) is still getting questions.

Feel free to change how this gets documented but seems like documenting this outside of Github issues would be helpful to people.

[zenflow]

I had another thought on this, a bit bike-sheddy (or at least open to bike-shedding) and not that important, but it could be an improvement..

I think .route would be a better than .page in this conventional solution because of API routes under pages/api/. The .route prefix seems fitting for both page routes and API routes, while the .page prefix seems fitting for page routes but not API routes. For example: pages/api/login.page.ts is not as fitting as pages/api/login.route.ts.

Thoughts anyone?

[OzzieOrca]

I don't have much history with the project and don't have a strong opinion.

I sorta feel like if you're going to name pages and API routes .route, you should just rename the whole /pages directory /routes, which I assume is a change that will never be made. I think it would be nice to maintain some consistency between the name of the folder and the name of the file extension and it would be confusing for them to be different. But with the current solution using pageExtensions, the name is up to the user, although the docs would be suggesting a convention.

Although here's an example of calling pages routes being added to the docs #27965 (comment)

Test files should not be included inside the pages directory because any files inside the pages directory are considered routes.

Also seems like there is some interest in making this default #3728 (comment) which might make the naming more important

Hey, maybe even the default should be *.page.[jt]sx? 😃

[rvirani1]

This is a great addition to the framework. I was fighting this problem the other day of having massive directories of files in parallel structures. Next team, please merge!

[styfle]

Thanks!