Handleiding: Projectspecifieke Node.js-versie instellen met ServBay (macOS)

ServBay is een krachtig, lokaal webontwikkelplatform speciaal ontworpen voor ontwikkelaars. Het biedt een alles-in-één oplossing met integratie van meerdere programmeertalen, databases en webservers, waaronder Node.js. Een opvallend voordeel van ServBay is de native ondersteuning voor en het flexibel beheer van verschillende Node.js-versies. Met een simpel configuratiebestand wijs je eenvoudig per project de gewenste Node.js-versie toe, zonder dat je externe tools als NVM, fnm of Docker-containers hoeft te gebruiken. Hierdoor wordt je workflow eenvoudiger en voorkom je vervuiling van de globale omgeving en versieconflicten.

In dit artikel lees je hoe je met het .servbay.config bestand van ServBay versiebeheer op projectniveau toepast voor Node.js.

Waarom Node.js-versiebeheer met .servbay.config van ServBay?

Traditionele methoden voor het beheren van Node.js-versies, zoals NVM of handmatige installatie, brengen diverse nadelen met zich mee:

• Globale vervuiling & conflicten: Globale installaties of het globaal wisselen van versies via versiebeheer kan leiden tot dependency-conflicten tussen projecten.
• Installatie- en compileertijd: Nieuwe versies installeren of schakelen tussen architecturen (zoals x86_64 en arm64) kan hercompilatie van modules vereisen, wat tijdrovend en ingewikkeld is.
• Overhead van Docker-containers: Voor situaties waarin alleen een specifieke Node.js-versie nodig is, zijn volledige Docker-containers vaak overdreven zwaar.

ServBay biedt een elegantere oplossing door standaard meerdere gangbare Node.js-versies voor te installeren (op dit moment worden alle hoofd- en subversies van v12 t/m v23 ondersteund; te beheren via het onderdeel "Packages" in ServBay), en het gebruik van het .servbay.config configuratiebestand:

• Direct schakelen: De versies zijn al geïnstalleerd; wisselen gaat bijna direct.
• Projectisolatie: De configuratie werkt alléén binnen de projectmap, waardoor je echte versie-isolatie per project hebt.
• Geen globale vervuiling: Je wijzigt niets aan het globale systeem, je systeem blijft schoon.
• Volledige ServBay-integratie: Naadloze integratie binnen de ServBay-omgeving en samenwerking met andere ServBay-pakketten (zoals PHP, databases en webservers).

Vereisten

Voordat je begint, zorg ervoor dat:

1. Je ServBay correct hebt geïnstalleerd en uitgevoerd op macOS.
2. Je via het ServBay interface in het overzicht "Packages" de Node.js-versie die je nodig hebt voor je project hebt geactiveerd.
3. Je beschikt over een projectmap waarvoor je een specifieke Node.js-versie wilt instellen.

Kernprincipe

ServBay houdt in zijn geïntegreerde terminalomgeving continu bij in welke map je je bevindt. Zodra je via het cd-commando een bepaalde map binnenloopt, zoekt ServBay in die map én de bovenliggende mappen naar het bestand .servbay.config. Zodra dit bestand gevonden is (voorkeur voor de meest nabije), leest ServBay de instellingen uit en past de omgeving van je huidige terminalsessie dynamisch aan – bijvoorbeeld door het aanpassen van het PATH-variabele zodat het verwijst naar het juiste Node.js-installatiepad zoals gespecificeerd in .servbay.config.

Op deze manier laadt en gebruikt iedere projectmap automatisch zijn eigen versie van Node.js, zonder dat je handmatig hoeft te switchen.

Stappenplan

Een project van een eigen Node.js-versie voorzien is eenvoudig en omvat twee stappen:

Stap 1: Maak en bewerk het .servbay.config bestand

In de hoofdmap van je project (waar doorgaans je package.json zich bevindt), maak je een nieuw bestand aan met de naam .servbay.config.

Open dit bestand in je favoriete teksteditor en voeg bijvoorbeeld het volgende toe:

# Stel het hoofdversienummer van Node.js in dat dit project gebruikt
# ServBay kiest automatisch de meest recente subversie die is geïnstalleerd
NODE_VERSION=20

# Optioneel: configureer een npm of pnpm mirror om afhankelijkheden sneller te installeren
# Gebruik een lokale mirror als je in China werkt
YARN_CONFIG_REGISTRY=https://npmreg.proxy.ustclug.org/
NPM_CONFIG_REGISTRY=https://registry.npmmirror.com

# Optioneel: stel een cachemap in voor npm of pnpm
# Het is aanbevolen om de cache in ServBay’s tijdelijke map te plaatsen en zo systeemruimte en gebruikersmap te ontzien
NPM_CONFIG_CACHE=/Applications/ServBay/tmp/npm/cache

Toelichting bij de configuratie:

• NODE_VERSION: Vereist. Geef het hoofdversienummer van Node.js op dat je project nodig heeft. Bijvoorbeeld, met 20 gebruik je automatisch de nieuwste Node.js 20.x in ServBay. Controleer dat deze versie geïnstalleerd is.
• YARN_CONFIG_REGISTRY / NPM_CONFIG_REGISTRY: Optioneel. Spiegel-URL's voor Yarn of npm, handig bij trage netwerken of connectiviteit in bijvoorbeeld China.
• NPM_CONFIG_CACHE: Optioneel. Locatie voor de npm- of pnpm-cache. Door deze te plaatsen in /Applications/ServBay/tmp/npm/cache houd je de cache centraal en voorkom je vervuiling van de rest van het systeem.

Sla het .servbay.config-bestand op en sluit je editor.

Stap 2: De versie controleren in de ServBay-terminal

1. Open de hoofdinterface van ServBay.

2. Klik op de knop “Terminal” om de geïntegreerde terminal te openen.

3. Gebruik het cd-commando naar jouw projectmap:

   cd /Applications/ServBay/www/your-project-name

   (Vervang /Applications/ServBay/www/your-project-name door het echte pad van jouw project)

4. Geef het commando node -v om te controleren welke Node.js-versie actief is:

   node -v

   De uitvoer toont nu de versie uit je .servbay.config (bijvoorbeeld v20.x.x).

5. Je kunt ook met npm -v (of pnpm -v, yarn -v) bevestigen dat de package managers gekoppeld zijn aan de juiste Node.js-versie.

Voer je Node.js- of npm/pnpm/yarn-commando’s nu uit in deze projectmap, dan wordt altijd gebruikgemaakt van de in .servbay.config vastgelegde Node.js-versie en bijbehorende package manager-instellingen.

Voorbeeld: Automatisch wisselen tussen projecten

Hieronder een simpel voorbeeld hoe .servbay.config gebruikt wordt om automatisch tussen Node.js-versies te wisselen bij verschillende projecten.

Stel: je hebt twee projecten, project-a vereist Node.js v18, en project-b vereist Node.js v20.

1. Maak projectmappen aan en stel configuratie in:

   # Maak de voorbeeldmappen aan onder www van ServBay
   mkdir /Applications/ServBay/www/project-a
   mkdir /Applications/ServBay/www/project-b
   
   # Voor project-a: .servbay.config voor Node.js v18
   echo "NODE_VERSION=18" > /Applications/ServBay/www/project-a/.servbay.config
   
   # Voor project-b: .servbay.config voor Node.js v20
   echo "NODE_VERSION=20" > /Applications/ServBay/www/project-b/.servbay.config

2. Controleer het schakelen in de ServBay-terminal:

   Open de ServBay-terminal en voer het volgende uit:

   # Ga naar de map van project-a
   cd /Applications/ServBay/www/project-a
   # Controleer Node.js-versie
   node -v
   # Verwachte output: v18.x.x
   
   # Ga naar de map van project-b
   cd ../project-b
   # Controleer Node.js-versie
   node -v
   # Verwachte output: v20.x.x
   
   # Terug naar project-a
   cd ../project-a
   # Controleer Node.js-versie opnieuw
   node -v
   # Verwachte output: v18.x.x

Dit voorbeeld toont aan dat ServBay, afhankelijk van de map waarin je werkt, automatisch het juiste NODE_VERSION-instelling uit .servbay.config inlaadt en toepast. Zo wissel je moeiteloos tussen verschillende Node.js-versies voor ieder project.

Onderstaande afbeelding laat zien hoe bij het wisselen tussen projectmappen de actieve Node.js-versie verandert, gestuurd door .servbay.config (de afbeelding is ter illustratie, het werkelijke uiterlijk kan verschillen):

Let op

• Plaats het .servbay.config-bestand in je projectmap of een bovenliggende map. ServBay zoekt naar het eerstgevonden .servbay.config hoger in de directorystructuur (het meest dichtbij).
• Werk altijd in de terminal die geïntegreerd is in ServBay of zorg dat je externe terminal voorzien is van alle relevante ServBay-omgevingsvariabelen.
• De door NODE_VERSION gespecificeerde Node.js-versie moet in ServBay zijn geïnstalleerd en geactiveerd. Ontbreekt de versie, dan schakelt ServBay eventueel terug naar een standaardversie of raakt het node-commando niet gevonden.
• Instellingen in .servbay.config zijn uitsluitend van kracht in de huidige terminalsessie en subprocessen, niet voor het hele systeem of processen buiten ServBay.

Veelgestelde vragen (FAQ)

Q: Wat gebeurt er als mijn projectmap geen .servbay.config bestand bevat?

A: Als ServBay geen .servbay.config vindt in de huidige map of een bovenliggende map, dan wordt de globale instelling gebruikt of de standaard Node.js-versie van ServBay (meestal gemarkeerd als “standaard”).

Q: Hoe zie ik welke Node.js-versies ServBay ondersteunt?

A: Open de ServBay-app en ga in het linkermenu naar "Packages". Daar vind je het volledige overzicht van beschikbare en geïnstalleerde Node.js-versies en andere pakketten. Je kunt eenvoudig bepaalde versies aan- of uitzetten.

Q: Beïnvloedt een .servbay.config-bestand mijn hele systeem?

A: Nee. De instellingen in .servbay.config zijn tijdelijk en alleen van kracht in de ServBay-terminal(s) of processen waarin de ServBay-omgeving actief is. Er worden geen globale omgevingsvariabelen of instellingen aangepast buiten ServBay. Dit is een centraal onderdeel van de projectisolatie van ServBay.

Q: Kan ik behalve NODE_VERSION nog meer ServBay-gerelateerde zaken instellen via .servbay.config?

A: Zeker. .servbay.config is bedoeld als algemene manier om per project omgevingsvariabelen in te stellen binnen ServBay. Je kunt dus, afhankelijk van de ServBay-versie en uitbreidingen, ook andere variabelen beheren die actief worden bij het uitvoeren van commando’s in de betreffende projectmap. Het instellen van environment variables is de kernfunctie.

Samenvatting

Met behulp van het .servbay.config-bestand van ServBay wijs je eenvoudig, snel en efficiënt per lokaal development-project een specifieke Node.js-versie toe én beheer je npm/yarn/pnpm-instellingen. Deze aanpak is lichter, sneller en gebruiksvriendelijker dan traditionele versiebeheeroplossingen of containers, en sluit naadloos aan op de alles-in-één ontwikkelomgeving die ServBay biedt. Voeg vandaag nog .servbay.config toe aan je project en ervaar het voordeel van moeiteloos en conflictvrij Node.js-versiebeheer!