Как настроить VS Code для JavaScript: Node.js и отладка

VS Code уже умеет подсвечивать JavaScript, показывать подсказки и отлаживать Node.js. Для первой программы не нужен большой набор расширений. Нужно определить среду выполнения: браузер для кода страницы или Node.js для локального скрипта и серверного приложения.

Здесь настроим небольшой проект под Node.js с ES-модулями, тестом и отладкой. В конце разберём, почему браузерный document не работает в Node.js и как подготовить редактор для фронтенда.

Установите Node.js и проверьте npm

Для нового проекта выберите поддерживаемую LTS-ветку Node.js. Для существующего приложения используйте версию из его документации и конфигурации, даже если на главной странице Node.js уже предлагают более новую. Актуальный статус веток публикуется в таблице релизов Node.js.

После установки перезапустите VS Code и выполните в новом терминале:

node --version
npm --version

Если npm.ps1 заблокирован политикой PowerShell, проверьте npm.cmd --version. Не отключайте глобальные ограничения выполнения скриптов ради первой команды. Если версии вообще не находятся, используйте инструкцию по PATH и терминалу.

Поддержка JavaScript в редакторе не зависит от установки Node.js, но выполнение Node-программы зависит. Это различие есть в официальном Node.js tutorial VS Code.

Создайте проект с понятной точкой входа

Создайте папку js-start, откройте её в VS Code и выполните из неё:

npm init -y

Команда создаст package.json. Для этого нового учебного проекта приведите файл к следующему виду. В существующем приложении не заменяйте конфигурацию целиком:

{
  "name": "js-start",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "start": "node src/index.js",
    "test": "node --test"
  }
}

Создайте папку src, а в ней price.js:

export function totalPrice(price, quantity) {
  return price * quantity;
}

Рядом создайте src/index.js:

import { totalPrice } from "./price.js";

const total = totalPrice(350, 3);
console.log(`Total: ${total}`);

Выполните npm start. Ожидаемый результат: Total: 1050. npm запускает команду из scripts.start; VS Code не должен угадывать точку входа по активной вкладке. Правила scripts документированы в руководстве npm.

ES-модули и CommonJS: не смешивайте примеры

В данном проекте поле "type": "module" означает, что файлы .js используют ES-модули. Поэтому в коде написаны import и export. В CommonJS-проекте обычно используют require и module.exports.

Если появляется require is not defined in ES module scope, дело не в отсутствующем расширении VS Code. Проверьте формат модулей. Аналогично, при ошибке загрузки ./price.js проверьте точное имя, регистр и расширение файла. Правила определения формата изложены в документации Node.js packages.

Не меняйте type большого существующего проекта только ради одного скопированного фрагмента. Сначала приведите пример к формату приложения.

Настройте F5 и точки останова

Создайте .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Node: src/index.js",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/src/index.js",
      "cwd": "${workspaceFolder}",
      "console": "integratedTerminal",
      "skipFiles": ["<node_internals>/**"]
    }
  ]
}

Поставьте точку останова внутри totalPrice, нажмите F5 и проверьте аргументы функции. Здесь отладчик запускает тот же входной файл, что и npm start, но прямо через Node.js. Если позднее в start появятся загрузчик, генерация файлов или важные аргументы, эти два способа уже могут перестать быть эквивалентными.

Для приложения со сложным npm-скриптом настройте запуск соответствующей команды либо используйте JavaScript Debug Terminal. Не переносите этот минимальный launch.json в такой проект без проверки. Варианты запуска описаны в Node.js debugging.

Добавьте тест без стороннего фреймворка

Создайте в корне папку test, в ней файл price.test.js:

import test from "node:test";
import assert from "node:assert/strict";
import { totalPrice } from "../src/price.js";

test("calculates order total", () => {
  assert.equal(totalPrice(350, 3), 1050);
});

test("handles zero quantity", () => {
  assert.equal(totalPrice(350, 0), 0);
});

Запустите npm test. Должны пройти обе проверки. В примере используется встроенный тестовый runner Node.js; установка Jest или Vitest не нужна. В командном проекте сохраняйте уже принятый тестовый стек.

Тест не доказывает корректность функции для любых входных данных. Он фиксирует два сценария учебного примера. Если хотите принимать строки, дробные цены или отрицательные значения, сначала определите ожидаемое поведение, затем добавьте проверки.

Как включить дополнительную проверку JavaScript

Подсказки по коду работают и без отдельного TypeScript-проекта. Для проверки конкретного файла можно добавить первой строкой // @ts-check и описать типы аргументов через JSDoc.

Если решили включить проверки для всего учебного исходного кода, создайте jsconfig.json:

{
  "compilerOptions": {
    "checkJs": true,
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext"
  },
  "include": ["src/**/*.js"],
  "exclude": ["node_modules"]
}

После включения проверки могут появиться новые сообщения, в том числе о типах параметров. Их нужно исправлять или настраивать осознанно. jsconfig.json описывает проект для инструментов редактора; он не компилирует программу и не меняет версию Node.js. Возможности JSDoc и checkJs объясняет Working with JavaScript.

Что отличается для браузерного JavaScript

Код, обращающийся к document и элементам страницы, запускайте в браузере. Node.js не предоставляет DOM страницы. VS Code может помочь с отладкой браузера, но выбор среды исполнения всё равно остаётся за проектом.

Для готового фронтенд-проекта сначала прочитайте package.json и README. Команда разработки может называться npm run dev, но она существует только при наличии соответствующего script. Не устанавливайте случайный Live Server поверх приложения, которое уже использует собственный dev-сервер.

Частые ошибки

Симптом	Куда смотреть
`npm` не видит `package.json`	Текущую папку терминала
`Missing script: dev`	Раздел `scripts`; такой команды может не быть
`document is not defined`	Браузерный код запущен в Node.js
`require is not defined`	Формат модулей и поле `type`
Точка останова серая	Загружен ли нужный файл; для сборщика проверьте source maps
`node` работает снаружи, но не в VS Code	PATH, менеджер версий и перезапуск редактора

Для оформления исходников добавьте Prettier с локальной конфигурацией. Для истории изменений настройте Git, исключите node_modules/, но сохраните файл зависимостей и lock-файл выбранного менеджера. Итоговая настройка должна воспроизводиться по проекту, а не существовать только в личных параметрах одного редактора.