syntaxerror: cannot use import statement outside a module — Vlaamse gids voor developers die ES-modules willen beheersen
SyntaxError: Cannot Use Import Statement Outside a Module — wat betekent dit precies?
De foutmelding syntaxerror: cannot use import statement outside a module verschijnt wanneer JavaScript probeert een import-instructie uit te voeren in een context die niet als een module wordt beschouwd. In Vlaamse termen: de code wordt geladen op een manier die niet toestaat om functies of objecten uit een ander bestand te halen via import. Dit gebeurt vaak bij Node.js-projecten, bij eenvoudige HTML-pagina’s zonder script type=”module”, of wanneer je bestanden mixt zonder de juiste moduleconfiguratie. Een correcte opname van deze fout zorgt ervoor dat je snel kunt identificeren waar de module-omgang niet klopt en welke stap nodig is om de code op de juiste manier te laten samenwerken.
Waarom komt de fout syntaxerror: cannot use import statement outside a module vaak voor?
De fout ontstaat wanneer een import-instructie wordt uitgevoerd in een context die niet als module wordt geladen. ES-modules introduceren een strengere scheiding tussen bestanden en laten expliciet toe dat import en export worden gebruikt. Als je bijvoorbeeld een bestand index.js hebt dat in een browser of in Node.js zonder module-context wordt geladen, zal de import-instructie niet werken en krijg je de foutmelding syntaxerror: cannot use import statement outside a module. In praktijk omvat dit enkele populaire scenario’s:
- Een browserpagina die een JavaScript-bestand laadt zonder
<script type="module">tag. - Een Node.js-project waarin
typeinpackage.jsonontbreekt of niet opmodulestaat ingesteld. - Een combinatie van bestanden waarin sommige scripts als module worden geladen maar andere als standaard scripts, waardoor imports in de verkeerde context terechtkomen.
Oorzaken en concrete voorbeelden van de fout
Om de fout te begrijpen, is het handig om de verschillende oorzaken te schetsen en hoe ze eruitzien in de praktijk. Hieronder staan enkele veelvoorkomende voorbeelden die leiden tot syntaxerror: cannot use import statement outside a module:
1) Importeren in een script dat niet als module wordt geladen in de browser
In een HTML-pagina gebruik je import alleen binnen scripts die als modules zijn gemarkeerd. Als je een standaard <script> tag gebruikt, kun je geen importeren. Dit leidt vaak tot de foutmelding syntaxerror: cannot use import statement outside a module in ontwikkelingsomgevingen die JavaScript als module willen beschouwen.
<!-- Foutieve benadering -->
<script>
import { helper } from './helper.js';
console.log(helper());
</script>
<!-- Juiste benadering -->
<script type="module">
import { helper } from './helper.js';
console.log(helper());
</script>
2) Importeren in een Node.js-project zonder moduletype
In Node.js werkt import alleen in omgevingen die als ES-module zijn gemarkeerd. Standaard draait Node echter nog vaak in CommonJS-modus. Dit veroorzaakt syntaxerror: cannot use import statement outside a module wanneer je een bestand probeert te laden met import zonder de juiste module-instelling.
// package.json zonder type: "module"
{
"name": "voorbeeld",
"version": "1.0.0"
}
// index.js in een non-module-context
import { something } from './module.js';
3) Mengwerk in bestanden met verschillende module-contexts
Wanneer sommige bestanden als modules worden geladen en andere niet, kan een fout zoals syntaxerror: cannot use import statement outside a module ontstaan. Het is belangrijk om consistent te blijven in de hele applicatie.
Hoe adresseer je de fout: stappenplan (met duidelijke oplossing)
De oplossing draait doorgaans om het expliciet maken dat de bestanden modules zijn. Hieronder vind je een praktisch stappenplan om syntaxerror: cannot use import statement outside a module te verwijderen en toekomstbestendig te maken.
- Maak van je Node.js-project ES-modules door type: “module” toe te voegen aan package.json, of gebruik de .mjs-extensie voor bestanden die ES-modules zijn. Dit zorgt ervoor dat
importcorrect wordt herkend. - Laad browserbestanden als modules. Gebruik
<script type="module">in je HTML om ervoor te zorgen dat imports werken in de browser. - Voorkom gemengde contexten. Houd consistente module-structuur door alle relevante bestanden als modules te markeren.
- Gebruik dynamische import als je slechts in bepaalde omstandigheden modules wilt laden. Dit kan ook helpen om situaties waarin de module-context niet obvious is te vermijden.
- Overweeg een transpiler/bundler. Tools zoals Babel, Webpack, Rollup of Vite kunnen helpen bij compatibiliteit en bundling, zodat imports in verschillende omgevingen soepel werken.
Concrete codevoorbeelden om syntaxerror: cannot use import statement outside a module te voorkomen
Hieronder vind je praktische voorbeelden die laten zien hoe je het probleem oplost en waarom de bovenstaande stappen nodig zijn.
Goede browserconfiguratie
In HTML-loaders gebruik je altijd modules. Voor een simpele pagina:
<!DOCTYPE html>
<html>
<head></head>
<body>
<script type="module" src="app.js"></script>
</body>
</html>
Node.js: modules inschakelen via package.json
Om Node.js te laten weten dat je ES-modules gebruikt, voeg type: “module” toe aan package.json:
{
"name": "voorbeeld",
"version": "1.0.0",
"type": "module"
}
// app.js (een ES-module)
import { greet } from './greet.js';
console.log(greet('Wereld'));
CommonJS alternatief: gebruik require
Als je liever bij CommonJS blijft, kun je import vervangen door require:
// app.cjs of app.js afhankelijk van configuratie
const { greet } = require('./greet.cjs');
console.log(greet('Wereld'));
Dynamic import als flexibele oplossing
Voor scenarios waarbij modules alleen onder bepaalde omstandigheden geladen moeten worden, kun je dynamic import gebruiken:
// Dynamische import in een ES-module
if (condition) {
import('./lazy.js')
.then(module => {
module.doSomething();
})
.catch(err => console.error(err));
}
Veelvoorkomende fouten vermijden: best practices voor ES-modules
Een zorgvuldige aanpak helpt om syntaxerror: cannot use import statement outside a module in de toekomst te voorkomen. Hier zijn een paar praktische aanbevelingen:
- Selctie 1: consistentie in module-context. Houd alle relevante bestanden als modules tenzij er een specifieke reden is om niet-modulair te blijven.
- Selctie 2: duidelijke projectstructuur. Houd modules logisch gegroepeerd en vermijd “single-script”-achtige pagina’s die modules proberen te laden zonder type=”module”.
- Selctie 3: testomgevingen. Gebruik tests/CI die ook de ES-module-configuratie controleren, zodat een fout snel opgespoord wordt voordat production build draait.
- Selctie 4: bundling en transpilatie. Gebruik moderne tooling om code te bundelen en foutmeldingen te verkorten; zo kun je imports centraal controleren.
Veelgestelde vragen (FAQ)
Hieronder beantwoord ik enkele veelvoorkomende vragen rond syntaxerror: cannot use import statement outside a module:
Kan ik importeren zonder type: “module” in Node.js?
Ja, maar dan ben je beperkt tot CommonJS-scripts die require gebruiken. Voor gebruik van import moet je modulemodus inschakelen via type": "module" in package.json of door de bestandsextensie te veranderen naar .mjs.
Wat als ik toch per bestand wil bepalen of het als module draait?
Dynamic import biedt flexibiliteit om op runtime-niveau te beslissen of een module moet worden geladen. Dit kan handig zijn in complexe systemen waar modules pas later in de flow nodig zijn.
Zijn er performance-momenten waar ik op moet letten?
ES-modules hebben een certain overhead bij het laden en parsen, zeker in browseromgevingen. Moderne bundlers verminderen dit door te chunk-en en lazy-loading te optimaliseren. Gebruik lazy loading verstandig om laadtijden te verbeteren zonder functionaliteit te schaden.
Samenvatting: wat leerde je over syntaxerror: cannot use import statement outside a module?
De kernboodschap is eenvoudig maar krachtig: imports werken alleen binnen een module-context. Door expliciet te definiëren welke bestanden modules zijn, kun je syntaxerror: cannot use import statement outside a module simpelweg voorkomen. In de praktijk betekent dit het toevoegen van type: "module" in Node.js-projecten of het gebruik van script type="module" in HTML-pagina’s. Mocht je toch onvermijdelijk in een gemengd omgeving belanden, biedt dynamische imports en bundlers een veilige oplossing om de fout te omzeilen en later opnieuw op te bouwen.
Grote samenspanning: hoe dit in de praktijk te plannen voor jouw project
Als je dit nut ziet, plan je migratie naar ES-modules stap voor stap. Begin met één kritisch onderdeel van de applicatie en schakel de module-context in. Voer tests uit en controleer of alle import/export-relaties nog kloppen. Door consistentie te behouden in je module-structuur, kun je op lange termijn meerdere projecten soepel laten draaien zonder steeds te stuiten op syntaxerror: cannot use import statement outside a module.
Conclusie: houd de regels van ES-modules vast
De fout syntaxerror: cannot use import statement outside a module is geen mysterie als je de basisprincipes van ES-modules kent en de context waarin je code draait strikt beheert. Door de juiste configuratie, consistente module-context en slimme tooling te gebruiken, zorg je ervoor dat imports altijd soepel verlopen. Of je nu werkt aan een kleine frontend-app of een grote backend-service, een solide module-strategie betaalt zichzelf terug in minder debugging-tijd en een betrouwbaardere codebasis.