如何配置Tsup+React开发环境实现浏览器实时预览？

问题背景 #

使用Tsup构建TypeScript+React小型库，项目结构如下：

dist
  index.js
  index.mjs
src
  index.html
  App.tsx
  index.tsx
tsup.config.ts
tsconfig.json

执行npm run dev启动watch模式后，用live-server运行src/index.html，浏览器控制台报错：

Uncaught ReferenceError: require is not defined

尝试给script标签添加type="module"后问题仍未解决，需要配置开发环境实现实时预览代码变更。

核心问题分析 #

1. external配置导致未打包React：tsup配置中把react设为external，打包后的CommonJS格式产物（dist/index.js）保留了require('react')语法，但浏览器原生不支持CommonJS的require。
2. 模块格式与引入不匹配：虽然生成了ES模块格式的index.mjs，但未打包的外部依赖无法被浏览器解析，导致模块加载失败。

具体修复步骤 #

1. 差异化配置Tsup开发/生产环境 #

修改tsup.config.ts，开发环境打包React到产物中，仅生产环境external依赖：

import { defineConfig } from "tsup";

export default defineConfig(({ watch }) => ({
  minify: !watch, // 开发环境不压缩代码
  target: "es2015",
  external: watch ? [] : ["react"], // 开发打包React，生产排除React
  sourcemap: true,
  dts: !watch, // 开发环境不生成类型文件提升速度
  format: ["esm"], // 开发环境仅输出ES模块格式
  injectStyle: true,
  esbuildOptions(options) {
    options.banner = {
      js: '"use client"',
    };
  },
}));

2. 调整index.html路径与模块引入 #

将src/index.html移动到项目根目录（避免跨目录路径问题），修改script标签为ES模块引入：

<body>
    <div id="root"></div>
    <script type="module" src="./dist/index.mjs"></script>
</body>

3. 优化开发脚本，结合watch与静态服务器 #

先安装静态服务器工具serve：

npm install -D serve

修改package.json的scripts，让tsup监听变更后自动启动静态服务器：

"scripts": {
    "build": "tsup src/index.tsx",
    "dev": "tsup src/index.tsx --watch --onSuccess \"serve .\"",
    "format": "prettier --write ."
}

4. 适配tsconfig的模块配置 #

修改tsconfig.json，让TypeScript输出适配浏览器的ES模块：

{
  "compilerOptions": {
    "jsx": "react",
    "target": "es2015",
    "module": "ESNext",
    "moduleResolution": "bundler", // 适配tsup/esbuild的模块解析逻辑
    "lib": ["es2015", "dom"],
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

验证运行 #

执行npm run dev，tsup会监听文件变更自动重新打包，同时启动静态服务器。打开浏览器访问服务器地址后，修改App.tsx等文件，刷新浏览器即可看到实时变更。

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