# 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

```bash
yarn --version
```

2. Install all dependencies from lockfile

```bash
yarn install
```

3. Add a dependency

```bash
yarn add <package-name>
```

4. Add a dev dependency

```bash
yarn add -D <package-name>
```

5. Remove a dependency

```bash
yarn remove <package-name>
```

6. Run a package script

```bash
yarn <script-name>
```

7. Inspect package info in registry

```bash
yarn npm info @jig-software/trest
```

8. Install trest from private scope

```bash
yarn add @jig-software/trest
```

## 5) Private Registry Quick Start (This Company)

1. Export token in shell:

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

2. Verify package access:

```bash
yarn npm info @jig-software/trest
```

3. Install package:

```bash
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.