如何基于单一代码库将简单文件封装为兼容浏览器、NodeJS及SPA的NPM工具库

Great question! Let's break this down step by step—first clearing up your import/require confusion, then walking through how to package your single utility file into a library that works everywhere.

First: How do import and require find your library files? #

You’re right to wonder about the lookup logic—it’s not just about index.js! The real control comes from fields in your library’s package.json:

• For SPA/ES Module environments (import { abc } from 'library'): Tools like webpack, Vite, or Rollup will first check the module field in your package.json (if present). This points to your ES module bundle. If module isn’t set, they’ll fall back to the main field or look for index.js.
• For Node.js CommonJS environments (let lib = require('library')): Node will default to the main field in your package.json. If you’re using modern Node with ES modules enabled (via "type": "module" in your library’s package.json), it might behave differently—but we’ll avoid relying on that for broad compatibility.
• Modern, granular control: The exports field in package.json lets you explicitly define entry points for different scenarios (e.g., separate paths for import vs require, or browser vs Node). This is the most flexible approach for modern libraries.

Example snippet for package.json:

{
  "main": "./dist/index.cjs.js", // CommonJS for Node
  "module": "./dist/index.esm.js", // ES Module for bundlers
  "browser": "./dist/index.umd.js", // UMD for browser globals
  "exports": {
    ".": {
      "import": "./dist/index.esm.js",
      "require": "./dist/index.cjs.js"
    }
  }
}

Do you need to write different code for different environments? #

Nope! You don’t have to maintain separate codebases. The key is to write your utility in standard ES6+ syntax (using export statements like you already are), then use a bundler to compile it into multiple formats that work across environments.

Step-by-Step Guide to Package Your Utility #

Let’s use Rollup (ideal for library bundling, lighter than Webpack for this use case) to build your single file into cross-compatible bundles:

1. Initialize your NPM project #

In a new folder for your library:

npm init -y

Fill in the project details (name, version, description, etc.) when prompted.

2. Install Rollup and plugins #

We’ll need Rollup plus plugins to handle any transpilation (if needed) and resolve imports:

npm install rollup @rollup/plugin-babel @rollup/plugin-node-resolve --save-dev

• @rollup/plugin-node-resolve: Helps Rollup find external dependencies (if your utility uses any)
• @rollup/plugin-babel: Transpiles ES6+ code to older syntax for broader compatibility (optional but recommended if you use modern features)

3. Create a Rollup config file #

Create rollup.config.js in your project root:

import resolve from '@rollup/plugin-node-resolve';
import babel from '@rollup/plugin-babel';

export default {
  input: './src/your-utility-file.js', // Path to your original helper file
  output: [
    // CommonJS bundle for Node.js
    {
      file: './dist/index.cjs.js',
      format: 'cjs'
    },
    // ES Module bundle for bundlers (SPA, Vite, Webpack)
    {
      file: './dist/index.esm.js',
      format: 'es'
    },
    // UMD bundle for browser globals (e.g., <script> tag)
    {
      file: './dist/index.umd.js',
      format: 'umd',
      name: 'YourLibraryName' // Global variable name for browser use
    }
  ],
  plugins: [
    resolve(),
    babel({ babelHelpers: 'bundled' }) // Transpile code if needed
  ]
};

4. Add build scripts to package.json #

Update your package.json to include a build command:

{
  "scripts": {
    "build": "rollup -c"
  }
}

Run npm run build to generate your bundles in the dist folder.

5. Test your library locally #

Before publishing, test it in different environments:

• Node.js: Create a test file with const { abc } = require('./dist/index.cjs.js') and run it with Node.
• SPA: Import it into a React project with import { abc } from '../path/to/your-library/dist/index.esm.js' and verify it works.
• Browser: Add a <script src="./dist/index.umd.js"></script> tag to an HTML file, then access window.YourLibraryName.abc in the console.

6. Publish to NPM #

Once you’re satisfied, publish your library:

npm publish

Make sure you’ve logged into NPM first (npm login).

Final Notes #

• .gitignore: Don’t forget to add node_modules/ and dist/ to your .gitignore so they aren’t committed.
• TypeScript (optional): If you want to add type definitions, create a index.d.ts file and point to it in your package.json with the types field.
• Keep it simple: Since your utility is a single file, you won’t need complex configurations—this setup will cover all major environments (Node, SPA, browsers).

内容的提问来源于stack exchange，提问作者Sayed Muhammad Talha