Skip to main content
This page covers debugging the GitHub Docs Node.js application — not content files. These tools help you inspect server behavior, middleware, and application logic.

​
Debugging with VS Code

The repository includes a pre-configured VS Code debug configuration that works with nodemon’s --inspect flag.
1

Build the application

If you haven’t already, run the build step before starting:
npm run build
2

Start the server in debug mode

npm run debug
This starts nodemon with the --inspect flag, which opens the V8 inspector on 127.0.0.1:9229 and prints a message like:
Debugger listening on ws://127.0.0.1:9229/...
3

Open the Debug panel in VS Code

Click the Run and Debug icon in the Activity Bar (or press Ctrl+Shift+D on Windows/Linux, ⇧⌘D on macOS).
4

Select the Node: Nodemon configuration

In the Run and Debug panel, open the configuration dropdown at the top and select Node: Nodemon.Press F5 or click the green Start Debugging button.VS Code will display all running Node processes. Look for the process that was started with the --inspect flag.
5

Attach to the inspected process

Select the node process that shows the --inspect flag. VS Code will attach the debugger.You can now set breakpoints, step through code, inspect variables, and use the Debug Console.
For more detail on the VS Code + nodemon workflow, see the VS Code nodemon recipe and the VS Code debugging guide.
The Node.js debugger only helps with issues in the application code (TypeScript source in src/). It does not help debug content rendering issues in Markdown or Liquid template files.

​
Understanding nodemon restarts

nodemon watches specific file types and directories and restarts the server when it detects changes. Knowing what does and does not trigger a restart saves debugging time. Triggers a restart:
  • Any .ts, .json, .yml, .md, .html, or .scss file inside a watched directory (mainly src/)
  • Changes to package.json or other config files at the root
Does not trigger a restart:
  • content/ — documentation Markdown files
  • data/reusables/, data/variables/, data/glossaries/, data/product-examples/, data/learning-tracks/
  • assets/, script/, tests/, translations/, rest-api-description/, semmle-code/
Content files are loaded dynamically per request, so you can edit them and refresh your browser without waiting for a restart. Application source files require a restart, which nodemon handles automatically.

​
Key environment variables for development

Set these in your .env file or inline when starting the server.
VariableExample valueEffect
NODE_ENVdevelopmentEnables development-mode logging and error output. Set automatically by npm start.
ENABLED_LANGUAGESen,ja,ptControls which language trees are loaded. Defaults to en.
ELASTICSEARCH_URLhttp://localhost:9200Points search to a local Elasticsearch instance instead of production.
TRANSLATIONS_ROOT/path/to/translationsOverrides the default translations directory.
ENABLE_FASTLY_TESTINGtrueEnables the /fastly-cache-test route for inspecting Fastly cache headers.
HYDRO_ENDPOINT(your endpoint)Sends analytics events to a local mock instead of production.
When ELASTICSEARCH_URL is not set, search requests are proxied to the production endpoint. Set it only if you’re working on search indexing or query logic.

​
Using the fixture server for testing

The fixture server loads a small, self-contained content tree from src/fixtures/fixtures instead of the full content directory. It is the recommended way to test application behavior in isolation. 
npm run fixture-dev
The fixture content includes a small but representative set of pages, layouts, and data that exercise the full rendering pipeline without loading the entire content/ tree.

​
Running the test suite

The project uses Vitest as its test runner. All test commands are available via npm test.

​
Running all tests

npm test

​
Running a specific test file or directory

npm test -- src/your-feature/tests/

​
Scoped test commands

Several pre-configured test commands set the right environment variables automatically: 
npm run test:fixtures
npm run test:search and npm run test:languages require a running local Elasticsearch instance at http://localhost:9200. Start one via Docker before running these.

​
Type checking

Run the TypeScript compiler without emitting files to check for type errors across the codebase: 
npm run tsc

​
Linting

npm run lint          # ESLint on all .ts and .tsx files
npm run lint-content  # Content linter for Markdown files in content/ and data/
npm run prettier      # Auto-format .ts, .tsx, .scss, .yml, and .yaml files
npm run prettier-check  # Check formatting without making changes

​
Quick reference

CommandDescription
npm run debugStart server with Node.js inspector on port 9229
npm run fixture-devStart fixture server (lightweight content tree)
npm run fixture-dev-debugFixture server with inspector attached
npm run fixture-testRun tests against fixture content
npm testRun the full Vitest test suite
npm run tscType-check the TypeScript codebase
npm run lintLint TypeScript source files
npm run lint-contentLint Markdown content files

Build docs developers (and LLMs) love

Get started for freeTalk to us