CodeVetter · Repo Unpack · Contributor handoff
sveltejs/svelte
Read `AGENTS.md`, `CONTRIBUTING.md`, and `.github/PULL_REQUEST_TEMPLATE.md` first — the repo's own agent guide makes the PR template mandatory and forbids submitting without a full test run. The dominant convention is `snake_case` internally, `camelCase` publicly; the dominant workflow is add a fixture directory, not a new test file. The two hard edit boundaries are generated files (types, error/warning modules, generated docs) and the compiler/runtime import firewall. Expect long feedback loops: the full suite covers ~3,400 fixtures across 4 variants, so filter aggressively while iterating and only run the full suite before opening a PR.
- `AGENTS.md` is explicit that `CONTRIBUTING.md` must also be read, that `PULL_REQUEST_TEMPLATE.md` must be read and filled out correctly for any PR, and that PRs must not be submitted without running the full test suite.
- Naming convention is enforced, not advisory: `snake_case` for internal variables and methods, `camelCase` for public ones, backed by the `lube/svelte-naming-convention` ESLint rule set to `error` with `fixSameNames: true`.
- Never hand-edit `packages/svelte/types/index.d.ts`, `src/compiler/errors.js`, or the four `warnings.js` modules — they are generated by `pnpm generate` and CI fails the `Lint` job if `git status` is dirty after `pnpm build`.
- Never import from `../compiler/` or `#compiler` inside `packages/svelte/src/**` outside `src/compiler/**` — the custom `no_compiler_imports` rule string-searches the file text and rejects even JSDoc type references.
- Adding a test means creating a directory under `packages/svelte/tests/<suite>/samples/`, optionally with a `_config.js` default-exporting the config object — `for_each_dir` in `suite.ts` discovers it automatically, so no test file is edited.
- Files prefixed with `_` inside a sample directory are excluded from compilation by `compile_directory`, which is how `_config.js` coexists with the component files it tests.
- A sample directory containing only `_output` or `_actual.json` is treated as leftover from another branch and silently skipped — so a suite that appears to pass may simply not have run.
- Tests require Chromium to be installed first (`pnpm playwright install chromium`) or the `runtime-browser` and custom-elements suites will fail to launch.
- Iterate with `pnpm test <suite>`, `pnpm test <suite> -t <name>`, or `FILTER=<name> pnpm test <suite>`; snapshot suites are regenerated with `UPDATE_SNAPSHOTS=true pnpm test`.
- Typechecking is a three-project run inside `packages/svelte`: `tsc --project tsconfig.runtime.json && tsc && cd ./tests/types && tsc` — the `tests/types` project exists purely to typecheck public API ergonomics (`actions.ts`, `snippet.ts`, `store.ts`, `bindings.svelte`, …).
- Any change under `packages/svelte/src` requires a changeset (`npx changeset`) per the PR template; the root `changeset:version` script also runs `pnpm -r generate:version` so `src/version.js` stays in sync.
- For performance work, use the `performance-investigation` skill: run `pnpm bench:compare main <branch>`, read `benchmarking/compare/.results/report.txt`, then diff the per-benchmark `.md` CPU-profile summaries, and re-run `pnpm test runtime-runes` afterward.
- Files to read first for the compiler: `src/compiler/index.js`, `phases/1-parse/index.js`, `phases/2-analyze/index.js`, `phases/3-transform/index.js`, `phases/scope.js`, `phases/bindings.js`.
- Files to read first for the runtime: `internal/client/constants.js` (the flag vocabulary, which nothing else makes sense without), `internal/client/runtime.js`, `reactivity/{sources,deriveds,effects,batch}.js`, `internal/client/render.js`, `internal/client/proxy.js`.
- Known trap: `tests/README.md` is a stale migration-era document listing 'TODOs' and 'tests not copied over yet' from the Svelte 4→5 rewrite; treat it as historical context rather than current guidance. (inferred)
- Known trap: `pnpm-workspace.yaml` sets `minimumReleaseAge: 2880` and `blockExoticSubdeps: true`, so adding a freshly-published third-party dependency will be rejected unless it is on the `minimumReleaseAgeExclude` list.