How to run a JavaScript file with Node.js

For what felt like an eternity in internet time, JavaScript was a language shackled to the web browser. It was the language of dancing Santas, annoying pop-ups, and eventually, sophisticated web applications. But it was always, always, running inside the sandbox of a browser. If you wanted to write a simple script to, say, rename a bunch of files on your computer, you’d reach for Perl, Python, or a crusty old shell script. JavaScript wasn’t even an option. It was a toy language for the front-end, or so the thinking went.

This was a tremendous shame. You had a whole generation of developers cutting their teeth on JavaScript, becoming incredibly proficient with it, but they had to learn a completely different language and ecosystem for any task that didn’t involve a tag. It was a classic case of the right tool for the job being locked in a box.

Then along came Ryan Dahl in 2009, who did something so brilliantly obvious in retrospect it’s a wonder it didn’t happen sooner. He took Google’s stupendously fast V8 JavaScript engine-the very same one powering the Chrome browser-and bolted it onto a C++ program. He added a few necessary bits for interacting with the underlying operating system, like file I/O and networking, and called it Node.js. Suddenly, JavaScript was free. It could run anywhere. On your server, on your laptop, anywhere you could compile the source.

What does that look like in practice? It’s shockingly simple. Forget about index.html and tags. You just write JavaScript in a plain text file. Let’s create a file named hello.js:

// hello.js
const message = "Hello from outside the browser!";
console.log(message);

This is JavaScript, pure and simple. There’s no Document Object Model (DOM), no window object, no browser APIs to speak of. Instead, you have a global console object, just like in the browser’s developer tools, that lets you print text directly to your terminal. You also have access to a powerful set of built-in modules for handling files, network requests, and other system-level tasks. This simple act of decoupling JavaScript from the browser has had profound consequences for web development. It means you can use the same language, and often the same developers, to build both the front-end and the back-end of your application. The “full-stack JavaScript developer” was born from this moment. To get started, you first need to install Node.js on your system. It’s available for Windows, macOS, and Linux, and the installation is typically a straightforward process of downloading an installer from the official website and clicking “Next” a few times. Once installed, you have a new command available in your terminal: node. This is the runtime environment that will execute your code.

Running your script is a single command

To run this masterpiece of software engineering, you’ll fire up your favorite command line. That’s Terminal on macOS, PowerShell or Command Prompt on Windows, or whatever shell you prefer on Linux. The first step is to navigate to the directory where you saved your file. If you just dropped it on your Desktop, you’d do something like this:

cd Desktop

Once your terminal’s working directory is the same as the file’s location, you can execute it. The command is breathtakingly complex, so pay close attention. You type node, followed by the name of the file.

$ node hello.js

Hit Enter. What happens next is the magic. You’ll see the output of your script printed directly below your command:

Hello from outside the browser!

It’s that simple. No, really. There’s no compilation step, no web server to configure, no labyrinth of XML files to edit. You wrote a script, and you ran it. The command node starts the Node.js runtime, which loads your JavaScript file, passes it to the V8 engine for execution, and pipes the output of functions like console.log directly to your terminal’s standard output. This immediate feedback loop is addictive. It’s programming reduced to its essence: write code, run code, see results. This is a world away from the ceremony and boilerplate that used to be required for server-side programming. You can even launch Node.js without a file to get an interactive shell, sometimes called a REPL for Read-Eval-Print Loop. Just type node by itself, and you get a > prompt, ready to execute any JavaScript you throw at it.

Don’t forget about the arguments

A script that does the exact same thing every time is, to be blunt, a glorified text file. It’s a party trick. The real power comes when you can give your script some data to work with when you run it. You need to pass it arguments. If you’ve ever used a command-line tool like grep or ls, you’ve used arguments: ls -l passes the -l argument to the ls program. How do you build a JavaScript script that can do the same?

Node.js, thankfully, doesn’t overcomplicate this. It exposes all the command-line arguments through a global object called process. Specifically, you’re interested in the process.argv property. The name argv is a classic C-ism, short for “argument vector,” which is a fancy way of saying “an array of strings.” Let’s see what’s in it. Create a new file, args.js:

// args.js
console.log("Here are your arguments:");
console.log(process.argv);

Now, run this from your terminal and throw a few random words after it:

$ node args.js testing 123 --whatever

The output will be something like this, though your specific paths will vary:

Here are your arguments:
[
  '/usr/local/bin/node',
  '/Users/jattwood/Desktop/args.js',
  'testing',
  '123',
  '--whatever'
]

Wait a minute. What’s all that extra junk at the beginning? This is a critical, and slightly annoying, detail you have to remember. The process.argv array is not just the arguments you provided. It’s a complete record of the command used to launch the process.

• process.argv[0] is the full path to the Node.js executable itself.
• process.argv[1] is the full path to the JavaScript file you’re running.

The arguments you actually care about start at index 2. This is a common source of confusion and bugs for anyone new to Node.js scripting. Your arguments are hiding in plain sight, just a little further down the array than you might expect. So, to make our original script greet a specific person, we’d modify it to look at process.argv[2].

// hello-you.js
const name = process.argv[2];

if (name === undefined) {
  console.log("Hello, mysterious stranger!");
} else {
  console.log(Hello, ${name}!); }

Running this is now far more interesting:

$ node hello-you.js Alice
Hello, Alice!

$ node hello-you.js Bob
Hello, Bob!

$ node hello-you.js
Hello, mysterious stranger!

Now we’re talking. We’ve built a bona fide command-line utility. It takes input and changes its behavior based on that input. This is the fundamental building block of every CLI tool you’ve ever used. If you want to grab all the user-provided arguments, a common pattern is to slice the array, creating a new one that contains only the elements you care about.

const myArgs = process.argv.slice(2);
console.log('Your arguments were: ', myArgs);

// $ node my-script.js arg1 arg2 arg3
// Your arguments were: [ 'arg1', 'arg2', 'arg3' ]

This is much cleaner than manually picking off elements by their index, especially when you don’t know how many arguments the user might provide. Of course, this simple array is just the beginning. Manually parsing arguments like --user=alice or -v gets tedious fast. You have to loop through the array, check if a string starts with a hyphen, split on the equals sign… it’s a mess of string manipulation that you really don’t want to write yourself.

This is why a universe of argument-parsing libraries like yargs and commander exists. They handle all the dirty work of defining flags, handling different data types, and even generating help text automatically. For any non-trivial script, pulling in one of these libraries is almost always the first step. For example, with yargs, you can define an expected argument, give it an alias, set a default value, and describe what it does.

The library then presents the parsed arguments to you in a clean object, rather than a raw array of strings. It can even tell the user they’ve made a mistake and show them the correct usage if they provide an invalid argument, which is far more user-friendly than your script just crashing or behaving unpredictably. The raw process.argv is fine for the simplest of cases, but the moment you need a proper flag like --verbose or a key-value pair, you’ll want to reach for a more robust solution.

Parsing these yourself is a classic case of reinventing the wheel, and it’s a wheel that’s surprisingly easy to get wrong, especially when dealing with edge cases like quoted arguments containing spaces.