Vite Ruby
Return to top
On this page

Debugging 🔎

This section contains some useful tips for debugging Vite.js and Vite Ruby.

Before we start

Debugging can be time-consuming, please check the Troubleshooting section first.

If you are using the vite JS executable directly, please refer to this blog post instead.

Getting more output from Vite 📜

The quickest way to get started is to enable more output from Vite's core plugins.

You can achieve that by passing the --debug flag to the commands.

Tweaking debug output

To see output from other plugins, you can set the DEBUG environment variable.

You can use globs to filter specific commands:

  • DEBUG=*: Enable all debug output
  • DEBUG=vite:*: Enable output from core plugins
  • DEBUG=vite-plugin-ruby:*: Enable output from vite-plugin-ruby

Debugging with DevTools 🎯

Commands in Vite Ruby can also receive the --inspect flag to start a debugging session.

You may use the Node Inspector Manager browser extension to attach automatically to the session.

Set breakpoints in Dev Tools, or use the debugger keyword in the code to break execution.

Opening Packages and Gems 📖

Run bundle open or npm edit to open the version of the libraries used in your project.

Set $EDITOR

This environment variable will be used to infer the text editor to open the library with.

I like using Sublime Text or Visual Studio Code, to see the entire file tree.

Examples: bundle open vite_ruby, npm edit vite.

Editing In-Place ✍️

Because both Ruby and JavaScript are dynamic languages, you can tweak the code in-place, and then restart the dev servers, and your changes will be picked up.

You can add puts or console.log as needed, or even change the behavior!

In TypeScript packages (and some JS packages), make sure to edit the transpiled file instead of the sources. This is often dist/index.js but that depends on the library and target environment.

Disclaimer

This has many caveats: bugs that only happen in your local, or the opposite, code that only seems to work in your local. Keep reading for a better approach. You have been warned!

(I use it all the time though, so convenient 😅)

Using a Local Library 🔗

When fixing a bug, a nice flow is to clone the library, and then point to your local copy.

  • In Ruby, you can use local paths for Git dependencies, or use path:

    gem 'vite_ruby', path: '../vite_ruby' # Assuming the same parent directory

  • In JavaScript, you can use yarn link or npm link:

    For example, for vite, inside your clone:

    cd packages/vite # Location of the package.json for the library
yarn link

    In the project you are debugging:

    yarn link vite # Name of the library

    If using pnpm, then you can safely use file which will link to your local copy:

    "devDependencies": {
  "vite": "file:../vite/packages/vite",

  • In TypeScript or compiled JS libraries, make sure to start a compiler with a watcher.

    By convention, the dev script is used for this purpose: npm run dev.

    This will detect changes in the library, and recompile as needed.

Just as in the previous section, it's important to restart the dev servers after changes.

Why is it necessary to restart? 🤔

Most processes will load the required libraries into memory, and then use these cached versions during their entire running time.

Restarting your Ruby and Vite processes ensures the modified versions are loaded.

Debugging Gems

Sometimes puts debugging in Ruby is not enough, and you need to use an actual debugger.

You can use byebug (or pry-byebug) to break execution and start an interactive session.

Use tap to inject breakpoints without affecting the outcome:

.tap { |val| binding.pry }