Introduction

Yarn v2 and newer releases changed dependency file layout, so old Yarn v1 .gitignore templates are often wrong for modern projects. The correct rules depend on one policy choice: whether your repository uses zero-install or install-on-clone. Once that policy is explicit, .gitignore becomes straightforward and stable.

Understand Yarn Berry File Roles

Yarn Berry introduces a .yarn directory with both important project files and machine-generated cache artifacts.

Common files and directories:

• '.yarnrc.yml configuration file'
• 'yarn.lock dependency lock file'
• '.yarn/releases and plugins used by project'
• '.yarn/cache package archives'
• '.pnp.cjs and optional .pnp.loader.mjs for Plug and Play mode'

Some of these should be committed, some should be ignored. Treating all .yarn files the same leads to either noisy diffs or broken clones.

Pick a Dependency Policy First

Before writing rules, define team policy.

Install-on-clone policy:

• repository stores lock and Yarn config
• developers and CI run yarn install
• cache artifacts are ignored

Zero-install policy:

• repository stores package cache and Plug and Play artifacts
• fresh clone can run commands without fetching dependencies

Without this policy, .gitignore debates repeat every sprint.

Recommended .gitignore for Install-on-Clone

This setup is common in teams optimizing for smaller repositories and cleaner diffs.

1# Node outputs
2node_modules/
3dist/
4build/
5
6# Yarn Berry base
7.yarn/*
8
9# Keep critical Yarn directories
10!.yarn/patches
11!.yarn/plugins
12!.yarn/releases
13!.yarn/sdks
14!.yarn/versions
15
16# Ignore generated state and cache
17.yarn/cache
18.yarn/unplugged
19.yarn/build-state.yml
20.yarn/install-state.gz
21
22# Ignore Plug and Play runtime artifacts in install-on-clone mode
23.pnp.cjs
24.pnp.loader.mjs
25
26# Misc
27*.log
28.env
29.env.*

This keeps repository deterministic through lock files without storing package archives.

Adjust Rules for Zero-Install

In zero-install workflows, keep cache and Plug and Play runtime files committed.

Typical changes:

• remove .yarn/cache from ignore rules
• track .pnp.cjs and loader file
• still ignore transient install-state files unless your team explicitly needs them

Pair this with .yarnrc.yml settings that match your linker mode.

nodeLinker: pnp
enableGlobalCache: false

Consistency between config and ignore rules prevents confusing dependency behavior.

Validate Ignore Behavior Explicitly

Do not guess what Git tracks. Verify with commands.

git status --short
git check-ignore -v .yarn/cache/example.zip
git check-ignore -v .pnp.cjs

If files are already tracked from older commits, remove from index once.

git rm -r --cached .yarn/cache
git rm --cached .pnp.cjs

Then recommit with updated ignore policy.

Monorepo and Workspace Considerations

Monorepos often mix Yarn workspaces with build tooling caches. Keep Yarn-specific rules focused, then add separate rules for framework outputs.

Examples to handle separately:

• test coverage artifacts
• bundler cache folders
• framework-specific build directories

Avoid giant copied templates. Small, intentional ignore sets are easier to maintain.

Keep CI and Docs in Sync with Ignore Policy

Your .gitignore, CI install commands, and onboarding docs should describe the same strategy.

Examples:

• install-on-clone projects should run yarn install --immutable in CI
• zero-install projects should verify cache files are present and unchanged

If docs and CI disagree, developers will commit or remove dependency artifacts unpredictably.

Common Pitfalls

• Ignoring all .yarn content and accidentally removing required release files.
• Mixing zero-install and install-on-clone expectations in one repository.
• Updating .gitignore but forgetting to untrack already-committed cache files.
• Copying Yarn v1 rules directly into Yarn Berry projects.
• Running CI commands that conflict with chosen dependency policy.

Summary

• Yarn v2 .gitignore depends on clear dependency management policy.
• Keep essential Yarn config tracked and ignore only policy-specific artifacts.
• Use one rule set for install-on-clone and another for zero-install.
• Validate rules with Git commands instead of assumptions.
• Align CI and documentation with the same repository policy.