Publishing a TypeScript Library to npm for Node.js and Browser with Proper CommonJS and ES Module Support

Publishing a TypeScript library suitable for both Node.js and browser environments with clean CommonJS and ES Module support can seem tricky at first, but it’s simpler than you might imagine. Doing this right ensures your module is easy to use across projects, enhancing its reach and usability.

Let’s demystify the process step-by-step, so you learn exactly how to prepare, package, and publish your TypeScript library efficiently on npm.

Setting Up TypeScript for Compiling ES Modules and CommonJS Outputs

Your first important step is configuring the tsconfig.json file. Think of this file like an instruction manual for TypeScript compiler, directing how your code should be compiled. Here’s a clear explanation of key configuration options you should know about:

• target: Sets the JavaScript language version output. Using “ES2019” or “ES2020” is typically safe and modern.
• module: Determines the type of JavaScript module generated. To support both formats, you’ll actually create two separate tsconfig files—one for “CommonJS” and another for “ESNext”.
• moduleResolution: Ensures dependency resolution works correctly; “Node” is the recommended and standard option.
• declaration: Choose “true” to generate declaration files (.d.ts). These files allow developers using your library to benefit from strong typing and rich IDE support.
• outDir: Clearly separates compiled JS files from your source to keep code organized. Typically “./dist” or “./lib” works well.
• rootDir: Indicates the directory that contains your source code (usually “./src”).
• strict: Enables stronger type-checking—highly recommended for catching issues early and ensuring robust code.
• esModuleInterop: Helps achieve compatibility between CommonJS and ES modules for easier imports and smoother integrations.
• isolatedModules: Recommended by frameworks like React and tooling such as Vite and Vitest to avoid surprising compile results.
• skipLibCheck: Set this true to skip checking type declarations from external libraries, improving type-check speed significantly.
• forceConsistentCasingInFileNames: Guards against file path casing issues across operating systems.

Here’s an example tsconfig.json snippet that demonstrates common recommended settings for publishing to npm:

{
  "compilerOptions": {
    "target": "ES2019",
    "module": "CommonJS",
    "moduleResolution": "Node",
    "declaration": true,
    "outDir": "./lib",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "isolatedModules": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "**/*.test.ts"]
}

Remember to configure a second tsconfig (like tsconfig.esm.json) with “module” set to “ESNext” for generating modern ESM modules. These two builds will cover consuming projects that prefer either CommonJS or ESM modules seamlessly.

Configuring package.json for Proper CommonJS and ES Module Support

Your package.json setup is equally critical. It clearly instructs developers’ bundlers and build systems how to identify your library, how to import it, and what types are available.

Let’s break down some of the key fields you need in package.json and clarify their roles:

• name: Must be unique across npm. Check npmJS to confirm availability.
• version: Use semantic versioning (e.g., 1.0.0). Check the rules on Semantic Versioning that npm follows closely.
• description: Short and clear—affects npm search visibility.
• type: Set to “module” to use ESM by default, or “commonjs” to default to CJS. This significantly influences how users can import your library.
• main: Path to CommonJS version (e.g., “lib/index.js”), essential for older projects still using CJS.
• types: Path to type definitions (.d.ts file), crucial for developers utilizing VSCode and similar IDEs for smooth type integration.
• keywords: Essential keywords improve searchability on npm registry (include terms like “typescript,” “browser,” “nodejs”).
• files: Specifies precisely what files npm publishes. Keep distribution files minimal.
• devDependencies: Dependencies needed only during development (like TypeScript, Vitest).
• peerDependencies: Dependencies expected to be installed by users of your library, such as popular frameworks React or Express.
• scripts: Automates common actions like build (“tsc -p tsconfig.json && tsc -p tsconfig.esm.json”), test (“vitest”), publish (“npm publish”).
• author: Showcase yourself or your organization clearly and publicly.

A simplified example structure might look like this:

{
  "name": "my-awesome-library",
  "version": "1.0.0",
  "description": "A reliable TypeScript library for Node.js and browser",
  "type": "module",
  "main": "./lib/index.cjs.js",
  "module": "./lib/index.esm.js",
  "types": "./lib/index.d.ts",
  "keywords": ["typescript", "library", "browser", "nodejs"],
  "files": ["lib/**/*"],
  "scripts": {
    "build": "tsc -p tsconfig.json && tsc -p tsconfig.esm.json",
    "test": "vitest",
    "publish": "npm publish"
  },
  "peerDependencies": {
    "react": "^18.0.0"
  },
  "author": "Your Name",
  "devDependencies": {
    "typescript": "^5.0.0",
    "vitest": "^1.0.4"
  }
}

Building the Library Without Additional External Development Packages

Dependency management is important to ensure your library remains lightweight and quick-to-install. Limit dependencies wherever possible, only explicitly defining crucial peer dependencies such as React or specific Node.js versions.

Here’s how you efficiently build and test without heavy tooling overhead:

1. Simply run your defined build script with:

   npm run build

2. Run tests using Vitest:

   npm run test

3. Check test coverage to ensure everything’s thoroughly tested.

Vitest is an impressive test runner optimized for TypeScript, improving the development productivity significantly. With minimal overhead, it speeds your test cycles wonderfully.

Now you’ve built an efficient and robust library. Time to publish:

npm run publish

Remember to check your .npmignore or files section before publishing to avoid accidentally bundling unnecessary files.

Publishing a robust TypeScript library supporting both Node.js and browsers might have seemed daunting initially. However, now you see, it’s simply a matter of solid configuration, smart package.json structuring, and efficient dependency management.

Getting these technical details right lifts your package quality, increases adoption potential, and offers a polished, professional experience for developers worldwide.

Ready to publish your next TypeScript library and grow your open-source portfolio? Let the world discover your well-prepared module—happy publishing!