Guia de JavaScript · 4/6

Modules and Packages

Por enquanto, este capítulo está disponível apenas em inglês.

As a program grows you split it into files and pull in libraries written by others. JavaScript has two module systems: the standard ES modules (ESM) and CommonJS, which Node.js used for years before ESM existed. This chapter compares them and then covers npm, package.json, scripts and the basics of bundling.

ES modules

ES modules are part of the language standard and work in both browsers and Node.js. You export from one file and import in another. A file can have many named exports but only one default export.

// math.js
export const PI = 3.14159;

export function circleArea(r) {
  return PI * r * r;
}

export default function sum(...nums) {
  return nums.reduce((a, b) => a + b, 0);
}

// main.js
import sum, { circleArea, PI as pi } from "./math.js";
import * as math from "./math.js";

console.log(sum(1, 2, 3));  // 6
console.log(circleArea(2)); // 12.56636
console.log(pi === math.PI); // true

// dynamic import loads on demand and returns a Promise
const { readFile } = await import("node:fs/promises");

A few things set ES modules apart:

They always run in strict mode.
Static import declarations let tools drop unused code (tree shaking).
Top-level await is allowed.
In the browser you load them with <script type="module" src="main.js">, and relative imports must include the .js extension.

CommonJS

CommonJS uses require and module.exports. You will still meet it in plenty of packages and older projects.

// greet.cjs
function greet(name) {
  return `Hello, ${name}`;
}
module.exports = { greet };

// app.cjs
const { greet } = require("./greet.cjs");
const path = require("node:path");

console.log(greet("Mina"));
console.log(path.join("logs", "today.txt"));

Node.js decides how to treat a file with these rules:

File	Treated as
`.mjs`	ES module
`.cjs`	CommonJS
`.js` with `"type": "module"` in the nearest `package.json`	ES module
`.js` with no `"type"` or `"commonjs"`	CommonJS

For new projects, set "type": "module" and write ESM. ES modules can import CommonJS packages; going the other way, a dynamic import() is the most reliable route. Prefix built-ins with node: (, ) so they never get confused with npm packages.

Dúvidas sobre este capítulo?

Tool	Known for
Vite	Fast dev server and minimal config; a common default for new apps
esbuild	Extremely fast bundling and transforms
Rollup	Clean output for publishing libraries
webpack	Long track record and a huge plugin ecosystem

Modules and Packages

ES modules

CommonJS

npm and package.json

Running scripts

Bundling basics

Summary

0 comentários