Web App Startpunt

• Versie: 2.0.3
• Meest recente update: 10-08-2026

Welkom bij het Web App Startpunt, een major update van wat voorheen de DPC Interactieve Infographic Sandbox heette. De sandbox-insteek is losgelaten en vervangen door een 'starter project' met daarin verschillende (stijl)elementen en features die het de maker gemakkelijker maken om een web app te bouwen die naadloos aansluit op de site waarop deze uiteindelijk geplaatst wordt.

Vereisten

De meeste elementen van dit startpunt zijn slechts suggesties, maar een aantal zaken is vereist voor het bouwen en correct aanleveren van een web app voor het PRO-platform:

• De web app moet gebouwd zijn in React.
• De web app moet werken in / gebruikmaken van de Shadow DOM.
• De web app moet voldoen aan de eisen voor toegankelijkheid.
• De web app mag geen gebruikmaken van het Rijksoverheid iconenfont.
• De web app moet werken in de PRO-preview-tool.
• Afhankelijkheden mogen geen bekende kwetsbaarheden bevatten. Dit controleer je met het commando pnpm audit. De verantwoordelijkheid voor het bijhouden van afhankelijkheden en het voorkomen van kwetsbaarheden daarin (zowel voor als na plaatsing) ligt en blijft bij de indiener van de web app. Het staat DPC vrij om bij kwetsbaarheden de web app offline te halen.

Toegankelijkheid

Houdt met het ontwikkelen van de web app al rekening met het feit dat de web app toegankelijk moet zijn volgens de specificaties van de WCAG. Enkele aandachtspunten zijn:

• Kleurcontrast: Er zijn eisen voor het contrast van tekst op een kleurvlak. Dit is onder andere te controleren met de APCA contrastchecker.
• Leesbare tekst: Houdt rekening met bezoekers die vertrouwen op screenreaders. Dit houdt in dat teksten in afbeeldingen niet toegankelijk zijn. Het toevoegen van een ALT-tekst is niet altijd voldoende.
• Bediening: Veel bezoekers en assistive hulpmiddelen vertrouwen op navigatie met een toetsenbord. Zorg ervoor dat alle klikbare elementen ook te bedienen zijn met een toetsenbord. Dit houdt in dat je geen niet-klikbare elementen moet gebruiken en deze vervolgens met JavaScript wel klikbaar te maken.
• Dynamische content: Zodra inhoud van de web app dynamisch wisselt (popup, sliders etc.) is dit niet voor alle gebruikers waarneembaar. Je zult met JavaScript en ARIA-tags moeten zorgen dat ook gebruikers met bijvoorbeeld screenreaders of braillelezers op de hoogte gebracht worden van de nieuwe informatie op de pagina.
• Zorg ook voor een leesbaar alternatief voor iconen en buttons met pijlen of kruisjes.
• Meer informatie is te vinden op digitoegankelijk.nl en w3.org.

Opstarten

Er wordt gebruikgemaakt van Turborepo. Om een testomgeving op te starten, voer je de volgende stappen uit:

• Maak gebruik van Node.js en pnpm 11.x.
• Gebruik in de root pnpm install om alle packages te installeren.
• Dupliceer in packages/webapp het bestand .env.sample en hernoem dit naar .env.
• Vul een VITE_WEB_APP_NAME in. Deze zal gebruikt worden om je zip automatisch een naam te geven.
• Vul het juiste VITE_WEB_APP_ID in.
• Gebruik in de root pnpm dev om alle omgevingen op te starten.
• De lokale omgeving is nu te gebruiken via http://localhost:5174.
• Ontwikkel je web app in de map packages/webapp.

Up-to-date blijven

Het Web App Startpunt wordt continu geüpdatet. Dit betekent dat je de laatste wijzigingen van het Startpunt in je huidige project moet mergen. Dit doen we door middel van een Git upstream repository. Dit is een extra remote die parallel loopt met je eigen remote.

Zorg er altijd voor dat de hoofdbranches van de twee remotes gelijk lopen. Dit doe je als volgt:

1. Voeg de nieuwe remote toe met: git remote add upstream <UPSTREAM_GIT_REPO_URL>
2. Merge de upstream/main in de branch waar je op dit moment in werkt: git merge upstream/main --allow-unrelated-histories Let op: Bestanden met overlappende namen zullen nu een conflict geven. Dit hoef je maar één keer op te lossen. Daarna zijn de branches gesynced.

Check voor updates altijd eerst via git fetch upstream. Daarna kun je deze updates mergen in je huidige branch met git merge upstream/main.

Migreren van V1 naar V2

Als je al een werkende web app hebt en je wilt gebruikmaken van de nieuwe versie, volg dan deze stappen:

• Gebruik de V2-versie als basis.
• Vervang de src folder in packages/webapp met de src van de oude web app.
• BELANGRIJK: Laat de folder vite-plugins in de src folder staan!
• Vervang de public folder in packages/webapp met de public van de oude web app.
• Verwijder de dist folder in packages/webapp.
• Start je project met pnpm dev in de root van je project.

Opleveren

Je levert de web app op door een zip-bestand aan te leveren bij DPC Support. Deze zip kun je automatisch genereren door het commando pnpm zip uit te voeren. In de root van het project zal nu een zip zijn aangemaakt die webapp@v2.x.zip heet. Deze kan je gebruiken om op te sturen.

Werking

Web App ID

In dit project is een variabele (VITE_WEB_APP_ID) opgenomen in het bestand packages/webapp/.env. Verander dit naar een uniek ID voor jouw web app. Dit ID wordt voor twee dingen gebruikt:

1. Hiermee identificeren we de web app om versies te beheren.
2. Dit zorgt ervoor dat de web app in de juiste container geladen wordt. Dit gebeurt op vier plekken: (packages/webapp/src/vite-plugins/linkBuildToPreviewTool.ts, packages/webapp/index.html, packages/webapp/src/Main.tsx en packages/webapp/postcss.config.js).

Fonts

Omdat webfonts niet direct in de Shadow DOM geëmbed kunnen worden, is het alleen mogelijk om gebruik te maken van webfonts die al door de omringende (host)site zijn ingeladen. In dit project zijn de vier fonts die op de verschillende PRO-sites gebruikt worden meegeleverd, maar deze worden slechts ingezet voor preview-doeleinden. In de uiteindelijke productie-output van dit project worden de fonts daarom niet meegenomen.

De standaard lettergrootte op het huidige PRO-platform is 10px. Na de migratie wordt dit de standaard 16px. Houd hier dus rekening mee wanneer er gebruik wordt gemaakt van relatieve lettergroottes. Zet in dat geval bijvoorbeeld de lettergrootte op de .web-apps-container class en gebruik vervolgens em.

Assets

Assets moeten worden toegevoegd door middel van de functie createAssetPath(). De bestandslocatie in development is namelijk anders dan op het PRO-platform. Om assets op het platform te laten werken, moet de src-locatie gewrapt worden in createAssetPath().

In de CSS kunnen er dus ook geen absolute paden gebruikt worden in een url() tag. In het startpunt zitten twee voorbeelden waarmee we laten zien hoe je iconen correct kunt gebruiken.

Naamgevingsconventies (Belangrijk)

Gebruik geen _ (underscore) in bestandsnamen. Maak in plaats daarvan gebruik van een - (koppelteken). De reden hiervoor is dat het CMS underscores vervangt door koppeltekens, waardoor bestanden anders niet correct worden uitgelezen.

Data sets

Door gebruik te maken van de data-set-attributen kun je data inladen uit bestanden die in het CMS zijn opgeslagen in de map webapp-data.

Er zijn maximaal vier data-set-attributen beschikbaar: data-set-1, data-set-2, data-set-3 en data-set-4.

Voor development kun je deze data sets aanpassen in pro-preview-tool/public/index.html, zodat je de functionaliteit lokaal kunt testen. In productie worden deze URL’s automatisch overschreven met de URL’s die verwijzen naar de daadwerkelijke bestanden in het CMS.

Voorbeeldstructuur

<div
    id="id-van-je-webapp"
    class="web-app-container"
    data-set-1="/binaries/webapp-demo/rocolors.csv"
    data-set-2=""
    data-set-3=""
    data-set-4=""
></div>

Uitlezen van datasets

Gebruik binnen je React-component de hook useDataSet() om toegang te krijgen tot de dataset-configuratie:

Voorbeeld in bestand: src/components/OnlineCommunicationColors.tsx

const { dataSets } = useDataSet();
const dataSet = dataSets?.["set-1"];

Stuurbestand

Een stuurbestand kan worden gebruikt als er meerdere webapps zijn die dezelfde data moeten gebruiken. In het CMS kan je een stuurbestand koppelen aan een webapp. Als dit bestand aangepast wordt in het CMS, dan wijzigt deze data in alle webapps die dit stuurbestand gebruiken.

Voor development kun je deze data set aanpassen in pro-preview-tool/public/index.html, zodat je de functionaliteit lokaal kunt testen.

In productie wordt deze URL automatisch overschreven met de URL die verwijst naar het bestand in het CMS.

Voorbeeldstructuur

<div id="id-van-je-webapp" class="web-app-container" data-control-file="/binaries/webapp-demo/control-file.json"></div>

Uitlezen van een stuurbestand

Gebruik binnen je React-component de hook useDataSet() om toegang te krijgen tot de dataset-configuratie:

Voorbeeld in bestand: src/components/OnlineCommunicationColorsJson.tsx

const { dataSets } = useDataSet();
const stuurbestand = dataSets?.["controlFile"];

Kwaliteit

Om de kans op issues later in het proces te verkleinen, is het aan te raden om met degelijke controle tools te werken:

Visual Studio Code + extensies

• VS Code code editor
• ESLint extensie
• webhint extensie
• axe Accessibility Linter extensie
• Prettier extensie