Suggested clarifications for Upgrade guide

[msakrejda]

Hello. First of all, thanks for the gem! Vite looks promising and I'm eager to try it out.

For context: we have a Rails (6.0.4) / webpacker (4.2.2) with React, TypeScript and PostCSS on the front-end. I'm trying to follow https://vite-ruby.netlify.app/guide/migration.html and suggestions from https://vite-ruby.netlify.app/guide/troubleshooting.html but I think the instructions could be clearer: the guide says "...the installation script will detect..." without actually telling you to run the installation script (fairly obvious, I admit). The next sentence is

That way you don't have to move code around, and can proceed to copying your entries in app/javascript/packs to app/javascript/entrypoints.

which is pretty vague and conceptually confusing: I don't have to move code around but I do have to copy it? Just copy it to the new directory without changes? Why is that required then?

I figured out (some of) these issues myself in trying to post a better "help it's not working" question (it's still not working, but now I think I know what I need to do), but I think some changes here could improve the migration experience.

I understand that there's a million different ways to set up Rails applications with respect to Webpacker, so no instructions will be perfect, but I think very explicit instructions for a very basic case (or ideally a slightly more complicated case), clearly referencing vite/vite_ruby and webpack/webpacker concepts, would make it a lot easier to migrate. I'm happy to suggest more concrete improvements once I complete our migration and understand vite/vite_ruby better if there's interest. As a start, just adding "bundle exec vite install" an explicit step, as well as a sentence or two about the packs/entrypoints migration, would help a lot.

Thoughts?

[ElMassimo]

Hi Maciek! @uhoh-itsmaciek

I originally wrote the Migration section as an addition to the Installation section. It's understandable that the first paragraph will be vague and confusing if read as a starting point. Especially the comment about copying entrypoints—it needed rephrasing.

I've updated the Migrate from Webpacker section to be more explicit about following the first steps of the guide before proceeding, and added more information about moving entrypoints.

Thanks for your feedback 😃

---

The "dark theme" I added recently had an unintended effect of unstyling links, which made the section seem even more vague—all of the reference links were hidden in plain sight 😅

I've updated the styles to use the standard underline decoration so they are as easy to spot as in the light theme.

[ElMassimo]

Unrelated: pganalyze seems to be an awesome tool!

[msakrejda]

Awesome, thanks for the quick response. Is the "Running your first example" section in the guide still applicable? I.e., does the default entry point automatically get hooked into our existing application view template (sorry if I'm not clear--I have limited experience with this part of Rails)?

Also, are the recommendations changes required? There was a note before that these were optional (or at least I read it that way). The big one for us would be adding suffixes to our .tsx files. We have a lot of these. I think this could be done with a JS codemod--if we end up going that route, I can probably share the codemod, but honestly I'd rather leave these. What's the motivation/requirement behind including the extension in the import paths?

Also, re the compatibility note:

Before migrating from Webpacker, make sure that you are not using any loaders that don't have a counterpart in Vite, which uses Rollup when bundling for production.

That makes sense, but it'd be great to suggest how users can go about doing this. E.g., how can I check what Vite loaders exist? And ideally, what Webpack loaders they are (more or less) equivalent to?

I think the changes you've made are already a huge improvement, though--thanks again!

And thanks for the kind words re: pganalyze!

[ElMassimo]

The installation of the example depends on the existence of a application.html.erb layout. In the future the library might detect a application.html.haml, since it's a popular templating language. The migration and tag helpers sections cover how to manually reference entrypoints in case the conventional layout is not found.

Every app is different, so the guides include useful links that reference the Vite.js documentation and recommended plugins, but in the end it's up to each user to take the time to learn about the technology and search for information as needed.

Bundlers are a complex topic. Covering them in detail (such as webpack loaders vs rollup plugins) is out of scope for the Vite Ruby docs. Please refer to the Vite.js docs, and the excellent Discord channel which is a great place to ask specific questions 😃

[msakrejda]

Thanks, that's much clearer now. Do you think it would be useful to link to Vite docs when talking about loaders? E.g., to https://vitejs.dev/guide/api-plugin.html#rollup-plugin-compatibility ?

[ElMassimo]

Sounds good!