41 lines
2.2 KiB
Markdown
41 lines
2.2 KiB
Markdown
|
# AGENTS.md - Yarn Spinner Loader
|
||
|
|
|
||
|
|
## Commands
|
||
|
|
- `npm run build` — Build all entry points (tsup, ESM + CJS)
|
||
|
|
- `npm run dev` — Watch mode
|
||
|
|
- `npm run test` — Vitest watch mode
|
||
|
|
- `npm run test:run` — Run tests once
|
||
|
|
- `npm run typecheck` — `tsc --noEmit`
|
||
|
|
|
||
|
|
## Architecture
|
||
|
|
- **`src/index.ts`** — Main entry point. Full browser package: parse + compile + run + all types. No Node.js deps.
|
||
|
|
- **`src/core.ts`** — Mirror of index.ts. Not in package.json exports.
|
||
|
|
- **`src/runner.ts`** — Minimal runtime export: `YarnRunner` + runtime/IR types only. No parser, no compiler.
|
||
|
|
- **`src/loader/`** — Filesystem loader: parses `.yarnproject` files, validates against JSON schema (ajv), resolves globs (fast-glob), compiles `.yarn` files.
|
||
|
|
- **`src/plugins/`** — Build tool plugins: esbuild, rollup, vite, webpack. Each is a separate tsup entry point outputting to `dist/plugins/`.
|
||
|
|
- **`src/yarn-spinner/`** — Embedded Yarn Spinner implementation: `parse/`, `compile/`, `runtime/`, `markup/`, `model/`.
|
||
|
|
- **`src/runner/`** — Empty directory. Ignore.
|
||
|
|
|
||
|
|
## Package exports
|
||
|
|
- `yarn-spinner-loader` → `dist/index.js` (full browser package)
|
||
|
|
- `yarn-spinner-loader/runner` → `dist/runner.js` (runtime only)
|
||
|
|
- `yarn-spinner-loader/esbuild` → `dist/plugins/esbuild.js`
|
||
|
|
- `yarn-spinner-loader/rollup` → `dist/plugins/rollup.js`
|
||
|
|
- `yarn-spinner-loader/vite` → `dist/plugins/vite.js`
|
||
|
|
- `yarn-spinner-loader/webpack` → `dist/plugins/webpack.js`
|
||
|
|
|
||
|
|
## Key conventions
|
||
|
|
- `src/index.ts` and `src/core.ts` must NOT import from `src/loader/` or any Node.js-specific modules.
|
||
|
|
- `src/loader/` is the only code that uses `fs`, `path`, `fast-glob`.
|
||
|
|
- TypeScript: strict mode, ES2022, `moduleResolution: "bundler"`.
|
||
|
|
- Tests live in `tests/`, not `src/`. Pattern: `tests/**/*.test.ts`.
|
||
|
|
|
||
|
|
## Build notes
|
||
|
|
- tsup config has 6 entry points. Main + runner output to `dist/`, plugins output to `dist/plugins/`.
|
||
|
|
- `npm run build` cleans `dist/` automatically.
|
||
|
|
- `core.ts` is NOT exported in package.json — it exists for internal consistency only.
|
||
|
|
- This package is intended as a `devDependency` alongside bundlers. Dependencies (`ajv`, `fast-glob`) are needed at build time.
|
||
|
|
|
||
|
|
## Security
|
||
|
|
- `.npmrc` contains an npm auth token. Never commit or expose this.
|