ES modules and npm: organizing your project

You structure a Node project with package.json, ES modules, npm dependencies, and scripts.

9 min · 3 questions

A real project doesn't fit in a single file: you split it into modules, files that export what they offer and import what they need. You already know the import / export syntax from the JavaScript track; let's see how Node enables it. It all starts with package.json, your project's ID card: a file in JSON format that describes its name, its version, and its settings. To create it, move into an empty folder and run npm init -y (the -y option accepts all the default answers). Then add the line "type": "module": it tells Node that your .js files use ES modules.

JSON

{
  "name": "my-project",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "start": "node main.js",
    "dev": "node --watch main.js"
  }
}

Your package.json after npm init -y, completed with the type line and two scripts we'll use below.

Let's create two files in this folder: math.js exports a function, main.js imports it. A detail specific to Node: importing a local file must begin with ./ and end with the .js extension. Both are required, unlike what some web tools tolerate.

JAVASCRIPT

// math.js
export function add(a, b) {
  return a + b;
}

// main.js
import { add } from "./math.js";

console.log(add(2, 3));

Two separate files. Run node main.js: the result 5 appears.

npm's great strength is its worldwide library of packages: code written by others, ready to use. The npm install command downloads a package into your project's node_modules folder and adds it to the dependencies section of package.json: the list of packages your project needs to work. A package-lock.json file, created automatically, records the exact versions installed, so everyone gets the same thing. Let's try with chalk, a package that colors the text shown in the terminal.

BASH

npm install chalk

After this command, chalk appears in dependencies and in node_modules; you can then import it like any module.

One last pillar: npm scripts, command shortcuts declared in the scripts section of package.json. npm run dev runs the command saved under the name dev, however long the real command may be. Our dev script uses node --watch, an option that automatically restarts the program every time a file changes: very comfortable during development.

BASH

npm run start
npm run dev

Each command runs the script of the same name. Stop watch mode with Ctrl+C.

Never edit the contents of node_modules and don't send it to Git: this folder regenerates identically with a simple npm install, thanks to package.json and package-lock.json. Add the line node_modules to your .gitignore file.

Knowledge check

Make sure you remember the key points of this lesson.

What is the role of the package.json file?
- Describe the project: name, version, scripts, and dependencies
- Contain the project's main JavaScript code
- Store the code of the downloaded packages
- Replace the node_modules folder
What happens when you run npm install chalk?
- chalk is copied directly into your main.js file
- chalk is only downloaded, without leaving a trace
- chalk is placed in node_modules and added to dependencies
Why add the type module line in package.json?
- So npm installs packages faster
- So Node reads .js files as ES modules (import/export)
- To publish the project on npm automatically