Node.js Fundamentals — Runtime, File System and Modules

Run JavaScript outside the browser, understand Node.js modules and filesystem APIs, read environment variables, and build a small CLI.

Est. 40 min Updated Suggest a fix
// Part 01 — The runtime

JavaScript Outside the Browser

JavaScript is the language; Node.js is a runtime that executes JavaScript outside a web page. Node provides APIs for files, paths, processes, streams, and networking that browsers do not expose in the same way. A Node program can serve an API, automate a task, or power a command-line tool. The language fundamentals are shared, but available globals and security boundaries differ by runtime.

Node runs JavaScript on its event loop and can delegate certain I/O operations to the operating system or runtime. That lets one process handle many waiting operations without blocking on each one. CPU-heavy synchronous work can still block the event loop, so keep request handlers and command-line progress responsive.

The same JavaScript syntax does not imply the same runtime capabilities.
EnvironmentTypical APIsImportant boundary
BrowserDOM, window, fetch, localStorageRuns in a page sandbox; no direct access to arbitrary local files
Node.jsprocess, fs, path, streamsCan access server resources; validate input and protect secrets
Shared JavaScriptObjects, functions, promises, modulesConfirm that the specific API exists in the runtime you target
💡 Note
Node.js is not a browser with the UI removed. It has a different set of global objects and application responsibilities.
// Part 02 — Run a program

Start with a Small Script

Create a JavaScript file and run it using the Node executable available in your development environment. The process global describes the current process, including its arguments, working directory, and environment. Remember that a process can be started from different directories, so a relative path is not always relative to the script itself.

hello.js
javascript
console.log('Hello from Node.js')
console.log('Current working directory:', process.cwd())
console.log('Arguments:', process.argv.slice(2))

process.argv includes the executable and script entries before arguments supplied by the user; slicing from index two gives the CLI arguments for this simple example. For a tool with flags, help text, and validation, use a deliberate argument parser rather than interpreting ambiguous strings ad hoc.

greet.js
javascript
const name = process.argv[2]

if (!name) {
  console.error('Usage: node greet.js <name>')
  process.exitCode = 1
} else {
  console.log('Hello, ' + name + '!')
}
🎯 Pro Tip
Prefer setting process.exitCode for a simple failure result. Calling process.exit()immediately can interrupt pending output or cleanup work.
// Part 03 — Modules

Choose and Understand a Module System

Modules divide a program into files with explicit imports and exports. Node supports ECMAScript modules, commonly called ESM, and the older CommonJS format. A project should choose a format and remain consistent; package settings affect how Node interprets files. Do not copy an import example into a project without checking its module setup.

math.js — ESM
javascript
export function add(left, right) {
  return left + right
}
app.js — ESM
javascript
import { add } from './math.js'

console.log(add(4, 5))

CommonJS uses require and module.exports. Existing projects may use it, but new code should follow the module format already configured by that project. Mixing formats carelessly can create confusing import behaviour, particularly around default exports and file extensions.

legacy-module.cjs
javascript
function add(left, right) {
  return left + right
}

module.exports = { add }
QuestionES modulesCommonJS
Export syntaxexport / export defaultmodule.exports / exports
Import syntaximport ... from ...require(...)
Typical clueProject package configuration and .mjs files.cjs files or existing require-based code
// Part 04 — Paths and files

Build Paths and Read Files Safely

The path module handles platform-specific separators and path joining. Avoid manually concatenating directory strings: a slash that works on one operating system may not be the expected separator on another. Decide whether your path should be based on the process working directory or the script/module location.

read-config.js
javascript
import { readFile } from 'node:fs/promises'
import path from 'node:path'

async function readConfig() {
  const filePath = path.join(process.cwd(), 'config.json')
  const contents = await readFile(filePath, 'utf8')
  return JSON.parse(contents)
}

readConfig()
  .then((config) => console.log(config))
  .catch((error) => {
    console.error('Could not read config:', error.message)
    process.exitCode = 1
  })

This uses promise-based file I/O so the event loop is not synchronously blocked while waiting for the file. Parsing JSON can still throw for malformed content, and reading can fail because a file is missing or permissions differ. Handle those cases at the boundary where a useful message can be shown. Do not assume a file exists because it did on your laptop.

⚠️ Important
A filename supplied by a user is untrusted input. Normalize and constrain it to an intended directory before using it to read or write files; do not let an arbitrary path become a server-side file access operation.
// Part 05 — Environment configuration

Keep Configuration and Secrets Out of Source

Environment variables let the same program use different settings in development, testing, and deployment. Node exposes them through process.env, where values are strings and may be absent. Validate required values once near application startup and fail with a clear message instead of allowing an undefined value to fail much later.

config.js
javascript
function requiredEnv(name) {
  const value = process.env[name]
  if (!value) {
    throw new Error('Missing required environment variable: ' + name)
  }
  return value
}

const config = {
  port: Number(process.env.PORT || 3000),
  serviceUrl: requiredEnv('SERVICE_URL'),
}

export { config }

The example uses a default for a non-secret local port and requires a service URL. Validate numeric settings too if their exact range matters. A secret such as an API key should come from the deployment environment or a local untracked configuration file managed according to the project policy. Never print secrets into logs, commit them, or expose server environment variables to browser code.

📌 Real World Example
A campus events tool can use one service URL in a developer environment and another in its hosted environment while keeping the source code unchanged. The environment is configuration, not a reason to hard-code credentials.
// Part 06 — Build a CLI

Turn a Small Script into a Useful Tool

A CLI should make its contract clear: what input it accepts, what it writes, how it reports errors, and what exit status it returns. This example reads a text file and counts non-empty lines. It validates argument presence, resolves a path from the current directory, and catches file errors at the program boundary.

count-lines.js
javascript
import { readFile } from 'node:fs/promises'
import path from 'node:path'

async function main() {
  const filename = process.argv[2]
  if (!filename) {
    throw new Error('Usage: node count-lines.js <file>')
  }

  const filePath = path.resolve(process.cwd(), filename)
  const contents = await readFile(filePath, 'utf8')
  const count = contents.split(/\r?\n/).filter((line) => line.trim().length > 0).length
  console.log('Non-empty lines:', count)
}

main().catch((error) => {
  console.error(error.message)
  process.exitCode = 1
})

The tool is intentionally small, but the boundary is explicit. For a shared utility, add tests around argument parsing, file contents, and missing-file behaviour. Separate the reusable counting function from direct process I/O so it can be tested without launching a separate process for every case.

  1. Extract the line-counting operation into a pure function that accepts text.
  2. Keep argument parsing and file reading in a thin main function.
  3. Test empty input, blank lines, and mixed line endings.
  4. Document what the exit code means and avoid printing private file contents.
// Part 07 — Pitfalls

Common Node.js Mistakes

Assuming a relative file path starts beside the script

Why: Relative paths are commonly resolved from the process working directory.

Fix: Choose the base intentionally and use the path module to construct it.

Mixing ESM and CommonJS syntax without checking project settings

Why: Node interprets files according to module configuration and file conventions.

Fix: Follow the existing project format and verify imports with a minimal run.

Blocking the event loop with synchronous I/O in a server path

Why: Other JavaScript callbacks wait while synchronous work finishes.

Fix: Use asynchronous APIs for routine I/O in applications that serve concurrent work.

Putting credentials in source or console output

Why: Source and logs are easily copied, committed, or exposed.

Fix: Read secrets from protected environment configuration and redact diagnostics.

// Part 08 — Practice

Create a Course-Notes CLI

Practice

Read a file, summarize it, and fail clearly

  1. Write a pure function that counts non-empty lines in a string and verify it against empty and multiline inputs.
  2. Build a CLI entry point that accepts a filename, reads UTF-8 text asynchronously, and prints the count.
  3. Handle a missing argument and a missing file with a helpful message and non-zero process exit code.
  4. Move a required service URL into an environment variable and validate it once at startup.
  5. Run the same small module in the module format used by your project; explain how you confirmed the configuration.

Hint: Keep the pure counting function separate from process.argv and filesystem access so each layer is easy to test.

🎯 Key Takeaways

  • ✓Node.js runs JavaScript outside the browser and provides its own process, filesystem, and path APIs.
  • ✓Keep ESM and CommonJS usage consistent with the project configuration.
  • ✓Use path utilities and async filesystem APIs for portable, responsive programs.
  • ✓Treat process arguments, file paths, and file contents as inputs that require validation.
  • ✓Read deployment-specific settings from the environment, validate required values, and protect secrets.
  • ✓Design a CLI with a clear contract, useful errors, and deliberate exit status.

Next

What comes next

You have a working mental model for JavaScript in Node. Next, add static types to model inputs and results more clearly, narrow unknown data, and make invalid states harder to represent.

Lesson 12 · TypeScript Essentials →

HELP US IMPROVE

How was this lesson?

Your note is shared with the Chaduvuko team for review. Please don’t include personal or sensitive information.

Choose your feedback

Spotted a mistake or something unclear? Suggest a fix on GitHub or email us. Select the text first and it is quoted for you.

Share

Discussion

0

Have a better approach? Found something outdated? Share it — your knowledge helps everyone learning here.

Continue with GitHub
Loading...