yarn-spinner-loader/AGENTS.md

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.