Tools: 📎 Update Getting Started docs to clarify local installation usage

[yassere]

We recommend that Rome be installed locally with npm install rome or yarn add rome.

We should clarify that people will need to run rome commands prefixed with npx or yarn if they don't have node_modules/.bin in their PATH. (e.g. npx rome init or yarn rome init)

[SanketDG]

Can I take this up?

[bitpshr]

Definitely @SanketDG! Please feel free to submit an associated pull request and we'll be sure to get it reviewed quickly.

[sebmck]

I don't if this is necessarily a good first task. If we're going to recommend the usage of npx rome init then we also need to install it locally to package.json which would be a non-trivial amount of work to support.

[SanketDG]

then we also need to install it locally to package.json

I assume you want to do this, because a one off invocation is not ideal for most cases?

[SanketDG]

I was struggling to find the right place to put this so I just checked out how create-react-app does it. Can we do something like this in our Getting Started?

Let me know what you guys think.

[ematipico]

I wonder if we can provide a command that creates a file that can run rome with the shebang? Kinda like we are doing at the moment internally inside our repo. This would increase the ergonomic of our CLI.

I could be part of rome init or we could have an additional command for people that already inited the project.

[yassere]

My opinion is that we should still recommend people install Rome with npm install rome or yarn add rome and then npx rome <command> or yarn rome <command> will just use the rome in node_modules without installing anything new.

While it's technically possible to have npx rome init also install Rome into a project on its own, I'm not in favor of it.

[sebmck]

Automatically installing is the behaviour of create-react-app and other generators. My fear is that it wont be obvious to many that rome has not actually been installed and that it's running in a magic cache somewhere that isn't fixed to a specific version. This also means it wont work with LSP out of the box unless we can find it locally.

The only reason we need to recommend npx is because it seems that a significant amount of people do not have node_modules/.bin in their $PATH, which is something I thought nvm and the Windows installer do for you already, but I guess there are many ways to install Node. In an ideal world, the installation instructions would just be:

npm install rome
rome init

Which is what we currently have in the docs. If we change them to use npx then it's still the same amount of commands:

npx rome init
npm install rome

We could ideally make it a single command that needed to be ran:

npx rome init

The only thing we'd need to do is when running rome init, we check if you have rome in your package.json dependencies, if you do not, then we add it for you with the same version that is used by npx rome.

This would reduce it to a single command, we wouldn't need to explain the intricacies of how npx works and when you need to run the install command. And we wouldn't do anything if you decided to locally install it and then invoke rome init yourself so it would just support both.

[SanketDG]

The only thing we'd need to do is when running rome init, we check if you have rome in your package.json dependencies, if you do not, then we add it for you with the same version that is used by npx rome.

Sounds good to me!

Do we reach a consensus here so that I can start working on this?

[ematipico]

The only reason we need to recommend npx is because it seems that a significant amount of people do not have node_modules/.bin in their $PATH, which is something I thought nvm and the Windows installer do for you already, but I guess there are many ways to install Node.

As far as I know, nvm, n and the installer add node_modules/.bin to the global $PATH but only for packages that will be installed globally (when using npm install -g). If we suggest to install rome locally to a project (or set of projects), the only way to run is using a npx or yarn.

npx, when run inside a project that has a package.json, will try to run the binary inside project/node_modules/.bin. If not there, it will download the package and run the command. (as we already know).

The only thing we'd need to do is when running rome init, we check if you have rome in your package.json dependencies, if you do not, then we add it for you with the same version that is used by npx rome.

I like this proposal! If we decided to go this way, it means we need first to implement this feature and later update the documentation

[sebmck]

I thought I had already put up a PR but I have the automatic installation implemented in a branch.

[SanketDG]

I also have seem to put up a PR, do I continue on this?

[sebmck]

Merged #1135 which when ran in a folder with package.json that doesn't have rome specified as a dependency, will add it, and if a yarn.lock or package-lock.json exists, will run it.

Neither open PRs address how we would actually want to document this new behaviour.

If you are using npm, all you need to do is run:

npx rome init

And if you're using yarn:

yarn add rome
yarn rome init

Then any future commands would use one of either:

npx rome check
yarn rome check

[ematipico]

@SanketDG will you send a PR?

I think the suggested usage by @sebmck looks clear.
Of course we should stress inside the documentation that Rome does auto installation, which is a really nice feature!

[SanketDG]

I updated #1061