[Content]: Better outline and information on FileRoutes

[davedbase]

📚 Subject area/topic

SolidStart, FileRoutes

📋 Page(s) affected (or suggested, for new content)

https://docs.solidjs.com/solid-start/building-your-application/routing#file-based-routing

📋 Description of content that is out-of-date or incorrect

Users have expressed concerns regarding how file-based routing is documented. There isn't enough detail that's leading them to making mistakes:

Hey people can you help me with the nested routing while using FileRoutes
I have everything configured but nested route is showing page  not found

From our Discord where similar reports have been made a couple of times. What might be valuable is outlining nested routes in a clearer and more concise manner with more examples.

🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)

No response

[zjcurtis]

Hey I'm definitely one of the folks feeling confused. I'll try to list things I find confusing and/or specific sections of the documentation that confuse me. This will lean towards critical, because right now I don't understand the implementation enough to suggest what it should say.

1. CTRL + F for server or client show nothing on the SolidStart Routing page. It isn't clear to me how any of this works differently depending on where it is run, I keep getting hydration errors as I develop, and the whole process seems magical. Perhaps this seems obvious, but I'd rather you over-explain the simple bits in an accordion than assume I know what I'm doing.
2. "SolidStart traverses your routes directory, collects all of the routes, and then makes them accessible using the ." - To what depth? If I want /writing/test, is putting test.tsx inside the writing folder preferred, or is a writing folder, then a test folder, with index.tsx inside test preferred? Right now I naively can't get anything beyond the index page one level down (so a "url.com/writing") to work.
3. The nested routes section lacks enough details for me to understand, and doesn't seem to correlate with my experience. Again, I'm too confused to know why or how, just that it doesn't particularly seem correct... perhaps unwritten assumptions are being made?
4. It's unclear to me whether the default export (for a page) has any requirements as to its name. Is it only the file that needs to be named to align to the route?
5. Going back to the topic of server vs client - Please be brutally eli5 with the "if you have a client on site.com and you want them to CSR to site.com/about-- This is how you do that" because right now I feel like my approach to using solidstart is basically to try something, get an error, and then change random things.

EDIT: Here is an example of the sort of confusion I have.

My secondary links were not working (using the solidstart examples) so 'site.com/writing/post1' would 404, even though 'site.com/writing' was fine. Some posts seemed to suggest <Router url={isServer ? req.url : ""} Which confuses typescript because what the heck is req. Changing it to <Router url={isServer ? getRequestEvent()?.request.url : ""} makes all my secondary links work when used inside the client, but I'm not sure why, or what tradeoffs I'm making, only that it seems very kludgy.

[klequis]

@zjcurtis

There is a issue with the development server (no problem in production) that causes hydration errors as well as page not found when a new route is added. If you get one of these pages try ctrl-shift-r in the browser. This resets the cache. If after doing so the route works then that is likely the problem.

SolidStart traverses your routes directory, collects all of the routes, and then makes them accessible using the .

There appears to be no limit. Just to be sure of this I tried http://localhost:3000/one/two/three/four/five/six/seven/eight/nine/ten with index.jsx in /ten. More levels than I think one would need. It works but I had to use ctrl-shift-r.

If I want /writing/test, is putting test.tsx inside the writing folder preferred, or is a writing folder, then a test folder, with index.tsx inside test preferred?

I would be surprised if the Solid team had a preference. Folders allow you to add additional segments to a route. For example:

If you need a contacts page and no other routes will start with /contacts.

Either

|-- routes
     |-- contacts.tsx

OR

|-- routes
     |-- contacts
          |-- index.tsx

Are both fine and work the same.

If you need a page at /products, perhaps it is a list of all products, and also need /products/mice and /products/keyboards

|-- routes
     |-- products
          |-- index.tsx            // the route will be /products
          |-- mice.tsx             // the route will be /products/mice             (a nested route)
          |-- keyboards.tsx     // the route will be /products/keyboards (a nested route)

Nested routes

My understanding is that any route that is not the first segment in the path is a "nested route". So /products/mice and /products/keyboards are both nested routes. /products is not nested as it is directly off the root route /.

It's unclear to me whether the default export (for a page) has any requirements as to its name. Is it only the file that needs to be named to align to the route?

Yes.

---

I'm writing a tutorial on file-based routing which is nearly done. The tutorial is aimed at folks who are new to Solid and routing in general. I can put a draft up and share with you if you would like? Your feedback would be very helpful to me.