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.
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.
| Environment | Typical APIs | Important boundary |
|---|---|---|
| Browser | DOM, window, fetch, localStorage | Runs in a page sandbox; no direct access to arbitrary local files |
| Node.js | process, fs, path, streams | Can access server resources; validate input and protect secrets |
| Shared JavaScript | Objects, functions, promises, modules | Confirm that the specific API exists in the runtime you target |
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.
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.
const name = process.argv[2]
if (!name) {
console.error('Usage: node greet.js <name>')
process.exitCode = 1
} else {
console.log('Hello, ' + name + '!')
}process.exitCode for a simple failure result. Calling process.exit()immediately can interrupt pending output or cleanup work.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.
export function add(left, right) {
return left + right
}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.
function add(left, right) {
return left + right
}
module.exports = { add }| Question | ES modules | CommonJS |
|---|---|---|
| Export syntax | export / export default | module.exports / exports |
| Import syntax | import ... from ... | require(...) |
| Typical clue | Project package configuration and .mjs files | .cjs files or existing require-based code |
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.
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.
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.
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.
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.
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.
- Extract the line-counting operation into a pure function that accepts text.
- Keep argument parsing and file reading in a thin main function.
- Test empty input, blank lines, and mixed line endings.
- Document what the exit code means and avoid printing private file contents.
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.
Create a Course-Notes CLI
Practice
Read a file, summarize it, and fail clearly
- Write a pure function that counts non-empty lines in a string and verify it against empty and multiline inputs.
- Build a CLI entry point that accepts a filename, reads UTF-8 text asynchronously, and prints the count.
- Handle a missing argument and a missing file with a helpful message and non-zero process exit code.
- Move a required service URL into an environment variable and validate it once at startup.
- 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.
Spotted a mistake or something unclear? Suggest a fix on GitHub or email us. Select the text first and it is quoted for you.
Discussion
0Have a better approach? Found something outdated? Share it — your knowledge helps everyone learning here.
