192 lines
3.5 KiB
Markdown
192 lines
3.5 KiB
Markdown
# 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.
|