Посібник із незалежної конфігурації версій Node.js для проекту в ServBay (macOS)

ServBay — це потужне локальне середовище веб-розробки, створене спеціально для розробників. Воно пропонує комплексне рішення з інтеграцією багатьох мов програмування, баз даних і вебсерверів, включаючи Node.js. Однією з головних переваг ServBay є його вбудована підтримка кількох версій Node.js та гнучке управління ними. За допомогою простого конфігураційного файлу ви можете легко вказати потрібну версію Node.js для кожного проєкту окремо — без використання зовнішніх менеджерів версій на кшталт NVM чи fnm або Docker, що дозволяє уникати конфліктів і засмічення глобального середовища.

У цьому матеріалі докладно описано, як використовувати файл .servbay.config для реалізації проєктного керування версіями Node.js у ServBay.

Чому варто використовувати .servbay.config у ServBay для управління версіями Node.js?

Традиційні підходи до керування версіями Node.js (наприклад, NVM або ручне встановлення) можуть спричиняти певні незручності:

• Глобальне засмічення й конфлікти. Глобальне встановлення чи керування версіями на рівні системи може призводити до конфліктів залежностей між різними проектами.
• Трудомісткі інсталяції та компіляції. Встановлення нових версій або перемикання між різними архітектурами (наприклад, x86_64 і arm64) часто вимагає повторної компіляції модулів — це складно й займає багато часу.
• Витрати ресурсів Docker. Якщо вам потрібно лише певну версію Node.js, розгортання Docker-контейнера часто є надто важким рішенням.

ServBay пропонує елегантний підхід завдяки вже предвстановленим популярним версіям Node.js (зараз підтримуються всі основні та другорядні версії з v12 до v23, список керується у вкладці “Пакети” в застосунку ServBay), і використанню конфігураційного файлу .servbay.config:

• Миттєве перемикання. Всі версії вже інстальовані; перемикання займає долі секунди.
• Ізоляція проєктів. Налаштування діє лише у межах директорії проекту, забезпечуючи справжню ізоляцію версій для кожного проекту.
• Відсутність глобального засмічення. Системне середовище не модифікується — операційна система лишається “чистою”.
• Інтеграція із ServBay. Все працює у межах єдиної екосистеми, взаємодіє з іншими пакетами ServBay (PHP, бази даних, веб-сервери тощо).

Необхідні умови

Перед початком переконайтесь, що:

1. На вашому macOS встановлено та запущено ServBay.
2. Через інтерфейс застосунку ServBay у вкладці “Пакети” ви переконались, що потрібна версія Node.js встановлена й активована.
3. У вас є директорія, де потрібна окрема версія Node.js для проекту.

Основний принцип

Працюючи у вбудованому терміналі ServBay, середовище відстежує поточну директорію. Коли ви виконуєте команду cd для переходу у певну директорію, ServBay автоматично шукає (рухаючись вгору по структурі папок) файл з назвою .servbay.config. Знайшовши найзручніший (найближчий до поточної директорії) файл, ServBay завантажує налаштування і змінює змінні оточення термінальної сесії, наприклад, PATH, вказуючи на інсталяцію Node.js потрібної версії.

Завдяки цьому різні термінальні сесії перемикають версії Node.js автоматично, залежно від активної директорії проекту, без ручних операцій.

Кроки налаштування

Налаштувати окрему версію Node.js для проекту дуже просто:

Крок 1: Створіть і відредагуйте файл .servbay.config

У корені вашого проекту (зазвичай поруч із package.json) створіть новий файл з назвою .servbay.config.

Відкрийте його у вашому улюбленому редакторі і додайте такий зміст:

# Вказуємо основну версію Node.js для проекту
# ServBay автоматично вибирає найновішу підверсію вказаної основної версії
NODE_VERSION=20

# Додатково: налаштування дзеркал npm або pnpm для пришвидшення встановлення залежностей
# Якщо ви в Китаї, рекомендується використовувати локальні дзеркала
YARN_CONFIG_REGISTRY=https://npmreg.proxy.ustclug.org/
NPM_CONFIG_REGISTRY=https://registry.npmmirror.com

# Додатково: налаштування директорії кешу npm або pnpm
# Рекомендуємо використовувати тимчасову папку ServBay, щоб не захаращувати систему
NPM_CONFIG_CACHE=/Applications/ServBay/tmp/npm/cache

Пояснення ключових налаштувань:

• NODE_VERSION: обовʼязково. Вказує основну версію Node.js для проекту. Наприклад, 20 — буде використано останню доступну версію Node.js 20.x у ServBay. Переконайтесь, що ця версія вже встановлена в ServBay.
• YARN_CONFIG_REGISTRY / NPM_CONFIG_REGISTRY: опціонально. Швидке встановлення пакетів завдяки альтернативним реєстрам. Особливо корисно за повільного інтернету.
• NPM_CONFIG_CACHE: опціонально. Дозволяє визначити директорію для кешу менеджерів пакетів. Рекомендуємо вказувати папку всередині /Applications/ServBay/tmp/npm/cache для централізованого управління кешем і уникнення засмічення системи файлами.

Збережіть і закрийте .servbay.config.

Крок 2: Перевірте вибір версії у терміналі ServBay

1. Відкрийте головне вікно застосунку ServBay.

2. Натисніть кнопку “Термінал” (Terminal), щоб відкрити інтегрований термінал.

3. Заходьте у директорію свого проекту:

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

   (Замініть /Applications/ServBay/www/your-project-name на шлях до вашого проекту)

4. Виконайте команду, щоб перевірити активну версію Node.js:

   node -v

   У виводі має бути саме та версія, яку ви вказали у .servbay.config (наприклад, v20.x.x).

5. Також можете перевірити версію npm/pnpm/yarn:

   npm -v

   (або pnpm -v, yarn -v) — переконайтесь, що пакетний менеджер синхронізований із поточною версією Node.js.

Тепер усі команди Node.js/npm/pnpm/yarn у директорії проекту використовуватимуть саме ту версію Node.js, яка вказана в .servbay.config.

Приклад використання

Ось як виглядає автоматичне перемикання версій Node.js для різних проектів.

Припустимо, у вас є два проекти: project-a (потребує Node.js v18) і project-b (потребує Node.js v20).

1. Створюємо директорії проектів і конфігураційні файли:

   # Створення проектних директорій у www папці ServBay
   mkdir /Applications/ServBay/www/project-a
   mkdir /Applications/ServBay/www/project-b
   
   # Для project-a створюємо .servbay.config із Node.js v18
   echo "NODE_VERSION=18" > /Applications/ServBay/www/project-a/.servbay.config
   
   # Для project-b створюємо .servbay.config із Node.js v20
   echo "NODE_VERSION=20" > /Applications/ServBay/www/project-b/.servbay.config

2. Перевіряємо перемикання у терміналі ServBay:

   Відкрийте термінал ServBay і виконайте:

   # Заходимо у папку project-a
   cd /Applications/ServBay/www/project-a
   # Перевіряємо версію Node.js
   node -v
   # Очікувано: v18.x.x
   
   # Переходимо до проекту-b
   cd ../project-b
   # Перевіряємо версію Node.js
   node -v
   # Очікувано: v20.x.x
   
   # Повертаємося у project-a
   cd ../project-a
   # Ще раз перевіряємо Node.js
   node -v
   # Очікувано: v18.x.x

Як бачите, ServBay автоматично підлаштовує поточне оточення залежно від директорії — активує потрібну версію Node.js із налаштувань .servbay.config.

Ось ілюстрація перемикання версій Node.js у різних директоріях (на вигляд інтерфейсу можуть бути деякі відмінності):

На що звернути увагу

• Файл .servbay.config повинен знаходитися в директорії проекту або в батьківських папках. ServBay шукатиме найближчий до поточної директорії (вгору по дереву).
• Переконайтесь, що працюєте у терміналі, інтегрованому з ServBay, або у зовнішньому терміналі, підключеному до середовища ServBay.
• Версія, зазначена у NODE_VERSION, має бути попередньо встановлена і активована у ServBay. Якщо ця версія не встановлена, можливий “відкат” до стандартної версії або помилковий виклик Node.js.
• Налаштування у .servbay.config впливають лише на поточну сесію терміналу та дочірні процеси, а не на всю систему.

Поширені запитання (FAQ)

Q: Що якщо в директорії мого проекту немає файлу .servbay.config?

A: Якщо ServBay не знаходить .servbay.config в поточній чи батьківських директоріях, буде використано глобальні чи стандартні налаштування — зазвичай це версія Node.js, позначена в ServBay як “стандартна”.

Q: Як дізнатись, які версії Node.js підтримує ServBay?

A: Відкрийте застосунок ServBay і перейдіть у розділ “Пакети” в лівому меню. Тут ви побачите всі доступні й встановлені пакети, включно з різними версіями Node.js. Щоб активувати чи деактивувати певну версію, просто поставте або зніміть позначку.

Q: Чи впливають налаштування з .servbay.config на всю систему?

A: Ні. Все обмежується поточною сесією інтегрованого терміналу ServBay або іншого процесу, запусканого із правильними змінними середовища. Системні змінні не змінюються — це основний інструмент ізоляції проектів у ServBay.

Q: Чи можна у .servbay.config окрім NODE_VERSION прописувати додаткові налаштування?

A: Так! .servbay.config — універсальний файл для керування змінними середовища проекту. Окрім Node.js, можете вказати будь-які інші змінні для автоматичного застосування у межах поточної директорії. Перелік цих змінних може поповнюватися з оновленнями ServBay, але налаштування оточення — головний функціонал.

Підсумок

Завдяки використанню .servbay.config у ServBay ви можете просто й ефективно налаштовувати й управляти незалежними версіями Node.js для кожного локального проекту. Це набагато легше, ніж традиційні менеджери версій або Docker-контейнери, максимально інтегрується в екосистему ServBay та допомагає створити стабільний, структурований і зручний для співпраці робочий процес. Застосуйте .servbay.config у своїх проектах і відчуйте зручність від ServBay вже сьогодні!