[Docs]: Framework Adoption from RouterProvider improvements

[vorant94]

Describe what's incorrect/missing in the documentation

hi, there

really love rr7 and the way it allows to incrementally go from library-based SPA to SSG/SSR framework-based app

recently i migrated my playground pet project from rr as a library to rr as a framework and although docs are very helpful in doing so, there are some gaps in there that i saw related to framework adoption (as someone totally unfamiliar with remix specifically)

• non-existing page or broken link for deployment guide (here is the dedicated issue)
• no mention to update tsconfig.json, .gitignore with .react-router dir
• no mention to add react-router typegen to prepare script (without it CI, that worked before adoption, will fail)
• no mention to exclude reactRouter() from vite plugins list so vitest will work as expected (it is mentioned in remix docs)
• no mention that because of upstream vite issue there is no way to use ESM-based postcss config (neat-picking, but still would be great to have it as common issues section since the only way for me to resolve it was to bootstrap new rr7 project and see there, that postcss config in inlined as part of vite config)
• although there is a page on i18n integration in remix site and remix-i18next now supports rr7 there is no mention of it on rr7 docs themselves. that makes it harder for newcomers to understand how things should be done with rr7

i would like to contribute to docs, but since its not just some typo and i'm pretty, i would like first to agree on the scope of work and so on

[timdorr]

Hey, feel free to work up a PR for this. We're not gatekeepers here and any improvements to the docs are always appreciated. You can also start with a small PR in draft mode and add to it incrementally.

[vorant94]

@timdorr closed #12584 is exactly why i initially just opened the issue with questions to discuss the best way to address mentioned issues...

so we went over typegen stuff. my bad, didn't notice the reference

can you please suggest what is the recommended way to contribute into #12430?

and how do you see adding info on proper vitest setup? i mean remix docs has it on vite guide page, but i don't see a pair page like this in rr7 docs. it has a page with guide on mocking/stubbing rr7, but it sounds testing framework agnostic to me, not vitest specific

what to do with i18next integration? is cloning this page into rr7 docs a good approach?

is there some like FAQ place in docs, where it is fitting to add mention of ESM-based postcss config problem?

[timdorr]

Sorry about that with the PR, but we already have that covered in a dedicated doc. If the instructions change in the future, then you'd have to update it multiple places. That would lead to a good chance that something gets out of date. If you want to open a PR about highlighting the link to that page from the upgrade docs, that would be a good way to handle it.

As for vitest, we do have a minimal testing page: https://reactrouter.com/start/framework/testing A PR to expand that and include instructions for setting up tools like Vitest would be great.

The i18next page is a part of the Resources site: https://remix.run/resources?category=all I don't know if there are plans to build a page like that for RR. (Side note: I'm on the GitHub org, but I'm not a Shopify employee and don't regularly converse with the core team about their plans).

As for an FAQ, we don't have one and I think that might be a good idea, but may be a bigger concept than just one answer. We could either add a section to the site for FAQ pages around certain topics or add pages to the Explanations section.

[tannerhallman]

I have been fighting with our CI about why the types were not being generated. Thank goodness I found this issue suggesting adding a command for typegen for the CI (this works in dev automatically as the types are generated for you). The linked docs location was not an intuitive place for me to check. Getting CI to build properly is an important part of the POC/evaluation process for framework adoption. I will make a PR linking the adoption guide to the typegen steps.

I think it might also be useful to have a dedication section in the docs for releasing or production builds which would include things like setting up CI. It would be helpful to list that separately instead of listing the typegen as a how-to "feature" here.

Another thing I've noticed is that since routes are defined statically based on their route path and filename, there's going to be a fairly standard migration of the protected route paradigm and it would be useful to link to an example or discussion that has some of the options.

---

Edit: Upon rereading the guide, I did find this bit which does point to the section but perhaps deserves more detail about how they are autogenerated for you in development but for production builds its up to you.

See Type Safety to setup autogenerated type safety for params, loader data, and more.

Edit: This section points to the idea of a paradigm shift, but it would be great to have various paradigm shifts documented. is there anything like this yet?

The first few routes you migrate are the hardest because you often have to access various abstractions a bit differently than before (like in a loader instead of from a hook or context). But once the trickiest bits get dealt with, you get into an incremental groove.