Migrating to Vite Ruby v3 #

This section is intended to guide early adopters to upgrade from Vite Rails v2 to v3.

New Features ✨ #

Safer Upgrades #

bin/vite upgrade is a new CLI command to easily upgrade any Vite Ruby gems you are using, as well as the vite-plugin-ruby npm package, to compatible versions.

Additional Entrypoints #

additionalEntrypoints is a new configuration option to specify entrypoints.

By default it adds sourceCodeDir/{assets,fonts,icons,images}/**/*, so you can now reference these files using tag helpers instead of having to place them inside entrypointsDir.

vite_asset_path 'images/logo.svg' # app/frontend/images/logo.svg

Breaking Changes 🧨 #

Nested entrypoints paths must be explicit #

Any paths without a parent dir will be resolved to the entrypointsDir:

vite_javascript_tag 'application' # entrypoints/application.js

But for entrypoints in a nested directory in entrypointsDir, the path must now be explicit:

app/frontend: sourceCodeDir
  └── entrypoints: entrypointsDir
      ├── nested:
      │   └── application.js
      └── images
          └── logo.svg

❌ vite_javascript_tag 'nested/application'
✅ vite_javascript_tag 'entrypoints/nested/application'

❌ vite_asset_path 'images/logo.svg'
✅ vite_asset_path 'entrypoints/images/logo.svg'

For assets located inside entrypointsDir there is now a better solution as described in the previous section, which is to place assets in one of the default additionalEntrypoints dirs:

- app/frontend/entrypoints/images/logo.svg
+ app/frontend/images/logo.svg

app/frontend: sourceCodeDir
  ├── entrypoints: entrypointsDir
  │   └── nested:
  │       └── application.js
  └── images
      └── logo.svg

✅ vite_javascript_tag 'entrypoints/nested/application'
✅ vite_asset_path 'images/logo.svg'