# Tomtom Maps Sdk JS Contribution

> Orient to the SDK contributor context. Use when a contributor asks how to work on, build, or modify the TomTom Maps SDK — or when the current task involves editing SDK source files in core/, map/, services/, plugins/, examples/, or map-integration-tests/.

- Skill: `tomtom-international/tomtom-maps-sdk-js-contribution` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tomtom-international/tomtom-maps-sdk-js-contribution`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomtom-international/tomtom-maps-sdk-js-contribution/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: tomtom-international (https://skillmd.com/u/tomtom-international)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomtom-international/tomtom-maps-sdk-js-contribution

---


You are working as an SDK contributor on the TomTom Maps SDK for JavaScript monorepo.

`AGENTS.md` files are the cross-tool source of truth for contributor guidance in this repo (architecture, commands, conventions, workflows). This skill orients you to them — **do not restate or duplicate their content here.**

## Orientation steps

1. **Always** read the root `AGENTS.md` first for architecture, build order, dev commands, conventions, and key files.

2. Read the package-specific `AGENTS.md` for the area you're touching:

   | If the task touches… | Read |
   |---|---|
   | `core/` | `core/AGENTS.md` |
   | `map/` | `map/AGENTS.md` |
   | `services/` | `services/AGENTS.md` |
   | `examples/` | `examples/AGENTS.md` (and `examples/E2E_TESTING.md` for test work) |
   | `map-integration-tests/` | `map-integration-tests/AGENTS.md` |
   | `plugins/` (any) | `plugins/AGENTS.md` |
   | `plugins/agent-toolkit/` | `plugins/agent-toolkit/AGENTS.md` + `plugins/agent-toolkit/ENGINEERING-GUIDELINES.md` |
   | `plugins/viewport-places/` | `plugins/AGENTS.md` (no dedicated AGENTS.md; see `src/viewportPlaces.ts`) |
   | `plugins/landmarks-3d/` | `plugins/AGENTS.md` (no dedicated AGENTS.md; see `src/Landmarks3D.ts`) |
   | `shared-configs/` | `shared-configs/AGENTS.md` |
   | `documentation/` | `documentation/AGENTS.md` |
   | `documentation/docs-portal/` | `documentation/docs-portal/AGENTS.md` (guide writing with `SDKGuideLiveCodingExample`) |

   If the area is unclear, read all package-level `AGENTS.md` files before acting.

3. Before you write code, silently confirm you're in **contributor mode** with these easy-to-violate rules top-of-mind:

   - **Biome** for formatting/linting (not ESLint or Prettier). Run `pnpm lint` from root.
   - **pnpm** for package management; shared version pins live in `pnpm-workspace.yaml` under `catalog:`.
   - **Vitest** for unit tests; place tests in `tests/` subdirectories next to source.
   - **Strict TypeScript** — no `any`, no unnecessary casts.
   - **Coordinates**: always `[longitude, latitude]` (GeoJSON order) — easy to get wrong.
   - **Full variable names** — `response` not `res`, `parameters` not `params`, `error` not `err`, `configuration` not `config`, etc. (full list in root `AGENTS.md`).
   - **Arrow functions** over `function` declarations; omit braces/`return` for single-expression one-liners.
   - **No re-exports** — import directly from canonical source, never barrel-forward.
   - **Blank line after single-line `if`** — Biome does not enforce; apply manually.
   - **Map modules**: get instances via `await SomeModule.get(map)`, never `new SomeModule()`.
   - **Tool `execute`** in plugins must catch and return `{ error: string }`, never throw.
   - **Build order is strict**: `core` → `services` + `map`. Never import `map` from `services` or vice versa.
   - **Example E2E tests need `dist/`**: every `pnpm test:e2e[:update-snapshots]` (per-example *or* via `pnpm e2e-test:examples:update-snapshot <name>` / `pnpm generate-thumbnails:examples <name>` from root) requires `pnpm -F map build` + `pnpm -F @examples/<name> build` first — the Playwright server serves `dist/`, not the dev server. Skipping the build silently uses stale assets.
   - **New examples** must ship both `e2e-tests/snapshots/upon-load.png` (from `pnpm test:e2e:update-snapshots`) and `content/thumbnail.png` (derived via `pnpm generate-thumbnails:examples <name>`). Commit both.

## After every change

Always run both of these from the repo root after editing any source file, before reporting the task as complete:

```sh
pnpm lint:fix
pnpm format:fix
```

`lint:fix` runs Biome's check+lint with `--write`; `format:fix` runs Biome's formatter with `--write`. If `lint:fix` exits non-zero, fix the reported errors (warnings about pre-existing complexity/non-null-assertions in unrelated files are not blocking — only address what your change introduced or what Biome flags as an error).

## Cross-file consistency check (before pushing)

Most automated review nags come from references that drift between code, exports, tests, and docs. Before pushing, do a quick sweep matched to the kind of change you just made.

**Renamed or removed a public symbol** — start with `git grep -l '<oldName>'` from the repo root, then walk the hits across:
- the package's own `src/**` (registries, barrels, schemas, tests, mocks, fixtures)
- `examples/**` (entry points, hooks, eval cases, tests, snapshots)
- `documentation/docs-portal/guides/**` — both `navigation.yml` and every `.mdx` under the affected guide
- `.claude/skills/**` — skill descriptions list trigger keywords by symbol name and go stale silently

Replace every hit. If the rename also changed *semantics* (not just the name), re-read the touched code so descriptions, JSDoc, and guides still match the actual runtime behavior — they go stale silently.

**Changed a public type shape (default generic, exported interface, output schema)** — also:
- update the JSDoc `@typeParam` / property docs to match the actual default and shape (a common review nag is "JSDoc says X but signature says Y")
- decide whether downstream consumers need a deprecated alias or a major-version bump (see `.release-please-manifest.json`)

**Added external-resource fetching** — confirm bounded handling: explicit protocol allowlist, `AbortController` timeout, streamed size cap. Don't trust `new URL` alone.

**Package-specific extras** — when a package's own `AGENTS.md` lists "after adding X, also touch Y" rules (e.g. `plugins/agent-toolkit/AGENTS.md` for new state slices or registered tools), follow those as well. The root-level checks above don't replace them.

## When to branch off this skill

- Building an SDK *consumer* app (not editing SDK source) → use the `tomtom-maps-sdk-js` skill instead.
- Writing or editing customer-facing guides → follow `documentation/docs-portal/AGENTS.md`.
- Working on the agent-toolkit plugin → `ENGINEERING-GUIDELINES.md` is required reading before touching tools, state, or system prompts.