---
title: "Debug-id op component-root"
status: active
audience: [ai-agent, contributor]
language: nl
last_updated: 2026-05-09
when_to_read: "Wanneer je een named-component aanmaakt of aanpast."
---

# Patroon: Debug-id op component-root

## Regel: named-component boundary

Elk named-component plaatst `data-debug-id` en `data-debug-label` via de
`debugProps`-helper op zijn root JSX-element. Zes concrete regels:

1. **Import** `debugProps` uit `@/lib/debug` — geen inline attribuut schrijven.
2. **Spread** het resultaat op het root element: `{...debugProps(id, component, file)}`.
3. **`id`** is kebab-case van de componentnaam, bijv. `sprint-board`.
4. **`component`** is de PascalCase naam zoals die geëxporteerd wordt, bijv. `SprintBoard`.
5. **`file`** is het relatieve pad vanaf de repo-root, bijv. `components/sprint/sprint-board.tsx`.
6. **Root = het buitenste JSX-element** dat de component rendert — niet een wrapper div die je extra toevoegt.

In productie (`NODE_ENV=production`) retourneert `debugProps` een leeg object `{}`
zodat er geen debug-attributen in de gebundelde HTML staan.

## Helper-voorbeeld

```tsx
import { debugProps } from '@/lib/debug'

export function SprintBoard({ ... }: SprintBoardProps) {
  return (
    <div
      className="..."
      {...debugProps('sprint-board', 'SprintBoard', 'components/sprint/sprint-board.tsx')}
    >
      {/* inhoud */}
    </div>
  )
}
```

## Skip-criteria

Voeg **geen** `debugProps` toe aan:

| Categorie | Reden |
|---|---|
| `components/ui/*` | shadcn-primitives — ongebrand, niet onze componenten |
| Bridges / mounts | Niet-renderende wrappers zoals `notifications-bridge`, `realtime-bridge`, `sync-active-sprint-cookie` |
| Hooks-only files | Files die alleen hooks exporteren en niets renderen |

## Motivatie: geen build-time injectie van pad

Een alternatief is het bestandspad automatisch injecteren via een Babel/SWC-plugin
of een ESLint-codefixin. Dit is bewust **niet** gekozen omdat:

- de plugin afhankelijk wordt van de build-toolchain-configuratie (Next.js, Turbopack),
- bij rename/move van een bestand de injectie verouderd raakt zonder dat de compiler waarschuwt,
- expliciete argumenten in de broncode reviewbaar en grep-baar zijn.

Het handmatig meegeven van `id`, `component` en `file` maakt de intentie zichtbaar
en voorkomt verborgen afhankelijkheden.