← Terug naar tutorials

Hoe je React dev-server snel werkend krijgt (7 fixes)

reactdevelopment serverfrontendnode.jsnpmvitecreate react appdebuggingport conflictdependencies

React-app start niet? 7 veelvoorkomende fixes voor je development server

Als je React-app niet wil starten, voelt dat vaak alsof “alles stuk” is—maar in de praktijk gaat het meestal om een handvol terugkerende oorzaken: verkeerde Node-versie, kapotte node_modules, poortconflicten, environment-variabelen, bundler-caches, of een dependency die nét niet matcht. In deze tutorial krijg je 7 veelvoorkomende fixes met diepe uitleg, echte commando’s, en een aanpak waarmee je systematisch kunt debuggen (in plaats van willekeurig dingen te proberen).

Context: de voorbeelden zijn toepasbaar op projecten met Create React App (CRA), Vite, Next.js (dev server), en algemene React setups met Webpack/Rollup. Waar iets tool-specifiek is, staat het erbij.

Voor je begint: een snelle diagnose-checklist

Voordat je aan “fixes” begint, wil je weten wat er precies faalt. Verzamel deze info:

  1. Welke tool gebruik je?
    • CRA: react-scripts start
    • Vite: vite / npm run dev
    • Next.js: next dev
  2. Wat is de exacte foutmelding? Kopieer de volledige output.
  3. Welke Node/NPM/Yarn/PNPM versies?
  4. Op welk OS? (Windows/macOS/Linux)
  5. Start hij helemaal niet, of crasht hij na compile?
    • “Command not found” → tooling/installs
    • “Module not found” → dependencies/resolving
    • “EADDRINUSE” → poort bezet
    • “ERR_OSSL_EVP_UNSUPPORTED” → Node/OpenSSL mismatch

Handige commando’s:

node -v
npm -v
yarn -v
pnpm -v
git status

En check je scripts:

cat package.json

Fix 1 — Verkeerde Node.js-versie (of OpenSSL-problemen)

Symptomen

Waarom dit gebeurt

Node.js verandert door de jaren heen API’s, defaults en security-instellingen. Een bekende breuklijn is Node 17+ met OpenSSL 3, waar oudere Webpack-versies op stuklopen. Ook kunnen dependencies in je lockfile gebouwd zijn voor een andere Node-versie.

Oplossing A: gebruik een Node version manager (aanrader)

macOS/Linux: nvm

# Installatie (voorbeeld)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Herstart je shell, dan:
nvm install 18
nvm use 18
node -v

Windows: nvm-windows Installeer nvm-windows en doe:

nvm install 18.20.2
nvm use 18.20.2
node -v

Kies een versie die past bij je stack:

Oplossing B: tijdelijke workaround voor OpenSSL (niet ideaal)

Als je moet draaien op Node 17+ met oude Webpack:

macOS/Linux

export NODE_OPTIONS=--openssl-legacy-provider
npm start

Windows PowerShell

setx NODE_OPTIONS "--openssl-legacy-provider"
npm start

Let op: dit is een workaround. Beter is upgraden naar een bundler/tooling die OpenSSL 3 ondersteunt (bijv. nieuwere Webpack of overstappen naar Vite).

Extra: zet je Node-versie vast in het project

Voeg in package.json:

{
  "engines": {
    "node": ">=18 <21"
  }
}

En (optioneel) een .nvmrc:

echo "18" > .nvmrc

Fix 2 — Kapotte install of “dependency hell” (node_modules + lockfile reset)

Symptomen

Waarom dit gebeurt

node_modules is een grote boom van packages. Als je:

…dan kan je dependency tree inconsistent worden. Je bundler resolve’t dan modules anders dan verwacht.

Oplossing: clean install (de “nucleaire” maar vaak juiste stap)

  1. Stop de dev server.

  2. Verwijder node_modules en lockfile(s):

macOS/Linux

rm -rf node_modules
rm -f package-lock.json yarn.lock pnpm-lock.yaml

Windows PowerShell

Remove-Item -Recurse -Force node_modules
Remove-Item -Force package-lock.json, yarn.lock, pnpm-lock.yaml
  1. Kies één package manager en installeer opnieuw:

npm

npm install
npm start

Yarn

yarn install
yarn start

pnpm

pnpm install
pnpm dev

Tip: gebruik npm ci in plaats van npm install (als je een lockfile hebt)

npm ci installeert exact wat in package-lock.json staat en faalt bij mismatch—ideaal voor reproducible builds:

npm ci
npm start

Diepere check: dubbele React-versies

Een klassieker: je hebt twee React versies in de dependency tree, wat kan leiden tot hooks-errors.

Check met npm:

npm ls react react-dom

Of met yarn:

yarn why react
yarn why react-dom

Als je meerdere versies ziet, los je dat vaak op door:

Fix 3 — Poort bezet (EADDRINUSE) of dev server bindt aan verkeerde host

Symptomen

Waarom dit gebeurt

Poort 3000/5173/8080 kan al bezet zijn door:

Oplossing A: vind en kill het proces

macOS/Linux (poort 3000)

lsof -i :3000
# voorbeeld output toont PID
kill -9 <PID>

Linux alternatief

ss -lptn 'sport = :3000'

Windows PowerShell

netstat -ano | findstr :3000
taskkill /PID <PID> /F

Oplossing B: start op een andere poort

CRA

PORT=3001 npm start

Windows PowerShell (CRA):

$env:PORT=3001; npm start

Vite

npm run dev -- --port 5174

Next.js

npm run dev -- -p 3001

Oplossing C: host binding issues (0.0.0.0 vs localhost)

Soms draait je server wel, maar is hij niet bereikbaar door een verkeerde host of IPv6/IPv4 mismatch.

CRA

HOST=127.0.0.1 npm start

Vite (vite.config.js)

export default {
  server: {
    host: "127.0.0.1"
  }
}

Fix 4 — Environment variabelen en .env problemen (CRA/Vite/Next verschillen)

Symptomen

Waarom dit gebeurt

Elke tool heeft eigen regels:

Ook belangrijk: .env wordt bij start ingelezen. Wijzig je .env? Dan moet je de server herstarten.

Oplossing A: check je prefixes en code

CRA

REACT_APP_API_URL=https://api.example.com

Gebruik:

const url = process.env.REACT_APP_API_URL;

Vite

VITE_API_URL=https://api.example.com

Gebruik:

const url = import.meta.env.VITE_API_URL;

Next.js

NEXT_PUBLIC_API_URL=https://api.example.com

Gebruik:

const url = process.env.NEXT_PUBLIC_API_URL;

Oplossing B: controleer welke .env geladen wordt

Veel setups ondersteunen .env, .env.local, .env.development, etc. Conflicten ontstaan als je dezelfde key in meerdere bestanden hebt.

Zoek alle definities:

# macOS/Linux
grep -R "API_URL" -n .env*

# Windows PowerShell
Select-String -Path .env* -Pattern "API_URL"

Oplossing C: voorkom dat je per ongeluk secrets in de client stopt

Alles wat je in client-side env stopt, kan in de browser bekeken worden. Zet secrets server-side (bij Next.js API routes of backend).

Fix 5 — TypeScript/Babel/ESM vs CJS mismatch (import/export errors)

Symptomen

Waarom dit gebeurt

De JavaScript module-wereld is verdeeld:

Sommige packages zijn ESM-only geworden. Als jouw tooling (of Node runtime) verwacht dat het CJS is, crasht het. Ook kan je type: "module" in package.json invloed hebben op hoe Node je config files interpreteert (bijv. webpack.config.js, vite.config.js, postcss.config.js).

Oplossing A: check "type": "module" in package.json

Als je dit hebt:

{
  "type": "module"
}

Dan moeten Node-run configbestanden vaak ook ESM zijn, of je moet ze hernoemen naar .cjs (CommonJS).

Voorbeeld: postcss.config.cjs:

module.exports = {
  plugins: {
    autoprefixer: {}
  }
};

Oplossing B: pas import aan of pin dependency

Als een dependency ESM-only is en jouw tool kan dat niet, kun je:

Voorbeeld pinnen met npm:

npm install some-lib@1.9.0

Oplossing C: TypeScript config check

Soms faalt de dev server door tsconfig.json module settings.

Controleer:

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "jsx": "react-jsx"
  }
}

Let op: moduleResolution: "Bundler" werkt goed met Vite/modern tooling, maar niet altijd met oudere setups. Voor CRA/oudere tooling is "Node" soms stabieler.

Fix 6 — Caches en build artifacts (Vite/Next/Webpack) die je moet legen

Symptomen

Waarom dit gebeurt

Bundlers en frameworks cachen agressief voor snelheid:

Als cache-inhoud niet meer matcht met je code/dependencies, krijg je spookbugs.

Oplossing: verwijder caches en start opnieuw

Algemeen (macOS/Linux)

rm -rf node_modules/.cache
rm -rf node_modules/.vite
rm -rf .next
rm -rf dist
rm -rf build
npm start

Vite specifiek

rm -rf node_modules/.vite
npm run dev

Next.js specifiek

rm -rf .next
npm run dev

Windows PowerShell

Remove-Item -Recurse -Force node_modules\.cache -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force node_modules\.vite -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force .next -ErrorAction SilentlyContinue
npm run dev

Extra: forceer een “schone” bundler run

Sommige tools hebben flags:

Vite

npm run dev -- --force

Fix 7 — Tooling scripts, PATH en “command not found” (react-scripts/vite/next ontbreekt)

Symptomen

Waarom dit gebeurt

Meestal een van deze:

Oplossing A: check scripts in package.json

Open package.json en kijk naar:

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  }
}

Dan moet je starten met:

npm run dev

CRA ziet er vaak zo uit:

{
  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build"
  }
}

Dan:

npm start

Oplossing B: installeer dependencies

npm install

En start opnieuw.

Oplossing C: zorg dat je in de juiste directory zit

Check:

pwd
ls

Je moet in de map staan waar package.json staat.

Oplossing D: gebruik npx voor lokale binaries (handig bij diagnose)

Als vite niet gevonden wordt, maar wel in node_modules staat:

npx vite --version
npx vite

Voor Next:

npx next dev

Als npx het ook niet vindt, is de dependency waarschijnlijk niet geïnstalleerd of staat niet in dependencies/devDependencies.

Systematische debug-aanpak (als de 7 fixes niet meteen werken)

Als je nog steeds vastzit, ga dan methodisch te werk:

1) Reproduceer met maximale logging

Veel tools geven extra output met environment flags.

Node warnings

node --trace-warnings node_modules/.bin/react-scripts start

npm verbose

npm run dev --loglevel verbose

2) Controleer de exacte error en zoek op de kernzin

Niet zoeken op je hele terminal-output, maar op de “kern”:

3) Minimaliseer: start met een kale install

4) Check of het project überhaupt compileert

Run build:

CRA

npm run build

Vite

npm run build

Next

npm run build

Als build faalt, is het niet alleen “dev server”; dan is het een echte compile/config/dependency issue.

Veelvoorkomende concrete foutmeldingen en wat ze betekenen

EADDRINUSE

Poort bezet → Fix 3.

ERR_OSSL_EVP_UNSUPPORTED

Node/OpenSSL mismatch → Fix 1.

Module not found: Can't resolve 'xyz'

Dependency ontbreekt of verkeerde import path → Fix 2 (clean install) en check import.

react-scripts: command not found

Dependencies niet geïnstalleerd of verkeerde map → Fix 7.

process is not defined (bij Vite)

Je gebruikt process.env in Vite; moet import.meta.env zijn → Fix 4.

Preventie: maak je dev-setup robuust

  1. Leg Node-versie vast met .nvmrc en engines.
  2. Gebruik één package manager per repo.
  3. Commit je lockfile (package-lock.json of yarn.lock of pnpm-lock.yaml).
  4. Documenteer startcommando’s in README.md.
  5. Houd tooling up-to-date (zeker bundlers), maar upgrade gecontroleerd.

Voorbeeld README snippet:

## Development

Vereist: Node 18

```bash
npm install
npm run dev

---

## Snelle “alles-in-één” reset (als laatste redmiddel)

Als je zeker weet dat je geen lokale wijzigingen kwijt raakt (of je hebt ze gecommit), kun je dit doen:

**macOS/Linux**
```bash
git clean -xfd
npm install
npm start

Windows PowerShell

git clean -xfd
npm install
npm start

git clean -xfd verwijdert ook untracked files (zoals .env.local als die niet gecommit is). Wees voorzichtig: maak eventueel eerst een backup van env-bestanden.

Afronding: welke fix moet je eerst proberen?

Praktische volgorde (meest winst → minst invasief):

  1. Lees de foutmelding en match op categorie (poort, Node, module).
  2. Fix 3 (poort) als je EADDRINUSE ziet.
  3. Fix 1 (Node-versie) bij OpenSSL/engine errors.
  4. Fix 7 (scripts/command not found) als binaries ontbreken.
  5. Fix 2 (clean install) bij module-resolve issues.
  6. Fix 6 (caches legen) bij spookbugs/rare HMR issues.
  7. Fix 4/5 (env + ESM/CJS/TS) bij configuratie- en runtime-mismatches.

Als je wil, plak hier de exacte terminal-output (laat secrets weg) + je package.json scripts, dan kan ik gericht zeggen welke van de 7 fixes jouw situatie het meest waarschijnlijk oplost.

Gerelateerde tutorials

Snel met Docker: bouw en draai je eerste container Hoe je snel REST API's bouwt met Python Flask Hoe je snel met Docker containers bouwt en draait