Better workflow than npm | yarn link for package authors.
When developing and authoring multiple packages (private or public), you often find yourself in need of using the latest/WIP versions in other projects that you are working on in your local environment without publishing those packages to the remote registry. NPM and Yarn address this issue with a similar approach of symlinked packages (
npm/yarn link). Though this may work in many cases, it often brings nasty constraints and problems with dependency resolution, symlink interoperability between file systems, etc.
yalcacts as very simple local repository for your locally developed packages that you want to share across your local environment.
- When you run
yalc publishin the package directory, it grabs only files that should be published to NPM and puts them in a special global store (located, for example, in
- When you run
yalc add my-packagein your
projectit pulls package content into
.yalcin the current folder and injects a
package.json. Alternatively, you may use
yalc link my-packagewhich will create a symlink to the package content in
node_modulesand will not touch
npm/yarn linkdoes), or you even may use it with Pnmp/Yarn/Npm workspaces.
yalccreates a special
yalc.lockfile in your project (similar to
package-lock.json) that is used to ensure consistency while performing
yalccan be used with projects where
npmpackage managers are used for managing
npm i yalc -g
yarn global add yalc
Some documented features might not have been published yet, see the change log.
yalc publishin your dependency package
- It will copy all the files that should be published in remote NPM registry.
- If your package has any of these lifecycle scripts:
preyalcpublish, they will run before in this order. If your package has any of these:
postpublish, they will run after in this order. Use
--no-scriptsto publish without running scripts.
- While copying package content,
yalccalculates the hash signature of all files and, by default, adds this signature to the package manifest
version. You can disable this by using the
- You may also use
.yalcignoreto exclude files from publishing to yalc repo, for example, files like README.md, etc.
--filesflag will show included files in the published package
- NB! In terms of which files will be included in the package
yalcfully supposed to emulate behavior of
npm pack). If you have nested
.yalcfolder in your package that you are going to publish with
yalcand you use
fileslist, it should be included there explicitly.
- NB! Windows users should make sure the
LFnew line symbol is used in published sources; it may be needed for some packages to work correctly (for example,
yalcwon't convert line endings for you (because
- NB! Note that, if you want to include
.yalcfolder in published package content, you should add
- Easily propagate package updates everywhere.
- Yalc by default resolve
workspace:protocol in dependencies, to omit this use
yalc add my-packagein your dependent project, which will copy the current version from the store to your project's
.yalcfolder and inject a
- You may specify a particular version with
yalc add my-package@version. This version will be fixed in
yalc.lockand will not affect newly published versions during updates.
- Use the
--linkoption to add a
link:dependency instead of
- Use the
--devoption to add yalc package to dev dependencies.
--pureflag it will not touch
package.jsonfile, nor it will touch modules folder, this is useful for example when working with Yarn workspaces (read below in Advanced usage section)
-W) it will add dependency with "workspace:" protocol.
- As an alternative to
add, you can use the
linkcommand which is similar to
npm/yarn link, except that the symlink source will be not the global link directory but the local
.yalcfolder of your project.
yalccopies package content to
.yalcfolder it will create a symlink:
project/.yalc/my-package ==> project/node_modules/my-package. It will not touch
package.jsonin this case.
yalc update my-packageto update the latest version from store.
yalc updateto update all the packages found in
postyalcscripts will be executed in target package on add/update operations which are performed while
- if need to perform pre/post
scriptson update of particular package use
(pre|post)yalc.package-namename for script in your
--up) to run package managers's update command for packages.
yalc remove my-package, it will remove package info from
yalc remove --allto remove all packages from project.
yalc installations clean my-packageto unpublish a package published with
yalc installations show my-packageto show all packages to which
my-packagehas been installed.
Pushing updates automatically to all installations
- When you run
yalc add|link|update, the project's package locations are tracked and saved, so
yalcknows where each package in the store is being used in your local environment.
yalc publish --pushwill publish your package to the store and propagate all changes to existing
yalcpackage installations (this will actually do
updateoperation on the location).
yalc push- is a use shortcut command for push operation (which will likely become your primarily used command for publication):
falseby default, so it won't run
pre/postscripts (may change this with passing
--changedflag yalc will first check if package content has changed before publishing and pushing, it is a quick operation and may be useful for file watching scenarios with pushing on changes.
--replaceoption to force replacement of package content.
updatedocs) to execute needed script on every push.
yarn/npm/pnpm updatecommand for pushed packages.
Keep it out of git
- If you are using
yalc'edmodules temporarily during development, first add
yalc link, that won't touch
- If you use
yalc addit will change
package.json, and ads
link:dependencies, if you may want to use
yalc checkin the precommit hook which will check package.json for
yalc'eddependencies and exits with an error if you forgot to remove them.
Keep it in git
- You may want to keep shared
yalc'edstuff within the projects you are working on and treat it as a part of the project's codebase. This may really simplify management and usage of shared work in progress packages within your projects and help to make things consistent. So, then just do it, keep
- Replace it with published versions from remote repository when ready.
- NB! - standard non-code files like
LICENCEetc. will be included also, so you may want to exclude them in
.gitignorewith a line like
**/.yalc/**/*.mdor you may use
.yalcignorenot to include those files in package content.
- Useful for monorepos (projects with multiple sub-projects/packages):
yalc publish some-projectwill perform publish operation in the
./some-projectdirectory relative to
Retreat and Restore
- Instead of completely removing package you may temporary set it back with
yalc retreat [--all]for example before package publication to remote registry.
- After or later restore it with
Use with Yarn/Pnpm workspaces
Use if you will try to
add repo in
workspaces enabled package,
--pure option will be used by default, so
package.json and modules folder will not be touched.
Then you add yalc'ed package folder to
package.json (you may just add
.yalc/@*/* patterns). While
push) operation, packages content will be updated automatically and
yarn will care about everything else.
If you want to override default pure behavior use
Clean up installations file
- While working with yalc for some time on the dev machine you may face the situation when you have locations where you added yalc'ed packages being removed from file system, and this will cause some warning messages when yalc will try to push package to removed location. To get rid of such messages, there is an explicit command for this:
yalc installations clean [package].
Override default package store folder
- You may use
--store-folderflag option to override default location for storing published packages.
--quietto fully disable output (except of errors). Use
--no-colorsto disable colors.
Set default options via .yalcrc
- For example add
workspace-resolve=falseline to the
.yalcrcfile to turn off
workspace:protocol resolution or
sig=falseto disable package version hash signature.
- yarn probably shouldn't cache packages resolved with a file path
- "yarn knit": a better "yarn link"
- yarn link does not install package dependencies
- [npm] RFC: file: specifier changes