The Rome Toolchain

Yarn:

yarn add rome
yarn rome init

npm/npx:

npx rome init

After running this command, Rome will:

• Add itself to package.json as dependency if it wasn’t present, and run your package manager to install
• Generate .config/rome.rjson that serves as your project config.

If you’re putting Rome into an already established project and you’d like to automatically apply formatting and fixes, you can use:

npx rome init --apply

Refer to Project Configuration for configuration options.

Note: The .rjson extension. RJSON is a superset of JSON that supports more-concise syntax and features such as comments.

Safe Fixes

For some lint errors, the fixes are unambigious and can be applied automatically. Diagnostics that are fixable are indicated with a label that appears in the header:

src/App.js:20:12 lint/js/doubleEquals  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

To apply safe fixes and formatting, add the --apply flag:

rome check --apply

Suggested Fixes

These are for scenarios where there could be multiple ways to fix an issue, or doing so automatically would be unsafe. We include suggestions on some diagnostics for possible fixes. These require an explicit action to apply and can be done via reviewing.

 src/App.jsx:6:5 lint/js/doubleEquals  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ Use === instead of ==.

    5 │ function App({username}) {
  > 6 │   if (username == "sebmck") {
      │       ^^^^^^^^^^^^^^^^^^^^
    7 │     return null;
    8 │   }

  ℹ == is only allowed when comparing against null.

  Suggested fix: Use ===

  - username·==·"sebmck"
  + username·===·"sebmck"

  ℹ This may be unsafe if you are relying on type coercion
 Click to Expand

Anatomy

Diagnostics consist of six main parts:

• The header contains the filename, line, and column. They refer to the position that we believe is the main cause of a problem.
• Followed is the message which contains a single-line summary of what we believe is wrong.
• The code frame contains a snippet of the file referred in the header. This allows you to see what it’s referring to without having to jump into your editor and look it up.
• Advice is freeform and appears at the end of a diagnostic. It can include additional messages, lists, other code frames, and more. It gives you more details about why you’re seeing the diagnostic, and how you might fix it.

 Filename:Line:Columnpages/UserLoginPage.js:8:8 Categorylint/jsx-a11y/altText ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Message  × Provide alt text when using img, area, input type='image', and object
    elements.
Code Frame     6 │   return <span className="App">
     7 │       <header className="App-header">
   > 8 │         <img src={logo2} className="App-logo" />
       │         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     9 │         <p>
    10 │           Edit <code>src/App.js</code> and save to reload.
Advice  i Meaningful alternative text on elements helps users relying on screen
    readers to understand content's purpose within a page.

Suppressions

Diagnostics can be suppressed with a rome-ignore comment. Comments must be followed by the diagnostic categories you want to suppress and a mandatory explanation.

In JavaScript this can be a line comment:

// rome-ignore lint/js/useCamelCase: match upstream library casing

In JavaScript and CSS it can be a block comment:

/* rome-ignore lint/js/useCamelCase: match upstream library casing  */

And in Markdown and HTML:

<!-- rome-ignore html/useClosingNonVoid: allow self-closing divs -->

// rome-ignore lint/js/useCamelCase lint/js/noExplicitAny

// rome-ignore lint/js/noExplicitAny: explanation here

--cwd <dir>

Allows you to explicitly set the current working directory. Otherwise it is the shell cwd when executing the CLI.

--fieri

Adds some flavor to diagnostics.

--max-diagnostics <num>

Set the maximum amount of diagnostics that can be displayed before truncation. Defaults to 20.

--review

Open an interactive review mode for any diagnostics output from a command.

--show-all-diagnostics

Output all diagnostics, don’t limit to --max-diagnostics.

--silent

Don’t write anything to stdout. stderr will still be written to for errors. Equivalent to adding >/dev/null to a command.

--temporary-daemon

Spin up the server in a dedicated process. When the command has finished the server will exit. See Daemon for more information.

--watch

Some commands support a watch mode that will respond to file changes. See Commands for support.

--verbose-diagnostics

Output additional information about diagnostics and disable truncation.

--benchmark

Run a command multiple times and output timing information. The amount of iterations defaults to 10 and can be customized with the --benchmark-iterations flag.

This is useful as it will benchmark the command after server initialization and can reuse cache from previous runs making it a realistic information for a user with a server enabled.

--benchmark-iterations <count>

The amount of iterations to perform when using the --benchmark flag. Defaults to 10.

--logs all

Enables server logs and outputs them to the console.

--logs error

Exclude info logs and only include warnings and errors.

--log-workers

Enables worker logs, by default these are not output when running --logs.

--log-path <path>

Instead of logging to the console, write logs to a specific file.

--markers-path <path>

Collect performance markers.

--profile

Start CPU profiling all processes and at the end of the command write a CPU profile to disk. Processes include the CLI, server, and workers.

This profile can be loaded into the Chrome Devtools Performance panel.

Upon command completion the profile will be written to the path specified by the --profile-path flag.

--profile-path <path>

Change the path that --profile will write to.

Defaults to Profile-TIMESTAMP.json.

--profile-sampling <microseconds>

A sampling CPU profiler, like the one in V8, works by polling on a set interval to track what code is being ran. This means that work which happens very quickly often times will not be captured in a profile.

You can customize this to reduce or increase the timing resolution. The lower the number, the larger but more accurate the profile. However, it may slow down.

Defaults to 200.

--profile-timeout <milliseconds>

Write the profile after the specified milliseconds have passed. This is useful for commands that take a long time to run and produce very large profiles.

--no-profile-workers

Don’t include workers in the profile.

--rage

Produces a rage archive. A rage archive is a .tar.gz file that contains information that is useful for debugging performance or bugs. It contains environment and command information, a CPU profile, and logs.

Upon command completion the archive will be written to the path specified by the --rage-path flag.

WARNING: Possible sensitive information such as path names and terminal environment will be visible. It’s recommended that you only share this privately with core contributors.

--rage-path <path>

Change the path that --rage will write to.

Defaults to Rage-TIMESTAMP.tgz.

--review

See reviewing.

--timing

Output basic timing information on command completion.

--watch

For commands that support it, rerun and update on file changes.

rome cache dir

Show the location of the cache directory.

rome cache clear

Clear all artifacts from the cache directory.

rome check

Used to find problems in your project. This includes:

• Dependency verification
• Formatting
• Linting
• package.json validation

See Linting: Command Usage for more usage information.

Flags

• --apply

Apply formatting and safe fixes.

• --changed <branch/commit>

Only include files that were changed between the specified branch/commit. This can be useful for performance in large projects.

If the branch/commit is omitted then we default to the default branch, either main or master. ie. rome check --changed is equivalent to rome check --changed main.

• --format-only

Reformat all files without applying any fixes.

rome config

Used to modify project configuration. These commands work with all Rome project config locations (see supported locations for more info). When formatting a project config written with RJSON, comments will be retained.

Before your project config is saved, we will validate it for errors. It is not possible to save an invalid config with rome config.

Refer to Project Configuration: Properties for example commands.

rome config enable <key>

Set the key to true.

rome config disable <key>

Set the key to false.

rome config set <key> <value>

Set the key to a string value.

rome config set-directory <key> <value>

Set the key to the string value. If value is an absolute path then it will be made relative to the config path.

rome config push <key> <value>

Push the string value to an array at key. If key doesn’t exist then it will be created.

rome config location

Show the config location that would be modified.

rome init

This command assists in the creation of a new Rome project. The command will ask few questions about coding style and configuration extension.

Actions that are performed:

• rome.rjson is created that serves as your project configuration.
• .editorconfig is created that correctly sets indentation for editors that support EditorConfig.

The command only works on projects that don’t have Rome configuration.

$ rome init

 Welcome to Rome! Let's get you started... 

 Summary ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ 1 file saved
  ✔ No problems found!

 Files created ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  - rome.rjson: Your project configuration. Documentation:
    https://rome.tools/#project-configuration
  - .editorconfig: Sets editor formatting and indentation options.
    Documentation: https://editorconfig.org/

 What next? ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  1. Setup an editor extension
     Get live errors as you type and format when you save. Learn more:
     https://rome.tools/#editor-integration

  2. Try a command
     rome check is used to validate your code, verify formatting, and
     check for lint errors. Run rome --help for a full list of commands
     and flags.

  3. Read documentation
     Our website serves as a comprehensive source of guides and
     documentation https://rome.tools/

  4. Get involved in the community
     Ask questions, get support, or contribute by participating on
     GitHub (https://github.com/rome/tools) or our community
     Discord (https://discord.gg/rome)

Click to Expand

rome auto-config

This command is useful to “fix” some issues inside the projects. Rome will scan your project and detect the configuration of your existing project, and craft some configuration setting tailored on your project.

Flags

• --allowDirty bypasses the VCS check, allowing to perform the command on a working directory with uncommitted files

Uncommitted changes and --allowDirty

Since this command can be destructive and may have unintended consequences, we check if you have any uncommitted changes. It’s important to make sure you have everything committed in case you aren’t happy with the effects of running this command. ie. you run into a bug, you don’t like Rome, or want to try it some other time.

Operations are applied with this command:

• rome check --apply is ran which will automatically format and autofix your files.
• Global variables are extracted from previous errors and automatically added to your project config.
• Invalid licenses found inside the dependencies of the project are stored in the configuration file.

rome logs

Alias for rome noop --logs --hang. See --logs documentation for more info.

This command will never complete.

rome lsp

Running this command will start a long-running server and communicate via the Language Server Protocol over stdio. This command takes no flags.

rome noop

This command does nothing. Used in conjunction with other global flags such as --logs and --rage.

Flags

• --hang Instead of immediately exiting, hang the command and never exit unless forced.

rome rage

Alias for rome noop --rage. See --rage documentation for more info.

rome recover

Whenever Rome needs to write files to the disk, for example when updating the formatting or autofixing a file, we first save a copy of the original file to an internal cache that we call the “recovery store”. This is to allow you to revert your changes if necessary. This command is used to interact with this store.

We only keep the content of the last 5 commands that modified files. After that we will delete the oldest entry.

rome recover list

Show the contents of the recovery store. Including the command that was ran, at what time, files that were changed, and the recover commands you can use to perform operations.

$ rome recover list

 Recovery stores 

 1595570309210-lint-0 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Ran 42m21s ago (2020-07-24T05:58:29.210Z)"
  $ rome lint --apply"

  - src/App.ts
  - src/UserPage.ts

  ℹ To select specific files to patch run:
  $ rome recover apply 1595570309210-lint-0 --select"

  ℹ To see the changes with this patch run:
  $ rome recover diff 1595570309210-lint-0"

  ℹ To apply everything in this patch run:
  $ rome recover apply 1595570309210-lint-0"

Click to Expand

rome recover pop

Revert the last command. Equivalent to rome recover apply <MOST_RECENT_STORE_ID>.

rome recover apply <id>

Revert the changes that were made by the corresponding id. You can find the id by running rome recover list.

Running this command will also produce a new store entry with the files that were reverted.

rome recover diff <id>

Produce a diff of changes between existing files and those included in the id store.

rome recover dir

Print the directory where files are stored.

rome recover clear

Clear the entire contents of the recovery store.

rome restart

Equivalent to running rome stop and then rome start.

rome start

Start a daemon, if one isn’t already running.

rome status

Output the status of a running daemon. This includes uptime, file count, and other useful scaling statistics.

rome stop

Stop a daemon, if one is running.

bash

We will write the completions to ~/.rome/rome-completions.sh. We will add this file as a source to either ~/.bashrc or ~/.bash_profile, whatever we can find first.

fish

We will write the completions to ~/.config/fish/completions/rome.fish. No profile modification is necessary as they are automatically loaded.

zsh

We will write the completions to ~/.zsh-completions/_rome.

name

This is your project name. It is typically whatever you have set as name in package.json. This is never shown to you, and is used internally to refer to your project.

The Rome cache is portable, meaning it contains no references to absolute paths. This allows it to be stored across different machines. This feature may not be important to you so it can be safely omitted in most cases.

rome config set name "project-name"

extends

Inherit from another file and merge configuration. If you would only like to share partial configuration then extract it into a separate config that is used instead.

If the file refers to a package.json file then the rome property is used.

rome config set-directory extends "some-other-file"

root

By default, Rome supports nested projects and will search parent directories for other projects to initialize. Sometimes this isn’t what you want and can cause unexpected problems. This can be solved by explicitly setting the root flag which tells Rome that it should ignore any parent directories.

rome config enable root
rome config disable root

version

This is a semver range of the Rome version you want to set your project to. It is an optional layer of protection and can avoid version mismatches in large monorepos and projects.

rome config set version "^0.0.0"

lint.ignore

Path patterns that you want to ignore from linting.

rome config push lint.ignore "some-path"

lint.globals

Custom variables you want to declare as global.

rome config push lint.globals SomeGlobal

lint.requireSuppressionExplanations

Raise a diagnostic if a suppression does not have a valid explanation.

rome config enable lint.requireSuppressionExplanations

dependencies.exceptions.invalidLicenses

Sometimes Rome might complain that one or more of your dependencies has an invalid license.

Optionally, you can insert the name of this invalid license here:

rome config push dependencies.exceptions.invalidLicenses.invalid-license-name "[email protected]"

If you are unsure about the license name of your library, rome will suggest the command for you when you try to run a command.

.config/rome.rjson (recommended)

This is the recommend location. It’s the file we create when running rome init.

It can contains Rome’s flavor of JSON, RJSON, that allows comments and simpler syntax.

.config/rome.json

You can also use rome.json with regular JSON. This is useful if you think you might want to process and manipulate project configuration with another tool or language.

package.json field

Alternatively, your project config can be included in a rome field inside of package.json:

{
	"name": "my-package",
	"version": "0.0.0",
	"rome": {
		"version": "^0.0.1"
	}
}

Wildcards

* matches any number of any characters including none in a directory. This can be used in any filename position. ie.

*.js
App*Page.ts

Matching Directories

A pattern that matches a directory will also match every file inside of it. eg. pages is the same as writing pages/**/*.

Negations

Sometimes you want to add exceptions to a rule. For example, you have a folder you want to ignore but there is a file inside of that you don’t want to match. You can do this by prefixing it with !. For example:

scripts
!scripts/navigation.js

This will ignore everything in the scripts directory besides the file navigation.js.

Base Directory

Say that you have the following directory structure:

babies/juniper
cats/babies/orion
cats/babies/nev

And you only wanted to ignore the folder babies that contains juniper. If you wrote just babies then it would match both directories. However, if you prefix it with a black slash, as in /babies, then it will only match the folder at the base.

Implicit top level object

You can omit the curly braces for a top-level object and we will treat it as an object.

foo: "bar"
"bar": "foo"

Comments

Standard JavaScript comments are supported. Both line and block comments.

{
	// Line comment
	/* Block comment */
	foo: "bar"
}

Multiline strings

Regular double quoted strings can have newlines.

Unquoted keys

If a property key is a valid identifier then the quotes can be omitted, just like in regular JavaScript.

{
	unquotedKey: true
}

Optional commas

Commas are not required to separate elements of an array:

[
	1
	2
	3
]

or an object:

{
	a: 1
	b: 2
	c: 3
}

Numeric separators

You can use numeric separators in numbers, just like in regular JavaScript:

Example

5_000