Пошук уроків, статей та іншого контенту
Створимо базову структуру Node.js-проєкту з каталогами, файлами вихідного коду та конфігурацією середовища.
Структура проєкту допомагає:
швидко знаходити потрібні файли;
відокремлювати вихідний код від конфігурації;
не додавати службові файли до репозиторію;
спрощувати запуск і подальше розширення застосунку.
Для невеликого Node.js-проєкту достатньо кількох основних елементів:
my-node-app/
├── src/
│ ├── config/
│ │ └── env.js
│ └── server.js
├── .env.example
├── .gitignore
├── package.json
└── README.mdСтворимо каталог і перейдемо до нього:
mkdir my-node-app
cd my-node-appІніціалізуємо Node.js-проєкт:
npm init -yКоманда створить файл package.json із базовою інформацією про проєкт.
package.jsonpackage.json — головний опис Node.js-проєкту. У ньому зберігаються:
назва та версія проєкту;
команди для запуску;
тип модуля;
залежності проєкту.
Замініть вміст package.json на такий:
{
"name": "my-node-app",
"version": "1.0.0",
"description": "Базовий Node.js-проєкт",
"type": "module",
"main": "src/server.js",
"scripts": {
"start": "node src/server.js"
},
"keywords": [],
"author": "",
"license": "ISC"
}Поле "type": "module" дозволяє використовувати сучасний синтаксис модулів:
import something from './file.js';Без цього поля Node.js за замовчуванням використовує інший формат модулів.
Скрипт "start" запускає файл src/server.js командою:
npm startsrcКаталог src містить вихідний код застосунку. Назва походить від слова source — «вихідний код».
Необов’язково зберігати весь код в одному файлі. Навіть у невеликому проєкті краще одразу відокремити основну логіку від конфігурації.
src/config/env.jsУ цьому файлі зберігатимемо налаштування, які можуть змінюватися залежно від середовища запуску.
const port = Number(process.env.PORT) || 3000;
const environment = process.env.NODE_ENV || 'development';
export const config = {
port,
environment
};process.env — вбудований об’єкт Node.js, який містить змінні середовища.
У прикладі:
PORT визначає порт сервера;
NODE_ENV визначає середовище запуску;
якщо змінні не задані, використовуються значення за замовчуванням.
src/server.jsЦе основний файл, який запускає HTTP-сервер:
import { createServer } from 'node:http';
import { config } from './config/env.js';
const server = createServer((request, response) => {
response.writeHead(200, {
'Content-Type': 'application/json; charset=utf-8'
});
const result = {
message: 'Node.js-сервер працює',
environment: config.environment
};
response.end(JSON.stringify(result));
});
server.listen(config.port, () => {
console.log(`Сервер запущено на порту ${config.port}`);
console.log(`Середовище: ${config.environment}`);
});У цьому коді:
Імпортується функція createServer із вбудованого модуля node:http.
Імпортується об’єкт config із файлу конфігурації.
Створюється HTTP-сервер.
Сервер повертає JSON-відповідь.
Сервер запускається на порту з конфігурації.
Важливо вказувати розширення .js в імпорті:
import { config } from './config/env.js';Запустіть сервер командою:
npm startУ терміналі з’явиться повідомлення:
Сервер запущено на порту 3000
Середовище: developmentВідкрийте в браузері адресу:
http://localhost:3000Сервер поверне:
{
"message": "Node.js-сервер працює",
"environment": "development"
}Зупинити сервер можна комбінацією клавіш Ctrl + C.
Змінні середовища дають змогу змінювати налаштування без редагування вихідного коду.
У Linux або macOS сервер можна запустити так:
PORT=4000 NODE_ENV=production npm startТоді сервер працюватиме на порту 4000, а середовище матиме значення production.
У PowerShell змінні середовища задаються так:
$env:PORT = "4000"
$env:NODE_ENV = "production"
npm startПісля цього в терміналі буде:
Сервер запущено на порту 4000
Середовище: productionЗначення з process.env завжди є рядками. Саме тому порт перетворюється на число:
const port = Number(process.env.PORT) || 3000;.env.exampleФайл .env.example описує змінні, які потрібні проєкту:
PORT=3000
NODE_ENV=developmentЦе лише приклад конфігурації. Він допомагає іншому розробнику зрозуміти, які змінні потрібно налаштувати.
Не зберігайте в репозиторії справжні паролі, токени та ключі доступу. Для цього зазвичай створюють локальний файл .env, але його додають до .gitignore.
Node.js не в усіх версіях завантажує .env автоматично. Змінні можна передавати операційній системі або використовувати спеціальні засоби завантаження змінних середовища.
.gitignore.gitignore визначає файли та каталоги, які Git не повинен додавати до репозиторію.
Створіть файл .gitignore:
node_modules/
.env
npm-debug.log*
.DS_Storenode_modulesКаталог node_modules містить встановлені залежності. Його не додають до Git, тому що:
він може займати багато місця;
його можна відновити з package.json;
різні операційні системи можуть мати різні службові файли в цьому каталозі.
Після клонування проєкту залежності відновлюють командою:
npm install.envФайл .env може містити приватні налаштування. Наприклад:
PORT=4000
NODE_ENV=developmentОскільки цей файл часто містить секрети, його потрібно виключити з Git за допомогою правила:
.envREADME.mdREADME.md містить короткий опис проєкту та інструкції для запуску.
Приклад вмісту:
# My Node App
Базовий Node.js-проєкт.
## Запуск
```bash
npm install
npm startСервер буде доступний за адресою http://localhost:3000.
У реальному проєкті README може також містити:
- вимоги до версії Node.js;
- список змінних середовища;
- команди для перевірки та тестування;
- короткий опис каталогів.
## Підсумкова структура
Після створення файлів структура проєкту має виглядати так:
```text
my-node-app/
├── src/
│ ├── config/
│ │ └── env.js
│ └── server.js
├── .env.example
├── .gitignore
├── package.json
└── README.mdКожен елемент має окрему відповідальність:
src/ — вихідний код;
src/server.js — запуск HTTP-сервера;
src/config/env.js — читання конфігурації;
.env.example — приклад змінних середовища;
.gitignore — список файлів, які не потрібно зберігати в Git;
package.json — опис проєкту та команди npm;
README.md — документація для розробників.
Якщо в package.json використовується "type": "module", у локальному імпорті потрібно вказувати розширення файлу:
import { config } from './config/env.js';Варіант без .js може спричинити помилку:
import { config } from './config/env';Команду npm start потрібно виконувати в каталозі, де розташований package.json.
Якщо команда запускається в іншій папці, npm не знайде опис проєкту.
node_modules до GitНе потрібно вручну додавати node_modules. Переконайтеся, що в .gitignore є рядок:
node_modules/Не записуйте паролі та токени у вихідний код або файл, який передається до Git. Для локальних налаштувань використовуйте змінні середовища, а в репозиторії зберігайте лише .env.example.
Node.js-проєкт зазвичай має package.json і каталог із вихідним кодом.
Каталог src призначений для коду застосунку.
Конфігурацію зручно зберігати окремо від основної логіки.
Змінні середовища доступні через process.env.
Файли .env і node_modules не потрібно додавати до Git.
Файл .env.example описує необхідні змінні без зберігання секретних значень.
Команда npm start запускає застосунок через скрипт із package.json.