将Next.js项目转为NPM包时遇模块解析失败问题求助

核心问题原因 #

1. 未编译源码直接发布：你的原项目tsconfig.json中设置了"noEmit": true，这意味着TypeScript不会将TS/TSX文件编译成可执行的JS代码。发布到NPM的是未处理的源码，其他Next.js项目的Webpack无法解析其中的JSX语法和TypeScript特性，导致Module parse failed错误。
2. 依赖管理混乱：所有依赖都放在dependencies中，包括React、Next.js、Radix UI这类应该由宿主项目提供的包，既会导致重复安装，也可能引发版本冲突。
3. 路径别名未处理：组件中使用的@/*路径别名在发布后未被转换为相对路径，宿主项目无法识别该别名。

分步解决方案 #

1. 调整TypeScript配置（tsconfig.json） #

修改配置以生成编译产物和类型声明：

{
  "compilerOptions": {
    "target": "ES2018",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": false,
    "esModuleInterop": true,
    "module": "ESNext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "react-jsx",
    "declaration": true,
    "declarationDir": "./dist/types",
    "outDir": "./dist",
    "baseUrl": "./src",
    "paths": {
      "@/*": ["*"]
    }
  },
  "include": ["src/**/*.ts", "src/**/*.tsx"],
  "exclude": ["node_modules", "dist"]
}

2. 使用tsup打包组件库 #

tsup可以快速处理TS/TSX编译、路径别名转换和多格式输出，无需复杂配置：

• 安装依赖：

npm install tsup --save-dev

• 创建tsup.config.ts：

import { defineConfig } from 'tsup';

export default defineConfig({
  entry: ['src/index.ts'], // 替换为你的组件入口文件，需导出所有要发布的组件
  format: ['cjs', 'esm'], // 同时输出CommonJS和ES模块
  dts: true, // 自动生成类型声明
  sourcemap: true,
  clean: true,
  external: ['react', 'react-dom', 'next', 'tailwindcss', '@radix-ui/react-*', 'lucide-react'] // 这些依赖由宿主项目提供，不打包进库
});

3. 修改package.json配置 #

• 分离peerDependencies：声明宿主项目必须提供的依赖，避免重复安装
• 指定产物入口和发布文件
• 添加库构建脚本

{
  "name": "atikdev-npm-pages",
  "version": "1.0.6",
  "description": "Description of your private package",
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
  "types": "./dist/types/index.d.ts",
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "build:lib": "tsup", // 新增组件库构建命令
    "start": "next start",
    "lint": "next lint"
  },
  "files": ["dist"], // 只发布编译后的产物文件夹
  "peerDependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "next": "^13.0.0",
    "tailwindcss": "^3.0.0",
    "@radix-ui/react-checkbox": "^1.0.0",
    "@radix-ui/react-label": "^2.0.0"
  },
  "dependencies": {
    // 只保留组件自身必需的工具类依赖
    "class-variance-authority": "^0.7.0",
    "clsx": "^2.0.0",
    "tailwind-merge": "^1.14.0"
  },
  "devDependencies": {
    // 保留原有开发依赖，新增tsup
    "tsup": "^7.2.0",
    // ...其他原有dev依赖
  }
}

4. 构建并发布 #

• 先执行构建命令生成产物：

npm run build:lib

• 发布到NPM：

npm publish

5. 宿主项目适配（若仍有问题） #

在新Next.js项目的next.config.js中添加包转译配置：

/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ['atikdev-npm-pages'],
};

module.exports = nextConfig;

内容的提问来源于stack exchange，提问作者Yassine Atik