Improve initial install experience

[notpeter]

Currently the UX for a new user installing the Ruby extension is somewhat sub-par. If you do not have solargraph or ruby-lsp installed and available in your path, the extension kicks an error:

Language server error: ruby-lsp

Unable to find the 'ruby-lsp' command.
-- stderr--

Some of this may just be a need for better zed ruby docs.

For example on macos you would need to do the following:

brew install ruby
echo 'export PATH="/opt/homebrew/opt/ruby/bin:$PATH"' >> ~/.zshrc
export PATH="/opt/homebrew/opt/ruby/bin:$PATH"

# ruby-lsp
gem install ruby-lsp
echo 'export PATH="/opt/homebrew/lib/ruby/gems/3.4.0/bin:$PATH"' >> ~/.zshrc
export PATH="/opt/homebrew/lib/ruby/gems/3.4.0/bin:$PATH"

# solargraph
brew install solargraph

• Do I need a global install of ruby-lsp? (are there downsides to suggesting homebrew ruby)?
  • I hate suggesting a fixed ruby versionized gem path, but homebrew doesn't suggest adding gem bin to your path. Perhaps:

    export PATH="/opt/homebrew/opt/ruby/bin:$PATH"
    export PATH="$(gem environment path | sed 's#:#/bin:#g; s#$#/bin#'):$PATH"

  • What about for Linux users?
• Should we suggest ruby-lsp plugins like (ruby-lsp-rails, ruby-lsp-rspec)?
  • Do these require any additional config
• Does anyone have a sense of the solargraph / ruby-lsp usage split? (I know ruby-lsp is new-ish)?
  • Solargraph had zero releases in 2024, but development seems to have picked up a bit with 3 releases in 2025.

I'm going to see if I can improve the docs to make sure they work for setting up from a clean mac, but wanted to see if anyone had feedback or other suggestions on how to improve first time user experience.

cc: @vitallium, @ConradIrwin

[vitallium]

Hi,

Do I need a global install of ruby-lsp? (are there downsides to suggesting homebrew ruby)?

It depends. In most cases, the global installation of ruby-lsp is enough but if any add-on, for example, ruby-lsp-rspec, is required then it's recommended to add ruby-lsp to the project's Gemfile. Doing so requires starting the ruby-lsp via bundler: bundle exec ruby-lsp.

are there downsides to suggesting homebrew ruby

In 99% cases Rubyists rely on a version manager like rbenv, rvm, asdf or mise to install the specific Ruby project version defined there. It's important to have the correctly activated Ruby version otherwise LSPs won't work and other stuff too.

Should we suggest ruby-lsp plugins like (ruby-lsp-rails, ruby-lsp-rspec)?

ruby-lsp-rails is installed automatically by ruby-lsp if a Rails project is detected. ruby-lsp-rspec is an optional gem that must be added to the Gemfile but there is also an option to use a composed bundle - https://shopify.github.io/ruby-lsp/composed-bundle.html

Does anyone have a sense of the solargraph / ruby-lsp usage split?

No idea, I will ask on social media about that. Even the latest Ruby survey does not have such topic.

I was thinking about potential UX improvements and the only way to improve it is to allow a Zed extension to run system commands but that raises many security concerns. Overall, I am happy to help with anything that aims to improve UX of the Ruby extension.

[ConradIrwin]

Fixing the docs is a good start, but as mentioned in #zed-industries/zed/, I would like to get to the point where Zed's ruby integration can install and configures the language server out of the box.

I think you're right that this requires making extensions more powerful, and I also think that's the right trade-off. Given that today they can download arbitrary code from GitHub and run that, it doesn't seem too bad to let them run some code off the bat.

What I was imagining is a way for extensions to whitelist in the manifest the things they need to do:

allow_exec = [
  "gem install ruby-lsp",
 ]

If we were to do something like that, would it actually be enough though? :D

I think it's also important that extensions don't modify people's projects, so we wouldn't want to add things to the Gemfile by default (though we should obviously use the ruby-lsp from the Gemfile if it exists). I also know that there's a significant amount of variation in how gems get installed globally. I was wondering if we could emulate what we do with typescript and set up a fake project in a temporary directory, and run the lsp from there (if they don't already have it in the Gemfile of course); the challenge I guess would be making sure we're using the correct ruby in that directory

[vitallium]

I was wondering if we could emulate what we do with typescript and set up a fake project in a temporary directory, and run the lsp from there (if they don't already have it in the Gemfile of course); the challenge I guess would be making sure we're using the correct ruby in that directory

I am not sure about this idea since I am not familiar with Zed codebase but I was actually thinking about providing ruby_runtime in the same as Zed does for Node.js. The idea of this runtime is not to install Ruby but grant access to the system or project Ruby through extension API:

• ruby-binary-path: Returns the path to the currently active Ruby binary.
• gems-latest-version: Returns the latest version of the given Ruby gem.
• gems-installed-version: Returns the installed version of the given Ruby gem, if it exists.
• gems-install-gem: Installs the specified Ruby gem.

And so on. That should give flexibility to the Ruby extension and other extensions that rely on Ruby ecosystem. For example, the Ruby DX will be like this:

• Use the bundle-installed-version function from the ruby-runtime to check if the current project (if any) has any enabled LSP. If yes, start it in the context of the project's gemset.
• Otherwise, use gems-* functions from the ruby-runtime to install the LSP.

I spent some time today to craft PoC: zed-industries/zed#25350
It does some basic things like installs the Ruby LSP if it's not available but I removed all project-aware settings for now since they work as-is currently. I also didn't implement installing a portable Ruby in case we don't have Ruby at all, but that option is also available.

To test it you need to:

1. Check out the vs/ruby-runtime branch and build Zed.
2. Check out the vs/ruby-runtime branch of the Ruby extension.
3. Rebuild the Ruby extension to make the Ruby runtime functions available.

I also pushed a version of Ruby extension that uses this runtime to illustrate how it looks in action. Let me know what do you think. Thanks!

[ConradIrwin]

Wow, incredible! Thank you :D.

I'll take some time to review this and try to get back to you early next week, but I like this idea a lot.