Publishing your first JavaScript library can be a minefield of confusing `package.json` fields and module formats. We break down the common pitfalls and give you a clear, modern roadmap from a simple script to a production-ready package.

Your JavaScript Library is Broken, and It’s Probably `package.json`’s Fault

I remember a frantic Tuesday morning. Alarms were blaring in Slack. Our main deployment pipeline, the one for “Project Phoenix,” was completely busted. Builds were failing with cryptic `SyntaxError: Unexpected token ‘export’` messages. After 30 minutes of digging through logs on `ci-runner-03`, we traced it back to a tiny, seemingly innocent update to an internal utility library. A junior dev, trying to be helpful, had modernized the syntax to use ES Modules but forgot one tiny, crucial detail: the build step. The `package.json` was pointing directly at an un-transpiled `index.mjs` file, and our older Node.js-based tooling fell apart. It’s a classic mistake, one I see all the time, born from the messy history of JavaScript modules. Let’s make sure it doesn’t happen to you.

The “Why”: A Tale of Two Module Systems

The root of this problem is simple: JavaScript wasn’t originally designed with a module system. For years, we relied on hacks. Then, two major standards emerged:

• CommonJS (CJS): The system Node.js created. You know it by its signature require() and module.exports. It’s synchronous, which works great on a server.
• ES Modules (ESM): The official standard introduced in ES6. This is the import and export syntax you see everywhere now. It’s asynchronous and is the native standard in modern browsers.

For a library author, this is a nightmare. You have to create a package that works for a modern Vite/React app using import, but also for an older Node.js script using require(). Your package.json is the map that tells these different environments which file to load. Get it wrong, and everything breaks.

The Fixes: From Duct Tape to a Solid Foundation

I’ve seen this problem “solved” in a dozen different ways. Here are the three main approaches, from a quick fix to the way we do it for our production services at TechResolve.

Solution 1: The Quick & Dirty Fix (But It’ll Ship)

Let’s say you just have a single JavaScript file, MyCardGame.js, and you want people to be able to use it. The fastest way is to stick with the oldest, most compatible format: CommonJS. You don’t get the fancy import syntax, but it will work almost everywhere.

First, make sure your code uses CommonJS syntax:

// MyCardGame.js

function shuffleDeck() {
  // ... your logic
  return ['Ace', 'King', 'Queen'];
}

function dealCard(deck) {
  // ... your logic
  return deck.pop();
}

module.exports = { shuffleDeck, dealCard };

Then, update your package.json to point the main field directly to this file:

{
  "name": "fun-card-game",
  "version": "1.0.0",
  "description": "A fun card game library!",
  "main": "MyCardGame.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": ["card", "game", "javascript"],
  "author": "Your Name",
  "license": "MIT"
}

Is it hacky? Yes. It forces everyone, even those with modern tools, to use require(). It has no build step, so you can’t use TypeScript, JSX, or any modern features. But if you have a simple script and need it published now, this will get the job done.

Pro Tip: Before you ever run npm publish, test your package locally! In your library’s directory, run npm link. Then, in a separate test project, run npm link fun-card-game. This creates a symlink and lets you test your package as if it were installed from NPM, saving you the embarrassment of publishing a broken version.

Solution 2: The Permanent Fix (The “Right” Way)

The modern, professional way is to write your code in modern JavaScript (or TypeScript) and use a bundler like Rollup or Vite to generate multiple output formats. This gives your users the best of all worlds.

Your goal is to configure a build process that outputs at least two files:

• An ES Module file (e.g., dist/index.mjs)
• A CommonJS file (e.g., dist/index.cjs)

Then, you use the "exports" field in package.json to conditionally tell different environments which file to use. This is the new standard and replaces the old "main", "module", and "browser" fields.

Your package.json would look something like this:

{
  "name": "fun-card-game",
  "version": "1.0.0",
  "type": "module",
  "files": ["dist"],
  "main": "./dist/index.cjs",
  "module": "./dist/index.mjs",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  },
  "scripts": {
    "build": "vite build",
    "dev": "vite"
  }
}

Here’s a breakdown of what those important fields in the exports object mean:

Key	Purpose
"exports"	The main entry point for defining module resolution. This is the new standard.
"."	Defines the main entry point. E.g., import game from 'fun-card-game';
"import"	The file to use when a consumer uses an import statement (ESM).
"require"	The file to use when a consumer uses a require() call (CommonJS).

This approach requires setting up a build tool, but it’s the gold standard. It ensures your library is fast, compatible, and future-proof.

Solution 3: The ‘Nuclear’ Option (Use a Scaffolding Tool)

Sometimes you just want to write code, not spend a day fighting with bundler configs. I get it. My time is valuable, and so is yours. In these cases, just use a tool that sets everything up for you.

Vite is fantastic for this. You can scaffold a new library project with one command, and it comes with TypeScript, a dev server, and a pre-configured build process out of the box.

Just run this command:

npm create vite@latest my-card-game -- --template vanilla-ts

Then, you’ll need to make a small change to the generated vite.config.ts file to enable “library mode”:

// vite.config.ts
import { resolve } from 'path'
import { defineConfig } from 'vite'

export default defineConfig({
  build: {
    lib: {
      // Could also be a dictionary or array of multiple entry points
      entry: resolve(__dirname, 'src/main.ts'),
      name: 'MyCardGame',
      // the proper extensions will be added
      fileName: 'my-card-game',
    },
  },
})

When you run npm run build, Vite will automatically generate CJS, ESM, and even UMD bundles for you, along with the correct file structure. All you have to do is wire them up in your package.json as shown in Solution 2. This is the fastest way to get a production-grade library setup without the headache.

Final Warning: Whichever path you choose, use a tool like publint (npx publint) to check your `package.json` before publishing. It’s a lifesaver and will catch many of these common module resolution issues before they cause a production outage on a Tuesday morning.

---

🤖 Frequently Asked Questions