Een witte lege pagina in je webapp oplossen

Een witte lege pagina betekent bijna altijd een van twee dingen: het JavaScript van de app crashte voordat er iets werd getekend, of het JavaScript is helemaal niet geladen. Open de browserconsole (klik met rechts → Inspecteren → Console), lees de eerste rode fout, en controleer daarna het tabblad Netwerk op bestanden die niet konden worden geladen. De meeste oorzaken zijn een ontbrekende omgevingsvariabele, een verkeerd basispad, een build die niet klaar is, of een crash in één component.

Deze gids gaat over single-page apps gebouwd met React, Vue of vergelijkbare frameworks (inclusief apps van AI-bouwers), waar witte pagina’s het vaakst voorkomen.

Waarom de pagina wit is

Een moderne single-page app (SPA) stuurt de browser een bijna lege HTML-pagina, ongeveer zo:

<body>
  <div id="root"></div>
  <script type="module" src="/assets/index-a1b2c3.js"></script>
</body>

Daarna bouwt JavaScript de hele pagina op binnen die lege div. Als het script niet laadt, of een fout gooit voordat het rendert, blijft de div leeg en zie je wit. De pagina is niet op een zichtbare manier “kapot”; ze is simpelweg nooit getekend.

Daarom begint de oplossing altijd in de ontwikkelaarstools, niet in de pagina zelf.

Stap 1: lees de console

Open de ontwikkelaarstools: klik met rechts op de pagina en kies Inspecteren, of druk op F12 (Cmd+Option+I op een Mac). Ga naar het tabblad Console en laad de pagina opnieuw.

Kijk naar de eerste rode fout; latere zijn vaak bijwerkingen. Wat er staat, wijst naar de oorzaak:

Kopieer de volledige foutmelding, inclusief de bestandsnaam en het regelnummer. Als je een AI-bouwer gebruikt, plak het dan meteen in de chat.

Stap 2: controleer of de bestanden zijn geladen

Open het tabblad Netwerk, vink Cache uitschakelen aan en laad opnieuw. Kijk naar de verzoeken voor .js- en .css-bestanden.

• Status 404 bij een JavaScript-bestand: de pagina vraagt om een bestand dat niet op de server staat.
• Status 200 maar het type is text/html: de server gaf een pagina terug (vaak index.html zelf, door een SPA-fallback) in plaats van het script. Dezelfde basisoorzaak: het bestand staat niet waar de pagina het verwacht.

Veelvoorkomende redenen:

Verkeerd basispad. Als de app wordt geserveerd vanuit een submap, zoals voorbeeld.nl/app/, maar is gebouwd om bestanden te laden vanaf /assets/..., missen alle scriptverzoeken. In Vite is dit de base-optie in vite.config; in Create React App het veld homepage; in Next.js basePath. Het moet overeenkomen met waar de app daadwerkelijk wordt geserveerd.

Verouderde index.html. Buildtools geven bestanden namen met een content-hash, zoals index-a1b2c3.js. Na een nieuwe deployment is het oude bestand weg. Als een browser of CDN nog de oude index.html in de cache heeft, vraagt die om het oude bestand en krijgt niets. Een harde refresh (Cmd+Shift+R of Ctrl+Shift+R) bevestigt dit. De structurele oplossing is index.html serveren met een korte of geen cache-header, terwijl gehashte bestanden lang worden gecachet.

De build is niet af of niet gedeployd. Als de build mislukte, serveert de host misschien een oude of lege outputmap. Controleer het buildlog op fouten.

De verkeerde map is gepubliceerd. De host moet de buildoutput serveren (meestal dist of build), niet de bronmap van het project. De bronmap geeft een index.html die naar /src/main.tsx verwijst, en dat kan een browser niet uitvoeren.

Stap 3: controleer de omgevingsvariabelen

Frontend-apps lezen vaak instellingen zoals een API-URL of een publieke sleutel op buildtijd. Als een variabele op de live build ontbreekt, gooit code zoals createClient(undefined, undefined) meteen een fout en wordt de pagina wit.

Dingen om te weten:

• In Vite zijn alleen variabelen met het voorvoegsel VITE_ beschikbaar in browsercode, uitgelezen als import.meta.env.VITE_NAAM. In Create React App is dat REACT_APP_; in Next.js NEXT_PUBLIC_.
• Deze waarden worden ingebakken tijdens de build. Een variabele toevoegen na de build doet niets tot je opnieuw bouwt en deployt.
• De preview of je lokale machine heeft misschien een .env-bestand dat de productiebuild niet heeft. Stel dezelfde variabelen in op de host.
• Alles met deze voorvoegsels belandt in publiek JavaScript. Zet alleen publieke waarden erin, nooit geheime sleutels.

Een snelle test: zoek in de consolefout naar undefined vlak bij een instellingsnaam, of vraag:

De gepubliceerde app toont een lege pagina. Geef een lijst van elke omgevingsvariabele die de frontend leest, controleer welke ontbreken of leeg zijn in de live build, en laat de app een duidelijke foutmelding tonen in plaats van een lege pagina als er een ontbreekt.

Stap 4: los de crash op

Als de console een gewone JavaScript-fout toont, crashte de code tijdens het renderen. Typische oorzaken in met AI gebouwde apps:

• Data nog niet geladen. Een component leest user.name voordat user is binnengekomen. De oplossing is een laadstatus, of optional chaining (user?.name).
• Lege data. Een nieuw account heeft geen records, en de code gaat ervan uit dat de lijst minstens één item bevat.
• Onverwachte datavorm. Een API gaf een foutobject terug in plaats van de lijst die de code verwachtte.
• Een ontbrekende import nadat een bestand is hernoemd of verplaatst.
• Een browser-only API tijdens server-side rendering, zoals window of localStorage in een Next.js-servercomponent.

Geef de AI de volledige fout, de pagina, en met welk account je was ingelogd:

De Dashboard-pagina is leeg voor nieuwe gebruikers. Console: TypeError: Cannot read properties of undefined (reading 'map') bij ProjectList.tsx:18. Het werkt voor mijn account, dat projecten heeft. Pas het aan zodat een leeg account “Nog geen projecten” toont, en controleer een nieuw account in de preview.

Stap 5: voeg een error boundary toe

In React kan één crashende component de hele app uit de boom halen, waardoor een kleine bug een volledig lege pagina geeft. Een error boundary is een component die renderfouten eronder vangt en in plaats daarvan een terugvalweergave toont.

Voeg een error boundary toe rond de belangrijkste routes die “Er is iets misgegaan” toont met een knop Opnieuw laden, en die de fout naar de console logt. Houd de header en navigatie buiten de boundary, zodat ze blijven renderen.

Het lost de bug niet op, maar bezoekers zien een bericht in plaats van een leeg scherm, en jij ziet waar het misging.

Stap 6: geen fouten, toch leeg

Als de console schoon is en de scripts laden:

• Controleer het tabblad Elementen. Staat er inhoud in <div id="root">? Dan rendert het, maar is het onzichtbaar: witte tekst op wit, opacity: 0, display: none, of een element op volledig scherm dat erover ligt.
• Controleer de router. Als geen route past bij de huidige URL en er geen “niet gevonden”-route is, tekenen sommige routers niets. Voeg een catch-all-route toe die een 404-pagina toont.
• Controleer het koppelpunt. De code moet in een element worden gekoppeld dat bestaat. Als index.html id="app" heeft en de code naar root zoekt, verschijnt er niets (en React logt meestal een fout).
• Controleer een browserextensie. Probeer een privévenster. Advertentieblokkers blokkeren soms scripts met namen zoals analytics of ads.

Leeg alleen na het verversen van een pagina?

Als de startpagina werkt maar het verversen van /dashboard een lege pagina of een 404 geeft, weet de server niet dat hij index.html moet sturen voor app-routes. Dat is een probleem met de fallback voor routing, behandeld in 404-fouten na deployen oplossen.

Veelgemaakte fouten

• De laatste fout lezen in plaats van de eerste. De eerste rode regel is meestal de oorzaak.
• Omgevingsvariabelen instellen zonder opnieuw te bouwen. Variabelen aan de frontend worden op buildtijd vastgelegd.
• Alleen testen met je eigen account. Crashes bij lege accounts zijn een van de meest voorkomende oorzaken van een lege pagina.
• Aannemen dat de deployment is gelukt. Controleer het buildlog voordat je de code gaat debuggen.
• De browsercache de schuld geven van alles. Een harde refresh sluit dat in seconden uit; als de pagina nog steeds leeg is, zit het ergens anders.

Lege pagina’s in Mythex

Als de Preview leeg is, controleer dan eerst of de app draait (open Code → terminal). Vraag Mythex daarna de juiste server te starten, klik op Vernieuwen in de previewwerkbalk, of gebruik /fix. Voor een lege gepubliceerde URL raadt de documentatie aan een minuut te wachten en hard te verversen, te bevestigen dat omgevingsvariabelen en de database waren ingesteld voordat je publiceerde, en je hostingruimte te controleren. Houd er rekening mee dat een gepubliceerde app een momentopname is: na een fix publiceer je opnieuw. Heeft een wijziging het veroorzaakt, dan zet Terugzetten naar dit punt op het laatste goede antwoord het project terug. Zie Problemen oplossen en Publicatie-problemen oplossen in de documentatie, en onze algemene gids over het debuggen van een met AI gebouwde app.

Checklist witte pagina

• De eerste rode fout in de Console gelezen
• Het tabblad Netwerk gecontroleerd op .js- of .css-bestanden die 404 geven of HTML teruggeven
• Basispad klopt met waar de app wordt geserveerd
• Build is klaar, en de buildoutputmap is wat wordt gepubliceerd
• Alle omgevingsvariabelen aan de frontend ingesteld op de live build, daarna opnieuw gebouwd
• Crash opgelost, ook voor lege en nieuwe accounts
• Error boundary aanwezig zodat toekomstige crashes een bericht tonen
• Catch-all-route voor onbekende URL’s
• Getest na een harde refresh en in een privévenster

Veelgestelde vragen