@prettier/plugin-ruby

What is @prettier/plugin-ruby?

@prettier/plugin-ruby is a plugin for Prettier that adds support for formatting Ruby code. It ensures that Ruby code adheres to a consistent style, making it easier to read and maintain.

What are @prettier/plugin-ruby's main functionalities?

Code Formatting

This feature automatically formats Ruby code to follow a consistent style. For example, it ensures proper indentation and spacing.

def hello_world
  puts 'Hello, world!'
end

Consistent Style

This feature enforces a consistent coding style across Ruby files, such as consistent use of spaces, line breaks, and other stylistic elements.

class Person
  attr_accessor :name, :age

  def initialize(name, age)
    @name = name
    @age = age
  end
end

Integration with Prettier

This feature allows the plugin to be easily integrated with Prettier, enabling seamless formatting of Ruby code alongside other supported languages.

{
  "plugins": ["@prettier/plugin-ruby"]
}

Other packages similar to @prettier/plugin-ruby

standard

Standard is a Ruby style guide, linter, and formatter based on RuboCop. It enforces a standard style and can automatically fix issues, similar to @prettier/plugin-ruby, but with a focus on simplicity and minimal configuration.

README

Prettier for Ruby

@prettier/plugin-ruby is a prettier plugin for the Ruby programming language and its ecosystem. prettier is an opinionated code formatter that supports multiple languages and integrates with most editors. The idea is to eliminate discussions of style in code review and allow developers to get back to thinking about code design instead.

For example, the below code segment:

        d=[30644250780,9003106878,
    30636278846,66641217692,4501790980,
 671_24_603036,131_61973916,66_606629_920,
   30642677916,30643069058];a,s=[],$*[0]
      s.each_byte{|b|a<<("%036b"%d[b.
         chr.to_i]).scan(/\d{6}/)}
          a.transpose.each{ |a|
            a.join.each_byte{\
             |i|print i==49?\
               ($*[1]||"#")\
                 :32.chr}
                   puts
                    }

when run through @prettier/plugin-ruby will generate:

d = [
  30_644_250_780,
  9_003_106_878,
  30_636_278_846,
  66_641_217_692,
  4_501_790_980,
  671_24_603036,
  131_61973916,
  66_606629_920,
  30_642_677_916,
  30_643_069_058
]
a, s = [], $*[0]
s.each_byte { |b| a << ("%036b" % d[b.chr.to_i]).scan(/\d{6}/) }
a.transpose.each do |a|
  a.join.each_byte { |i| print i == 49 ? ($*[1] || "#") : 32.chr }
  puts
end

Getting started

The @prettier/plugin-ruby plugin for prettier is a small wrapper around the Syntax Tree gem that provides a Ruby formatter for prettier. It does this by keeping a Ruby server running in that background that prettier can communicate with when it needs to format a Ruby file. This means that in order to function, you will need to have both the requisite node and ruby dependencies installed. Because of this configuration, there are a couple of ways that you can get setup to use this plugin.

• If you're already using prettier in your project to format other files in your project and want to install this as a plugin, you can install it using npm.
• If you're not using prettier yet in your project, then we recommend using the Syntax Tree gem directly instead of using this plugin.
• Note that this plugin also ships a gem named prettier which is a wrapper around the prettier CLI and includes this plugin by default, but we no longer recommend its use. If you're using that gem, you should migrate to using Syntax Tree instead.

To run prettier with the Ruby plugin as an npm package, you're going to need ruby (version 2.7 or newer) and node (version 16 or newer).

If you're using the npm CLI, then add the plugin by:

npm install --save-dev prettier @prettier/plugin-ruby

Or if you're using yarn, then add the plugin by:

yarn add --dev prettier @prettier/plugin-ruby

You'll also need to add the necessary Ruby dependencies. You can do this by running:

gem install bundler prettier_print syntax_tree syntax_tree-haml syntax_tree-rbs

The prettier executable is now installed and ready for use:

./node_modules/.bin/prettier --plugin=@prettier/plugin-ruby --write '**/*'

Using Prettier >= 3.0

You need to tell Prettier to use the plugin, add the following to your existing prettier configuration file.

{
  "plugins": ["@prettier/plugin-ruby"]
}

Configuration

Below are the options (from src/plugin.js) that @prettier/plugin-ruby currently supports:

API Option	CLI Option	Default	Description
printWidth	--print-width	80	Same as in Prettier (see prettier docs).
requirePragma	--require-pragma	false	Same as in Prettier (see prettier docs).
rubyExecutablePath	"ruby"	Allows you to configure your Ruby executable path.
rubyPlugins	--ruby-plugins	""	The comma-separated list of plugins to require. See Syntax Tree.
rubySingleQuote	--ruby-single-quote	false	Whether or not to default to single quotes for Ruby code. See Syntax Tree.
tabWidth	--tab-width	2	Same as in Prettier (see prettier docs).
trailingComma	--trailing-comma	es5	Almost same as in Prettier (see prettier docs). Will be on for any value except none.

Any of these can be added to your existing prettier configuration file. For example:

{
  "tabWidth": 4
}

Or, they can be passed to prettier as arguments:

bundle exec rbprettier --tab-width 4 --write '**/*'

Ignoring code

Sometimes you want to leave your formatting in place and have prettier not format it, but continue to format the rest of the file. prettier has the ability to do this with prettier-ignore comments, but because the underlying formatter for this plugin is Syntax Tree, you instead would use a stree-ignore comment.

Usage with RuboCop

RuboCop and Prettier for Ruby serve different purposes, but there is overlap with some of RuboCop's functionality. Prettier provides a RuboCop configuration file to disable the rules which would clash. To enable this file, add the following configuration at the top of your project's .rubocop.yml:

inherit_from:
  - node_modules/@prettier/plugin-ruby/rubocop.yml

Usage with an editor

For supported editor integrations, you should follow the instructions for installing the integration, then install the npm version of this plugin as a development dependency of your project. For most integrations, that should be sufficient. For convenience, the instructions for integrating with VSCode are used as an example below:

• Install the Prettier - Code Formatter extension.
• Add the npm @prettier/plugin-ruby package to your project as described above.
• Configure in your settings.json (formatOnSave is optional):

{
  "[ruby]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
  }
}

Refer to this issue if you're having difficulties.

Contributing

Thanks so much for your interest in contributing! You can contribute in many ways, including:

• Contributing code to fix any bugs on GitHub.
• Reporting issues on GitHub.
• Supporting prettier/plugin-ruby on OpenCollective. Your organization's logo will show up here with a link to your website.

License

The package is available as open source under the terms of the MIT License.

Changelog

[4.0.4] - 2023-12-12

Changed

• #1413 - hrabe - Fix the cwd detection for mono-repos.