# 07 — Tooling & build

## Scripts

| `npm run …`           | Does                                                     |
| --------------------- | -------------------------------------------------------- |
| `build`               | `rm -rf dist && tsc --outDir dist`                       |
| `typecheck`           | `tsc --noEmit`, then `tsc -p tsconfig.test.json`         |
| `lint`                | `oxlint src test`                                        |
| `format`              | `oxfmt '*.md' 'src/**/*.{ts,js,json,md}' 'test/**/*.ts'` |
| `test` / `test:watch` | `vitest run` / `vitest`                                  |

## TypeScript 7

`package.json` pins `typescript@^7.0.2`. This choice constrains the lint
setup below. `tsconfig.json` highlights:

- `module: ESNext`, `moduleResolution: bundler`, `target: ESNext`
- `allowImportingTsExtensions` + `rewriteRelativeImportExtensions` — source
  imports each other with explicit `.ts` extensions, and `tsc` rewrites them
  to `.js` in the emitted output
- `declaration` + `declarationMap` — every module ships `.d.ts` + `.d.ts.map`
- `strict`, `isolatedModules`, `skipLibCheck`
- `include: ["src/**/*"]` only — `test/**` never reaches `dist/`. The
  root-level `oxfmt.config.ts` is outside this glob too, so it's never
  compiled.

## Linting: oxlint (not ESLint)

`oxlint.config.ts` — `oxlint@^1`, configured with `defineConfig`:
`plugins: ['typescript', 'unicorn', 'oxc']`, `categories` correctness→error /
suspicious+pedantic→warn, `max-lines*` and (in `test/`)
`max-classes-per-file` turned off.

**Why not `@typescript-eslint`:** it has no released version supporting
TypeScript 7 — its peer range caps at `<6.1.0`, and even loading
`@typescript-eslint/parser` crashes against TS 7's package shape. `oxlint`
has its own parser and never touches the `typescript` package, so it works
regardless of TS version.

**The tradeoff:** no type-aware rules — no `no-floating-promises`, no
`no-unnecessary-condition`, etc. Worth revisiting once `@typescript-eslint`
supports TS 7.

## Formatting: oxfmt

`oxfmt.config.ts` — `oxfmt` (the oxc project's formatter), configured with its
`defineConfig` default export:

```ts
export default defineConfig({
  semi: true,
  singleQuote: true,
  trailingComma: 'all',
  printWidth: 100,
  tabWidth: 2,
});
```

- Same toolchain family as `oxlint`; single native binary, no plugin
  ecosystem to pin against TS 7.
- Prettier-compatible options; the values above are Prettier's popular
  defaults, so running `oxfmt` over the existing tree is a near no-op.
- oxfmt auto-discovers `oxfmt.config.ts` (search order: `.oxfmtrc.json` →
  `.oxfmtrc.jsonc` → `oxfmt.config.ts` → `oxfmt.config.mts`); no `--config`
  flag needed. It reads `.gitignore` automatically.
- One behavioural difference from Prettier: oxfmt formats fenced code blocks
  _inside_ Markdown.
- Pre-1.0 — expect its output to shift between releases.

## Testing: Vitest + jsdom

`vitest.config.ts` — `environment: 'jsdom'`, `include: test/**/*.test.ts`,
`setupFiles: ['./test/setup.ts']`.

- **`test/setup.ts`** stubs `ResizeObserver` — jsdom doesn't implement it and
  `leaflet-map.ts` constructs one unconditionally, so without the stub even
  _importing_ the component throws. Nothing here depends on it firing.
- **Real Leaflet objects work under jsdom** for everything this library
  verifies: option/attribute wiring, event forwarding, child binding. No
  browser needed.
- **`onAdd()`-only state:** the `<img>`/`<video>` behind an overlay, a
  marker's `dragging` handler, `marker.getElement()` — these exist only once
  the layer is added to a real map. Tests touching them append through a
  `<leaflet-map>` rather than standalone.
- **`test/core/with-props.test.ts`** tests the mixin against a fake
  Leaflet-like class; the exception is child registration, which needs real
  `Popup`/`Tooltip`/`Layer` because `#onChildRegister` branches on
  `instanceof`.
- **`test/load-order.test.ts`** — see [06](./06-load-order.md); it's the only
  test reproducing real page load order.
- `test/**` is typechecked separately via `tsconfig.test.json` (`extends` the
  main config, `rootDir: '.'`, `noEmit`, adds `test/**/*` to `include`).

## Build output

`tsc` compiles `src/` → `dist/` as **individual ESM modules** — `.js` +
`.d.ts` + `.d.ts.map` per source file, no bundling step. `dist/elements/` and
`dist/components/` mirror the `src/` split one-to-one.

- Consumers import `dist/index.js` (or any single module) directly.
- **No CJS, no UMD** build.
- **Leaflet is always external** — never bundled. It's a `dependencies` entry
  and a bare `import` in the output.
- `package.json` `exports`: `.` → `dist/index.js` (+ types);
  `./elements` → `dist/elements/index.js` (the class barrel, no `define`);
  `./elements/*.js` and `./components/*.js` → the matching `dist/` module;
  `./dist/*` still there for deep imports.
- `sideEffects: true` — the `components/*` modules (and `index.js`) call
  `customElements.define()` at import time, so a bundler must not tree-shake
  them away. The `elements/*` modules have no side effect.

## Publishing to two registries

| Registry | Entry                                                    | Ships                                                                         |
| -------- | -------------------------------------------------------- | ----------------------------------------------------------------------------- |
| npm      | `package.json` `main`/`module`/`types` → `dist/…`        | compiled `dist/` + `README.md` (`files` field); `prepublishOnly` runs `build` |
| JSR      | `jsr.json` `exports` → `./src/index.ts` (+ `./elements`) | TypeScript source directly (JSR compiles per-consumer)                        |

Both are version `0.1.0`; keep them in step. JSR publishes `src/` with its
`.ts` import extensions intact, which JSR supports natively.