mjs/cosmjs
mjs/cosmjs
1
0
Fork 0
mirror of https://github.com/cosmos/cosmjs.git synced 2025-03-10 21:49:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update YARN.md

Browse Source
This commit is contained in:
willclarktech 2021-05-26 15:21:22 +02:00
parent 2a08145e7a
commit 41147395eb
No known key found for this signature in database
GPG Key ID: 551A86E2E398ADF7
1 changed files with 164 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

234
docs/YARN.md
View File

@ -14,11 +14,23 @@ documentation (except where indicated), to help others get through the process
faster than I did. It won’t cover every feature of Yarn v2, just enough for you
to complete the migration and be confident it was worthwhile.
## Update Yarn v1 to the latest version (eg v1.22)
Overall I would say that the Yarn vision is pretty impressive:
- zero installs are very cool,
- enforcing strict dependency specification gives us confidence we never had
with `node_modules`,
- delegating dependency resolution to the package manager makes a lot of sense.
However, it’s an open source project with limited resources, hence the difficult
documentation and slightly unstable feel. Moreover the ecosystem often does not
live up to the high standards required to reap all the benefits (eg packages not
listing all their dependencies).
## Step 1: Update Yarn v1 to the latest version (eg v1.22)
For example: `npm install --global yarn` or `brew upgrade yarn`.
## Enable Yarn v2 in your project
## Step 2: Enable Yarn v2 in your project
Navigate inside the project and run `yarn set version berry`.
@ -51,7 +63,7 @@ $ (cd .. && which yarn && yarn --version)
Weird, right? 🤷
## Transfer your configuration to the new configuration file
## Step 3: Transfer your configuration to the new configuration file
You might not have had either, but any configuration in a `.npmrc` or `.yarnrc`
file will need to be transferred to the newly created `.yarnrc.yml` file.
@ -63,7 +75,7 @@ options might secretly relate to plugins which you will need to install (for
example I added `changesetBaseRefs` and was informed it wasn’t a valid
configuration option until I added the `version` plugin).
## Set the Node linker to node-modules (for now)
## Step 4: Set the Node linker to node-modules (for now)
One of the core concepts in Yarn v2 is the
[Zero Install](https://yarnpkg.com/features/zero-installs), ie packages that
@ -77,7 +89,7 @@ own module resolution strategy, because that’s what Yarn v1 uses:
nodeLinker: "node-modules"
```
## Add any other basic configuration you need
## Step 5: Add any other basic configuration you need
For example:
@ -92,12 +104,12 @@ Refer to the
[configuration documentation](https://yarnpkg.com/configuration/yarnrc) (with
the same caveat as above).
## Migrate the lockfile
## Step 6: Migrate the lockfile
Run `yarn install` and Yarn will sort it all out. It will probably give you a
bunch of warnings. Note that `yarn.lock` is now valid YAML, unlike with Yarn v1.
## Tell VCS which files to ignore
## Step 7: Tell VCS which files to ignore
Add all of this to your `.gitignore` (or whatever):
@ -114,7 +126,7 @@ Add all of this to your `.gitignore` (or whatever):
Everything else that’s new or changed should be committed. We’ll come back to
this ignore list when we revisit Plug‘n’Play.
## Update Yarn CLI invocations and options in scripts
## Step 8: Update Yarn CLI invocations and options in scripts
If are using the Yarn CLI tool in any scripts you will need to update some
command and option names which have changed from v1 to v2. For example
@ -123,26 +135,66 @@ changes weren’t covered in the official documentation, so have fun finding out
which ones still work. A table of changes to commands can be found
[here](https://yarnpkg.com/getting-started/migration#renamed).
## Add the `workspace-tools` plugin
## Step 9: Add plugins
`yarn plugin import workspace-tools`.
Adding a plugin updates the `.yarnrc.yml` file and adds a plugin to
`.yarn/plugins`. Here are some helpful ones, but there are more and you can even
write your own.
Updates `.yarnrc.yml` Adds a plugin to `.yarn/plugins`
### `workspace-tools`
```sh
yarn plugin import workspace-tools
```
Most importantly this will let you use the `yarn workspaces foreach` command.
See [the docs](https://yarnpkg.com/cli/workspaces/foreach) for more information.
**NOTE:** The root project is a valid workspace, which means if you want to run
a script in all workspaces _except_ the root, other than running a script
defined in the root `package.json`, you have to filter it out.
a script using `foreach` in all workspaces _except_ the root, other than running
a script defined in the root `package.json`, you have to filter it out.
**NOTE:** You probably want to use the `--parallel`, `--topological-dev` and
`--verbose` options in most cases.
## Specify missing dependencies
### `version`
Yarn v2 claims to enforce dependencies strictly. You may be used to listing
```sh
yarn plugin import version
```
This lets you do version things. More info: https://yarnpkg.com/cli/version
### `interactive-tools`
```sh
yarn plugin import interactive-tools
```
Most useful for `yarn upgrade-interactive`: see
https://yarnpkg.com/cli/upgrade-interactive
### `typescript` (maybe)
Automatically installs DefinitelyTyped `@types/*` definitions if the project
doesn’t have its own. This sounds useful, but might actually be annoying because
sometimes you don’t need the type definitions even when they’re available (eg
for tools). I installed it initially but ended up removing it.
```sh
yarn plugin import typescript
```
More info:
https://github.com/yarnpkg/berry/tree/master/packages/plugin-typescript
## Step 10: Specify missing dependencies
Yarn v2 wants to enforce dependencies strictly. You may be used to listing
development dependencies in the root of the project and then being able to use
the executables they define in workspaces. But Yarn v2 won’t let you, so if you
are using any of these executables in you `package.json` scripts you’ll need to
add the relevant development dependency to the workspace. This doesn't mean that
are using any of these executables in your `package.json` scripts you’ll need to
add the relevant development dependency to the workspace. This doesn’t mean that
it will install duplicates, as long as you tell it not to via
`yarn add --interactive`. (You can also set `preferInteractive` in the
`.yarnrc.yml` file.)
@ -162,15 +214,20 @@ whether you are using the `workspace-tools` plugin, and how:
-> OK if dependency is not specified in workspace as long as it is in the
worktree
See https://yarnpkg.com/features/workspaces#what-does-it-mean-to-be-a-workspace
(This might depend on which linker you’re using.) See
https://yarnpkg.com/features/workspaces#what-does-it-mean-to-be-a-workspace for
more information on workspaces.
## Specify local dependencies as workspaces
## Step 11: Specify local dependencies as workspaces
I.e. `workspace:packages/xxx`
In packages which depend on other packages in the same monorepo, you can specify
these dependencies using the `workspace:packages/my-other-package` format. This
way you don’t need to constantly update the versions manually, it’ll all be
calculated for you at publication time.
https://yarnpkg.com/features/workspaces#workspace-ranges-workspace
More info: https://yarnpkg.com/features/workspaces#workspace-ranges-workspace
## Adjust lifecycle scripts
## Step 12: Adjust lifecycle scripts
Unlike npm or Yarn v1, Yarn v2 won’t run arbitrary lifecycle scripts (i.e.
`prexxx` and `postxxx`). There are
@ -187,11 +244,12 @@ get confusing if people start trying to use other package managers. It’s much
simpler just to put it all in the same script definition, or outsource to a
script file.
## Check it works
## Intermission: Check it works
At this point you should have a working setup.
At this point you should have a working setup. Make sure you can build, test,
lint, run scripts etc.
## Remove shx or equivalents (probably)
## Step 13: Remove shx or equivalents (probably)
According to
[this blog post](https://dev.to/arcanis/introducing-yarn-2-4eh1#normalized-shell):
@ -205,61 +263,37 @@ So you probably don’t need `shx` or any other tool that you were using for
cross-platform shell compatibility. Then again, maybe you do still need it
because you use a language structure outside the 90%. 🤷
## Consider using constraints
E.g. to ensure that each package specifies the right fields in its
`package.json`. Bonus: you get to learn Prolog!
https://yarnpkg.com/features/constraints
## TypeScript plugin
Automatically installs DefinitelyTyped `@types/*` definitions if the project
doesn’t have its own. This sounds useful, but might actually be annoying because
sometimes you don’t need the type definitions even when they’re available (eg
for tools).
```sh
yarn plugin import typescript
```
https://github.com/yarnpkg/berry/tree/master/packages/plugin-typescript
## Version plugin
```sh
yarn plugin import version
```
## interactive-tools plugin
Most useful for `yarn upgrade-interactive`
https://yarnpkg.com/cli/upgrade-interactive
## Plug-n-play and node_modules
## Step 14: Enable plug-n-play
Read about the problems of `node_modules` and how Yarn aims to fix them here:
https://yarnpkg.com/features/pnp#the-node_modules-problem
The rest of this section will take you through adding PnP. This was the most
painful part of the process, introducing many shiny new things that the rest of
the ecosystem doesn’t seem quite ready for.
[Die Idee ist gut, doch die Welt noch nicht bereit](https://www.youtube.com/watch?v=SW8a7svcQGY).
If you choose to skip this section that is a totally legitimate decision.
### Check whether your project is ready
```sh
yarn dlx @yarnpkg/doctor@2
```
**NOTE:** You need to specify the `@2` because they released the incompatible v3
RC as `latest` on npm.
**NOTE:** You need to specify the `@2` because the incompatible v3 release
candidate was released as `latest` on npm.
By the way, this uses another new feature of Yarn v2: `yarn dlx`. This is like
`npx`, but ...
`npx`, but downloads the package only temporarily and then throws it away.
### Remove the `nodeLinker` setting from `.yarnrc.yml`.
Uses default PnP setting.
This uses the default PnP setting, which is the real Yarn v2 magic.
### Install again
Run `yarn`. This will remove the `node_modules/` directory.
Run `yarn`. This will remove the `node_modules/` directory and store lots of zip
files in `.yarn/cache`.
### Update the VCS ignore list
@ -275,23 +309,83 @@ Remove what you put there before and add these:
!.yarn/versions
```
Basically we’re adding the cache and the `.pnp.js` file to VCS.
Basically we’re adding the cache and the `.pnp.js` file to VCS. It might seems
weird to add all those zip files to version control, but the reasoning is in the
article listed above.
Before you add these to the VCS index, you might want to think about how you
want to store the large zip files. For example, if you’re using Git LFS you
could get it to handle zip files by adding the following to `.gitattributes`:
```
*.zip filter=lfs diff=lfs merge=lfs -text
```
### Run node using yarn node
Replace calls to node outside of a `package.json` script with `yarn node`. For
example in shebangs in development scripts. (You probably don’t want to update
executables you will ship to your users because they may not be using Yarn.)
Replace calls to `node` outside of a `package.json` script with `yarn node`. For
example in shebangs in development scripts. You can pass the `-S` option to make
this work like this:
## Switch versioning from Lerna to Yarn
```sh
#!/usr/bin/env -S yarn node
```
You probably don’t want to update executables you will ship to your users
because they may not be using Yarn, but that means you’ll have to remember to
run them using `yarn node` from within your project rather than just executing
them directly.
### Add in support for ESM (if needed)
Running Node via Yarn v2 does not handle ESM as described in this issue:
https://github.com/yarnpkg/berry/issues/638
For a quick solution, you can run `yarn add -D esm` in every relevant package,
and then replace every `yarn node script.js` with a
`yarn node --require esm script.js`.
For a more general workaround, check out this repo:
https://github.com/DaneTheory/yarn-pnp-with-esm
### Maybe don’t use Node v15+ until you upgrade to Yarn v3(!!!)
It might not affect you but there’s an issue with the `fs` patch and `bigint`,
which is solved in v3, but won’t be backported to v2:
https://github.com/yarnpkg/berry/issues/2232#issuecomment-818514929
### Setup your IDE
Make sure you have everything you want your IDE to use installed in the root of
the project. I suggest `typescript` and `prettier` at least. Then run
```sh
yarn dlx @yarnpkg/pnpify --sdk
```
This will set up your IDE and put a bunch of things in `.yarn/sdks`, which
you’ll want to add to VCS. If you’re using VSCode, it will also add some stuff
to `.vscode/extensions.json` and `.vscode/settings.json`. You may or may not
want to add these to VCS—talk to your colleagues.
https://next.yarnpkg.com/advanced/pnpify#ide-support
## Step 15: Switch versioning from Lerna to Yarn
Lerna unfortunately appears to be unmaintained. Remove the dependency and the
`lerna.json` configuration file.
You can read about Yarn’s release workflow here:
https://next.yarnpkg.com/features/release-workflow
https://yarnpkg.com/features/workspaces#yarn-workspaces-vs-lerna
## Step 16: Consider using constraints
## Setup for IDE
E.g. to ensure that each package specifies the right fields in its
`package.json`. Bonus: you get to learn Prolog! (I for one did not have time.)
https://next.yarnpkg.com/advanced/pnpify#ide-support
More info: https://yarnpkg.com/features/constraints
## Conclusion
That’s it! There’s a lot more configuration available that has not been covered
here, but hopefully you made it through all that and your code still works.