DEV Community

Mohamed Idris
Mohamed Idris

Posted on

What does "type" in package.json actually do?

#beginners #javascript #webdev #node

If you have ever opened a package.json and seen something like this:

{
  "type": "module"
}
Enter fullscreen mode Exit fullscreen mode

and wondered what it actually does, this post is for you. We will keep things simple and stick to what a beginner needs to know.

Two ways to share code in JavaScript

JavaScript has two systems for splitting code across files. They both do the same job, but they look different and behave differently under the hood.

CommonJS (the older way)

// math.js
function add(a, b) {
  return a + b;
}
module.exports = { add };
Enter fullscreen mode Exit fullscreen mode 
// app.js
const { add } = require("./math.js");
console.log(add(2, 3));
Enter fullscreen mode Exit fullscreen mode

ES Modules, also called ESM (the modern way)

// math.js
export function add(a, b) {
  return a + b;
}
Enter fullscreen mode Exit fullscreen mode 
// app.js
import { add } from "./math.js";
console.log(add(2, 3));
Enter fullscreen mode Exit fullscreen mode

CommonJS uses require and module.exports. ESM uses import and export. ESM is the official standard for JavaScript today, and browsers only understand ESM. Node.js still supports both because CommonJS was around first and a huge amount of code is still written that way.

So how does Node know which one your file is?

This is where the type field comes in. When Node looks at a .js file, it needs to decide: do I treat this as CommonJS or as ESM? It checks the closest package.json and looks at the type field.

  • "type": "commonjs" or no type field at all means your .js files are CommonJS.
  • "type": "module" means your .js files are ESM.

That single line flips the switch for the whole project.

A small example

Imagine a fresh project with this package.json:

{
  "name": "hello",
  "version": "1.0.0"
}
Enter fullscreen mode Exit fullscreen mode

There is no type field, so Node defaults to CommonJS. If you write this:

// index.js
import { readFile } from "node:fs";
Enter fullscreen mode Exit fullscreen mode

and run node index.js, you get an error that says something like "Cannot use import statement outside a module". Node is telling you that this file is CommonJS, and import is not allowed in CommonJS.

Two fixes:

  1. Use require instead.
  2. Add "type": "module" to your package.json.

If you go with option 2, your import line works and the project is now an ESM project.

What about TypeScript?

TypeScript follows the same rule when you use modern settings. If your tsconfig.json has "module": "nodenext", then a .ts file is treated as ESM or CommonJS based on the same type field in package.json. So adding "type": "module" affects your .ts files too, not just your .js files.

File extensions are an escape hatch

If you want to mix and match, Node also lets you force a specific style with a file extension:

  • .mjs is always ESM.
  • .cjs is always CommonJS.
  • .mts is always ESM (TypeScript).
  • .cts is always CommonJS (TypeScript).

These override whatever the package.json says. Most projects do not need this, but it is handy when you have one stubborn file.

Which one should you pick?

For a brand new project in 2026, go with ESM. Set "type": "module" and use import and export everywhere. It is the standard, it works in browsers, and the rest of the ecosystem is moving in that direction.

You will still run into CommonJS in older tutorials and libraries, so it is good to recognize both. But for the code you write today, ESM is the safe default.

Quick recap

  • CommonJS uses require and module.exports.
  • ESM uses import and export.
  • The type field in package.json tells Node which one your .js and .ts files are.
  • No type field means CommonJS.
  • "type": "module" means ESM.
  • For new projects, go with ESM.

That is really all there is to it. Once you see the type field for what it is, a one line switch between two module systems, the rest of the confusion tends to fade.

Top comments (0)