tophat / yvm

🧶 Manage multiple versions of Yarn (deprecated)

Yarn Version Manager (yvm) - (deprecated)

⚠️ Deprecation Notice (2022-02-20) ⚠️

yvm has been deprecated in favour of corepack which is distributed by default with NodeJS v14, and is available in older versions by installing the corepack npm package globally.

With corepack, you specify your package manager and version via the packageManager field in your project's package.json file (see example).

What does it mean to be deprecated? yvm will no longer receive updates (except for critical security vulnerabilities) and the repository will eventually be archived.

---

Overview

Pesky yarn versions got you down? Automatically and easily manage those versions.

YVM will automatically use the correct yarn version when you run any yarn commands in any folder with a package.json, .yvmrc or any other supported configuration file. Otherwise, it will use you a globally set version of yarn.

Motivation

Manually managing different yarn versions across projects is a pain. This fixes that.

Installation

Node: >=10.0.0

Homebrew

Installs the latest stable version.

brew install tophat/bar/yvm --without-node

NOTE: Remove the flag --without-node to install with the node dependency.

Windows

TODO: #435

Node

Execute the following in your terminal:

curl -s https://raw.githubusercontent.com/tophat/yvm/master/scripts/install.js | node

Or to install a specific version:

curl -s https://raw.githubusercontent.com/tophat/yvm/v3.2.1/scripts/install.js | INSTALL_VERSION="v3.2.1" node

Script

Some older versions of yvm do not have the node installer enabled. If so the shell script installer can be used.

curl -s https://raw.githubusercontent.com/tophat/yvm/v2.4.3/scripts/install.sh | INSTALL_VERSION="v2.4.3" bash

Manual

Navigate to yvm releases and download the yvm.js file for the latest release into your desired yvm install directory.

Typically .yvm your home directory, then run the following command to configure your shell.

node ./home/joe_user/.yvm/yvm.js configure-shell

You will need to reload the shell to get yvm, or source the generated yvm.{sh,fish} scripts.

Upgrade

To upgrade yvm to the lastest version either install as normal, or run

yvm update-self

Usage

Automagic

Run any yarn command and watch it automagically use the correct version of yarn.

Yarn is shimmed to use the default version or the version defined your current directory config file.

yarn --version

Basic

To download and install a specific version of yarn, run:

yvm install <version>

To get the latest version of Yarn, run:

yvm install latest

Execute an arbitrary command using a specific version of yarn:

yvm exec <version> <command>

Additional commands

Switch the current yarn versions:

yvm use <version>
yarn --version

NOTE: The above disables yarn shimming until a new shell is loaded.

Control version aliasing:

yvm alias stable
# stable → 1.13.0 (1.13.0)

yvm alias default stable
# default → stable (1.13.0)

yvm alias
# default → stable (1.13.0)
# latest → 1.14.0 (1.14.0)
# stable → 1.13.0 (1.13.0)
# system → 1.13.0 (1.13.0)

yvm alias default '^1.7'
# default → ^1.7 (1.14.0)

Show path to version used:

yvm which

List installed yarn versions:

yvm list

Full list of available commands:

yvm --help

Configuration file

Yvm defaults to using the yarn version in your package.json engines. Otherwise you can create a .yvmrc file containing the version number of yarn in your project's root directory. Afterwards, yvm use, yvm install and yvm exec will use the version specified in the config file if no version number is supplied to the command. You can also declare the version using other configuration files

Custom Bootstrapping

When using yvm exec, the appropriate yarn version is executed using the node available in the current context. This can be explicitly specified using the YVM_BOOTSTRAP_EXEC_PATH environment variable.

Example: if you are using nvm, you can avoid having to execute nvm use before using yvm exec:

export YVM_BOOTSTRAP_EXEC_PATH=~/.nvm/nvm-exec
yvm exec my-command

You can set this environment variable globally in your preferred shell's setup script (e.g. bashrc/zshrc).

The script referenced via the exec path must be executable. It receives the yarn executable as its first argument, and should forward the remaining arguments to yarn.

Additional reference

A full list of commands is on the api reference page

Have questions? List of common questions and answers

Removing

To remove yvm simply execute

rm -rf $YVM_DIR

Next, edit $HOME/.bashrc and $HOME/.zshrc and remove those lines:

export YVM_DIR=/home/joe_user/.yvm
[ -r $YVM_DIR/yvm.sh ] && . $YVM_DIR/yvm.sh

Remove in $HOME/.config/fish/config.fish for fishers:

set -x YVM_DIR /home/joe_user/.yvm
[ -r $YVM_DIR/yvm.fish ]; and source $YVM_DIR/yvm.fish

In case you had older version of yvm installed, there could also be a line like

source /home/joe_user/.yvm/yvm.sh

or those lines could be in $HOME/.bash_profile instead of $HOME/.bashrc.

Contributing

We welcome contributions from the community, Top Hatters and non-Top Hatters alike. Here are some guidelines to help you get started!

Basic development flow

1. Ensure the problem you are solving is an issue or you've created one
2. Clone the repo
3. We use make. make help will show you a list of development commands
4. make install-watch will install yvm on your shell and update when you make changes. Make sure to only run this in the root yvm directory, it will fail elsewhere.
5. make test and make lint are also commonly helpful

Make sure all changes are well documented. Our documentation can be found inside the docs section of this repo. Be sure to read it carefully and make modifications wherever necessary. You can also access the documentation on our website

Please make sure to look over our Code of Conduct as well!

Manual testing command contributions

make install
yvm <your-command-here>

Technologies to Familiarize Yourself with

• NodeJS
• Yarn

Contributors

Thanks goes to these wonderful people (emoji key):

Francois Campbell 💻	Jake Bolam 📖 💻 🚇	Brandon Baksh 💻	Milan Milojic 💻	Umar Ahmed 💻	Nicholas Dujay 💻	Aser Eldamaty 💻
Michael Rose 💻	Sanchit Gera 📖	sdcosta 📖	Siavash Mahmoudian 🚇	greenkeeper[bot] 🚇	Jay Crumb 📖	Michael Lunøe 📖
Yash Shah 💻	Wacław Schiller 💻	yvm-bot 🚇	Emmanuel Ogbizi 💻 ⚠️ 📖	Martin Lai 💻	Marc Cataford 💻	Ahmed Elkady 👀
Noah 💻 🚇	Derek Delaney 📖	dependabot[bot] 🚇	allcontributors[bot] 📖	Umar Ahmed 🐛	Abi Noda 📖 📆	Josh Dean 📖
akeshk 🚇 🔧 💻

This project follows the all-contributors specification. Contributions of any kind welcome!

Credits

Thanks to Carol Skelly for donating the github organization!

yvm's Issues

yvm does not set a default global yarn version

Describe the bug
If you don't have a global version of yarn installed, yvm does not provide one, so yarn in any shell does not work until doing yvm use, and even then, it only persists for the current shell.

To Reproduce
Steps to reproduce the behavior:

• Do not have a global version of yarn installed
• Run yvm install <any version>
• yarn -v works
• Open a new shell
• yarn -v is an unrecognized command
• yvm use <the installed version>
• yarn -v works

Expected behavior

• Do not have a global version of yarn installed
• Run yvm install <any version>, this installs this version of yarn as default
• yarn -v works
• Open a new shell
• yarn -v uses the same version as above automatically

Screenshots
If applicable, add screenshots to help explain your problem.

Desktop (please complete the following information):

• OS: macOS 10.13.6
• YVM Release: any

Installing an invalid version fails

```milan:yvm` milanmilojic$ npm start install 1.0.2

@thm/[email protected] start /Users/milanmilojic/dev/yvm
node yvm.js "install" "1.0.2"

Installing yarn v1.0.2
Finished downloading yarn version 1.0.2
Finished extracting yarn version 1.0.2
milan:yvm milanmilojic$ npm start install 1.0.3

@thm/[email protected] start /Users/milanmilojic/dev/yvm
node yvm.js "install" "1.0.3"

Installing yarn v1.0.3
Finished downloading yarn version 1.0.3
{ Error: incorrect header check
at Zlib._handle.onerror (zlib.js:371:17) errno: -3, code: 'Z_DATA_ERROR' }
milan:yvm milanmilojic$```
leaves us with with invalid tarball

total 256
drwxr-xr-x  5 501  20     160 Jun 18 17:04 .
drwxr-xr-x  3 501  20      96 Jun 18 16:15 ..
drwxr-xr-x  7 501  20     224 Jun 18 17:04 v1.0.2
-rw-r--r--  1 501  20  129195 Jun 18 17:04 v1.0.3.tar.gz
drwxr-xr-x  7 501  20     224 Jun 18 17:01 v1.7.0```

yvm logo

Is your feature request related to a problem? Please describe.
Lets get a logo

`yvm install` crashes when trying to install a non-existent version of `yarn`

milan:yvm milanmilojic$ npm start install 1.0.2

> @thm/[email protected] start /Users/milanmilojic/dev/yvm
> node yvm.js "install" "1.0.2"

Installing yarn v1.0.2
Finished downloading yarn version 1.0.2
Finished extracting yarn version 1.0.2
milan:yvm milanmilojic$ npm start install 1.0.3

> @thm/[email protected] start /Users/milanmilojic/dev/yvm
> node yvm.js "install" "1.0.3"

Installing yarn v1.0.3
Finished downloading yarn version 1.0.3
{ Error: incorrect header check
    at Zlib._handle.onerror (zlib.js:371:17) errno: -3, code: 'Z_DATA_ERROR' }
milan:yvm milanmilojic$

Add `yvm use` to help

yvm use and yvm exec - behaviour for getting config differ

Describe the bug
yvm use, looks in the current directory for a .yvmrc file. yvm exec does a more indepth tree and file search

Expected behavior
They should behave the same

Show help string when yvm called without params

http://tj.github.io/commander.js/#Command.prototype.help

Verify integrity of tarball

Is your feature request related to a problem? Please describe.
In order to reach parity with the Yarn install script (linked below), we should verify the integrity of the downloaded tarball.

Describe the solution you'd like
If the user has GPG installed, run the integrity check by downloading the public key, spawning a child process, and running GPG. If there is an error in the integrity check or GPG is not installed, notify the user, and prompt the user on whether or not to continue without verifying. Clean up the downloaded files regardless.

Describe alternatives you've considered
YOLO it and download tarballs from who knows where without verifying integrity (I am being sarcastic 😐).

Additional context
https://github.com/yarnpkg/website/blob/master/install.sh#L50

Run a yarn subcommand with a specific version

• yvm exec "blah"

Cannot pass additional command line arguments

yvm.sh exec install --frozen-lockfile
error: unknown option `--frozen-lockfile'

yvm invalid-command, should show invalid command and help

Install multiple versions of yarn

• Can yarn run independently?
• downloading yarn version

Remove yarn versions

• removing an installed version

rc file

• Version for packages

Support a default version of yarn/commands

➜  yvm git:(yvm-which) yvm list
Checking for installed yarn versions...
Installed yarn versions:
  - v1.7.0

➜  yvm git:(yvm-which) yvm which
Checking yarn version
You don't have yvm version installed

If I've installed a version, it should default to that.

Seeing You don't have yvm version installed
I have YVM installed, but I don't have a yvmrc. Should we have the concept of a default version to use?

Prevent user from removing the currently active version of Yarn

NVM does this:

$ nvm uninstall 10.5.0
nvm: Cannot uninstall currently-active node version, v10.5.0 (inferred from 10.5.0).

PATH is not updated for globally installed packages

Describe the bug
On a machine that never had Yarn installed, the install script for YVM does not set up the PATH correctly for global installed packages. The Yarn website says:

Path Setup

Unix/Linux/macOS

If you chose manual installation, the following steps will add Yarn to path variable and run it from anywhere.

Note: your profile may be in your .profile, .bash_profile, .bashrc, .zshrc, etc.

1. Add this to your profile: export PATH="$PATH:/opt/yarn-[version]/bin" (the path may vary depending on where you extracted Yarn to)
2. In the terminal, log in and log out for the changes to take effect

To have access to Yarn’s executables globally, you will need to set up the PATH environment variable in your terminal. To do this, add export PATH="$PATH:yarn global bin" to your profile.

https://yarnpkg.com/en/docs/install#alternatives-stable

To Reproduce
Steps to reproduce the behavior:

1. Completely remove Yarn and YVM from your machine (remember to edit your PATH!!!)
2. Run curl -fsSL https://raw.githubusercontent.com/tophatmonocle/yvm/master/scripts/install.sh | bash
3. Run source yvm
4. Run yvm install 1.7.0
5. Run yvm use 1.7.0
6. Run yarn global add serve
7. Run which serve

Expected behavior
It should print out a path to the executable in the ~/.yarn/bin/ directory.

Screenshots
If applicable, add screenshots to help explain your problem.

Desktop (please complete the following information):

• OS: Ubuntu
• YVM Release: Fri, 27 Jul 2018 15:09:28 GMT

Additional context
Add any other context about the problem here.

Highlight currently active Yarn version in `yvm list` and `yvm list-remote`

Is your feature request related to a problem? Please describe.
If I have multiple versions of Yarn installed and I want to switch from one to another, I have to first run yvm which to determine which version I am currently using. Then I have to remember this version, and run yvm list to see what versions are installed. This requires more cognitive overhead than should be required for a tool like this.

Describe the solution you'd like
When you run yvm list or yvm list-remote, the currently active version should be highlighted with a different color AND an arrow should be pointing to it like in nvm (see screenshot below).

Describe alternatives you've considered
An alternate solution is to simply add a line at the beginning or end of the version output that states what version is currently being used. This approach is not the best because there is a lot of info being printed on the screen in these commands, so it is likely to be missed.

Additional context

Support install on shells other than zsh

Installer script

• Put yvm on the $PATH

Consistent formatting for list commands

yvm list and yvm list-remote list version numbers in two different ways: one with "v" prefix and one without. We should make the listing consistent with the commands that the user may run next (eg. yvm use 1.7.0 or yvm exec 1.7.0), so we should remove the "v" prefix.

You can use stripVersionPrefix in src/common/utils.js

Add aliases for commands

• i from install
• ls for list
• rm for remove

Change to directory switches to correct yarn version (looks for rc file)

• Look for RC file on directory change

Add short descriptions for each command

.description('Some description')

`make install-watch` should reset link `/usr/local/bin/yvm` when it is stopped

Open source repo setup

• Create repo
• Collaborators
• CircleCI (Test runner, auto publish to install script in the future)
• Basic PR template
• Basic issue template #94
• Basic Readme
• Basic Contributing
• Open source license

Make it easier to test changes to JS files

Before, we could run node yvm.js to test the JS code, but since we added Babel, we need to compile every time.

So far, I have just been running make install every time, but it would be nice to have either:

• make watch - to watch, rebuild and copy to ~/.yvm
• symlink webpack build artifacts to ~/.yvm

Codecov no longer works

Describe the bug
Code coverage is not being reported

Fix
Tried to activate but it seems there app is having trouble:
https://codecov.io/gh

Will need to update the CODECOV_TOKEN here https://circleci.com/gh/tophat/yvm/edit#env-vars when they come back

List installed Yarn versions

The exec command doesn't forward arguments correctly

Describe the bug

yvm exec tag --help

tag --help gets passed to the yvm command instead of being passed to the yarn command directly. The --help triggers the yvm help instead of getting passed correctly to the yarn command.

Workaround:

yvm exec -- tag --help

This will pass arguments to the underlying command correctly, but it's not ideal.

Expected behavior
A clear and concise description of what you expected to happen.

All arguments passed to exec should get passed to the underlying yarn version

Support Fish shell

Is your feature request related to a problem? Please describe.
To use yvm use, I have to source yvm within my shell environment. However, because yvm shell syntax is not compatible with fish shell,
sourcing will not work properly.

> source /usr/local/bin/yvm
/usr/local/bin/yvm (line 25): Unsupported use of '&&'. In fish, please use 'COMMAND; and COMMAND'.
    [ -n "${1-}" ] && [ -x "$(yvm_version_path "$1" 2> /dev/null)"/bin/yarn ]
                    ^
from sourcing file /usr/local/bin/yvm
        called on standard input

source: Error while reading file '/usr/local/bin/yvm'

Describe the solution you'd like
Provide additional shell script for sourcing yvm in fish shell.

virtualenv uses a similar approach. In its environment directory, has separate activate scripts for bash, fish shell, and windows CMD.

Describe alternatives you've considered

Additional context

Getting a segfault when trying to do a `yarn install` using yvm

Describe the bug
When I run yarn install with yvm I'm getting a segfault:

75162/91112/Users/******/.yvm/yvm.sh: line 82: 60566 Segmentation fault: 11  node "${YVM_DIR}/yvm.js" $@
make: *** [node_modules] Error 139

Idea: use exec instead of __non_webpack_require__

Instead of requiring the yarn bin js file, lets exec the yarn command.

If yarn ever changes their entry point to a shell script instead of a js file, we will suddenly stop working 😞

Implement yvm which command

Implement yvm which command

better command help: yvm exec list says -> Invalid .yvmrc version: null

Can we make the error messaging a little more helpful.
Something like:

$yvm exec list
No version supplied, no .yvmrc
Perhaps you wanted to specify your version like?
  yvm exec 1.2.0 list

List Yarn versions available for download.

Add next steps at end of install script

At the end of the install script, tell user to source yvm or open a new shell window.

Integrate with dev env and use in current FE apps

• put in devenv-boostrap
• Put it in our apps
• Start upgrading, yarn v1.0.2"

yvm - semantic release versioning

Is your feature request related to a problem? Please describe.
It would be good for users to install specific versions (and easily identify what versions have problems, will break API's etc). We are running under continuous release right now, and while this is great for us, is not so great for the wider internet.

Describe the solution you'd like
Someway to version yvm (open to suggestions)

Describe alternatives you've considered
We could use npm to host the core of our JS app

Extra commands ("which", "list", etc)

• Additional cool commands

Set the yarn version to use for the current shell session

• Change yarn bin path to whatever user wants

Remove dependency on npm

Yarn version manager should not depend on npm.

Remove need for npm install on host.
Switch build over to use YVM.

yvm help should show help

Determine best tool/language/environment

• Shell script wrapper, firing into Node library
• Research best method"

Warn if calling `yvm use` when `yvm` isn't a shell function

When this happens, the PATH isn't correctly updated

Support node 6

Write documentation

• Goodo docs

Make sure that user has minimum node version

Currently yvm is built on node 8.11.3. If a user tries to use yvm with a lower version (e.g 6.11.5) it will throw a syntax error.

This can be tackled by either:

1. Displaying a message to ensure the correct node version (index.js)
2. Using backwards compatible syntax

Support for `yvm use` command

Support yvm use for switching currently active yarn version

Detect other yarn versions on path, and warn about conflicts?
e.g. $PATH contains: /Users/jakebolam/.yarn/bin:/

Running `yvm exec` in a nested directory, says it can't find the .yvmrc file

Describe the bug
Running yvm exec in a nested directory fails saying it can't find the .yvmrc file

To Reproduce
Steps to reproduce the behavior:

1. Create a valid .yvmrc file
2. Create a new directory, enter that sub-directory
3. Run yvm exec list
4. See error

Expected behavior
yvm should search up the tree for .yvmrc files

Additional notes
This has introduced other behaviour (such as having a root level yvm.config.js file, or declaring in package.json. Do we want this?