marco-trest-test/docs/yarn-basics-cheatsheet.md

Yarn Basics Cheat Sheet (Beginner)

This page explains Yarn from zero and gives a short command set you can use daily.

1) What Yarn Is

Yarn is a JavaScript/TypeScript package manager.

It helps you:

• Install libraries your project depends on.
• Keep dependency versions consistent.
• Run scripts defined by the project.
• Work with private package registries.

2) Core Concepts

Package

A package is reusable code published to a registry (for example npm or your company Gitea registry).

Example in this project context:

• @jig-software/trest

Dependency

A dependency is a package your app needs to run.

• Regular dependency: needed at runtime.
• Dev dependency: needed for development/testing only.

package.json

This file declares project metadata and dependencies.

yarn.lock

This lock file pins exact dependency versions to keep installs reproducible across machines and CI.

Registry

A registry is where packages are downloaded from.

• Public: npmjs
• Private: your company Gitea Packages endpoint

Scope

A scope is a package namespace like @jig-software.

A scope can be routed to a custom registry in .yarnrc.yml.

.yarnrc.yml

Project-level Yarn config. It controls behavior such as:

• Registry URLs
• Authentication token source
• Install/link strategy

PnP (Plug'n'Play)

PnP is Yarn's alternative to node_modules.

• Faster and stricter dependency resolution.
• Dependencies are mapped through .pnp.cjs.
• Some tools that assume node_modules may need extra config.

3) How Your Current .yarnrc.yml Works

From this repo config:

• nodeLinker: pnp means no traditional node_modules tree.
• npmScopes.jig-software routes @jig-software/* packages to Gitea.
• npmAuthToken reads token from env var JIG_SOFTWARE_GITEA_DEPLOYMENT_TOKEN.
• npmAlwaysAuth: true always sends auth to that private registry.

4) 8 Commands You Need Day-to-Day

1. Check Yarn version

yarn --version

2. Install all dependencies from lockfile

yarn install

3. Add a dependency

yarn add <package-name>

4. Add a dev dependency

yarn add -D <package-name>

5. Remove a dependency

yarn remove <package-name>

6. Run a package script

yarn <script-name>

7. Inspect package info in registry

yarn npm info @jig-software/trest

8. Install trest from private scope

yarn add @jig-software/trest

5) Private Registry Quick Start (This Company)

1. Export token in shell:

export JIG_SOFTWARE_GITEA_DEPLOYMENT_TOKEN="<your-gitea-token>"

2. Verify package access:

yarn npm info @jig-software/trest

3. Install package:

yarn add @jig-software/trest

6) Common Errors and Fixes

Error: 401 Unauthorized

Likely causes:

• Missing or expired token.
• Wrong token scopes.

Fix:

• Re-export token and retry.
• Regenerate PAT with package read access.

Error: 404 on whoami

Some Gitea npm endpoints do not support whoami.

Fix:

• Use yarn npm info @jig-software/trest as the verification command.

Error: tool expects node_modules

Cause:

• Project uses PnP.

Fix:

• Configure that tool for PnP, or switch linker mode for that project if approved by the team.

7) Mental Model

Use this flow every time:

1. package.json asks for packages.
2. yarn.lock pins exact versions.
3. .yarnrc.yml tells Yarn where/how to fetch.
4. Yarn installs and links dependencies (PnP here).
5. Scripts run with the installed dependency graph.

If one step fails, debug that layer first.