开发npm组件库时，如何基于tsconfig的baseUrl/paths编译TS模块？

Great question! I’ve built a handful of ES module-first component libraries distributed via npm, so I can walk you through exactly how to set this up to work seamlessly—both for your own development workflow and for consumers of your library.

Step 1: Set Up baseUrl & paths in tsconfig.json #

First, configure your root tsconfig.json to enable short, clean imports during development. Here’s a minimal, working config tailored to your needs:

{
  "compilerOptions": {
    "baseUrl": ".", // Anchor all paths to your project root
    "paths": {
      "components/*": ["src/components/*"], // Map nested component imports
      "components": ["src/components/index.ts"] // Map direct `import from 'components'`
    },
    // Critical for ES module output
    "module": "ESNext",
    "moduleResolution": "NodeNext",
    // Generate type declarations for TypeScript consumers
    "declaration": true,
    // Output compiled files to a dist folder (keeps source clean)
    "outDir": "./dist",
    // Define your source root to ensure proper file structure in dist
    "rootDir": "./src",
    "strict": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

The module and moduleResolution settings are non-negotiable here—they ensure TypeScript outputs standard ES modules that align with your goal of distributing unbundled, standalone modules.

Step 2: Update Your Root index.ts Re-exports #

With the paths configured, you can use the clean imports in your root index.ts (your library’s main entry point) too:

// Clean, readable re-exports
export * from 'components/Button';
export * from 'components/Input';
// Or re-export the entire components entry if you have one
export * from 'components';

When you run tsc, TypeScript will automatically transpile these short paths into relative paths in the compiled dist files—no manual path rewriting needed.

Step 3: Configure package.json for Proper npm Distribution #

Since you’re distributing compiled ES modules (not raw source or bundled files), your package.json needs clear entry points and metadata:

{
  "name": "your-custom-components",
  "version": "1.0.0",
  // Tell Node.js this is an ES module package
  "type": "module",
  // Main entry for CommonJS environments (fallback)
  "main": "./dist/index.js",
  // Explicit ES module entry
  "module": "./dist/index.js",
  // Point to your generated type declarations
  "types": "./dist/index.d.ts",
  // Only publish the dist folder (avoids shipping source files unnecessarily)
  "files": ["dist"],
  "scripts": {
    "build": "tsc" // Simple build command to compile with TypeScript
  }
}

The type: "module" field is crucial—it prevents module resolution errors when consumers import your library in ES module projects.

Step 4: Validate & Test #

1. Check Compiled Output: Run npm run build, then inspect files in the dist folder. You’ll see that all short components/... imports have been converted to relative paths (like ./components/Button.js) in the compiled JS and type declaration files.
2. Local Testing: Use npm link to test your library locally in another project. In the test project, you can import directly:

   import { Button } from 'your-custom-components';
   

   For local development with hot reloading, you can even configure the test project’s tsconfig.json to map your library’s source files:

   {
     "compilerOptions": {
       "baseUrl": ".",
       "paths": {
         "your-custom-components": ["../your-library/src"],
         "your-custom-components/*": ["../your-library/src/*"]
       }
     }
   }
   

Common Pitfalls to Avoid #

• Don’t clash with npm package names: If your library’s npm name is components, avoid using that as your path alias—this can cause resolution conflicts for consumers. Use a unique alias like @your-org/components instead.
• Always generate type declarations: Omitting declaration: true will leave TypeScript consumers without type hints, which is a big no-no for component libraries.
• Keep outDir/rootDir aligned: Misconfiguring these can lead to messy file structures in the dist folder, making it hard for consumers to import individual components.

This setup gives you the clean development workflow you want with baseUrl/paths, while ensuring your distributed library works flawlessly for all ES module consumers.

内容的提问来源于stack exchange，提问作者Dmitriy Kanatnikov