Add more community route conventions and make them more prominent (#9381

)

docs/discussion/routes.md

@@ -101,11 +101,9 @@ app/
 
 ## Manual Route Configuration
 
-While the `app/routes` folder offers a convenient convention for developers, Remix appreciates that one size doesn't fit all. There are times when the provided convention might not align with specific project requirements or a developer's preferences. In such cases, Remix allows for manual route configuration via [`vite.config.ts`][vite-routes]. This flexibility ensures developers can structure their application in a way that makes sense for their project.
+While the `app/routes` folder offers a convenient convention for developers, Remix appreciates that [one size doesn't fit all][routes-disclaimer]. There are times when the provided convention might not align with specific project requirements or a developer's preferences. In such cases, Remix allows for manual route configuration via [`vite.config.ts`][vite-routes]. This flexibility ensures developers can structure their application in a way that makes sense for their project.
 
-<docs-warning>
-If you have not yet migrated to [Vite][remix-vite] and are still using the [Classic Remix Compiler][classic-remix-compiler], you can configure routes manually in your [`remix.config.js`][remix-config] file.
-</docs-warning>
+<docs-warning>If you have not yet migrated to [Vite][remix-vite] and are still using the [Classic Remix Compiler][classic-remix-compiler], you can configure routes manually in your [`remix.config.js`][remix-config] file.</docs-warning>
 
 A common way to structure an app is by top-level features folders. Consider that routes related to a particular theme, like concerts, likely share several modules. Organizing them under a single folder makes sense:
 
@@ -159,3 +157,4 @@ Remix's route configuration approach blends convention with flexibility. You can
 [classic-remix-compiler]: ../guides/vite#classic-remix-compiler-vs-remix-vite
 [remix-vite]: ../guides/vite
 [vite-routes]: ../file-conventions/vite-config#routes
+[routes-disclaimer]: ../file-conventions/routes#disclaimer

docs/file-conventions/routes.md

@@ -10,6 +10,20 @@ Please note that you can use either `.js`, `.jsx`, `.ts` or `.tsx` file extensio
 
 <docs-info>Dilum Sanjaya made [an awesome visualization][an_awesome_visualization] of how routes in the file system map to the URL in your app that might help you understand these conventions.</docs-info>
 
+## Disclaimer
+
+Before we go too far into the Remix convention though, we'd like to point out that file-based routing is an **incredibly** subjective idea. Some folks love the "flat" routes idea, some folks hate it and would prefer nesting routes in folders. Some folks simply hate file-based routing and would prefer to configure routes via JSON. Some folks would prefer to configure routes via JSX like they did in their React Router SPA's.
+
+The point is, we are well aware of this and from the get-go, Remix has always given you a first-class way to opt-out via the [`routes`][routes_config]/[`ignoredRouteFiles`][ignoredroutefiles_config] and [configure your routes manually][manual-route-configuration]. But, there has to be _some_ default so that folks can get up and running quickly and easily - and we think that the flat routes convention document below is a pretty good default that scales well for small-to-medium sized apps.
+
+Large applications with hundred or thousands of routes will _always_ be a bit chaotic no matter what convention you use - and the idea is that via the `routes` config, you get to build _exactly_ the convention that works best for your application/team. It would be quite literally impossible for Remix to have a default convention that made everyone happy. We'd much rather give you a fairly straightforward default, and then let the community build any number of conventions you can pick and choose from.
+
+So, before we dive into the details of the Remix default convention, here's some community alternatives you can check out if you decide that our default is not your cup of tea.
+
+- [`remix-flat-routes`][flat_routes] - The Remix default is basically a simplified version of this package. The author has continued to iterate on and evolve this package so if you generally like the "flat routes" idea but want a bit more power (including a hybrid approach of files and folders), definitely check this one out.
+- [`remix-custom-routes`][custom_routes] - If you want even more customization, this package lets you define that types of files should be treated as routes. This let's you go beyond simply flat/nested and do something such as _"any file with an extension of `.route.tsx` is a route"_.
+- [`remix-json-routes`][json_routes] - If you just want to specify your routes in a config, this is your jam - just give Remix a JSON object with your routes and skip the flat/nested concept entirely. There's even a JSX option in there too.
+
 ## Root Route
 
 ```text lines=[3]
@@ -386,12 +400,6 @@ Our general recommendation for scale is to make every route a folder and put the
 - Easy to identify shared modules, so tread lightly when changing them
 - Easy to organize and refactor the modules for a specific route without creating "file organization fatigue" and cluttering up other parts of the app
 
-## More Flexibility
-
-While we like this file convention, we recognize that at a certain scale many organizations won't like it. You can always define your routes programmatically in [`vite.config.ts`][routes_config].
-
-There's also the [`remix-flat-routes`][flat_routes] third-party package with configurable options beyond the defaults in Remix.
-
 [loader]: ../route/loader
 [action]: ../route/action
 [outlet_component]: ../components/outlet
@@ -401,7 +409,11 @@ There's also the [`remix-flat-routes`][flat_routes] third-party package with con
 [nested_routing]: ../discussion/routes#what-is-nested-routing
 [nested_routes]: #nested-routes
 [routes_config]: ./vite-config#routes
+[ignoredroutefiles_config]: ./vite-config#ignoredroutefiles
 [dot_delimiters]: #dot-delimiters
 [dynamic_segments]: #dynamic-segments
-[flat_routes]: https://github.com/kiliman/remix-flat-routes
 [an_awesome_visualization]: https://interactive-remix-routing-v2.netlify.app/
+[flat_routes]: https://github.com/kiliman/remix-flat-routes
+[custom_routes]: https://github.com/jacobparis-insiders/remix-custom-routes
+[json_routes]: https://github.com/brophdawg11/remix-json-routes
+[manual-route-configuration]: ../discussion/routes#manual-route-configuration