Rollup 最佳实践 #

my-library/
├── src/
│   ├── index.ts           # 入口文件
│   ├── components/        # 组件目录
│   │   ├── index.ts
│   │   ├── Button.ts
│   │   └── Input.ts
│   ├── utils/             # 工具函数
│   │   ├── index.ts
│   │   └── helpers.ts
│   └── types/             # 类型定义
│       └── index.ts
├── dist/                  # 输出目录
│   ├── my-lib.cjs.js      # CommonJS
│   ├── my-lib.esm.js      # ES Module
│   ├── my-lib.umd.js      # UMD
│   └── my-lib.d.ts        # 类型声明
├── tests/                 # 测试文件
├── rollup.config.js       # Rollup 配置
├── tsconfig.json          # TypeScript 配置
└── package.json           # 包配置

{
  "name": "my-library",
  "version": "1.0.0",
  "description": "A modern JavaScript library",
  "type": "module",
  "main": "dist/my-lib.cjs.js",
  "module": "dist/my-lib.esm.js",
  "browser": "dist/my-lib.umd.js",
  "types": "dist/my-lib.d.ts",
  "exports": {
    ".": {
      "import": "./dist/my-lib.esm.js",
      "require": "./dist/my-lib.cjs.js",
      "browser": "./dist/my-lib.umd.js",
      "types": "./dist/my-lib.d.ts"
    },
    "./style.css": "./dist/style.css"
  },
  "files": [
    "dist",
    "README.md"
  ],
  "sideEffects": [
    "*.css",
    "*.scss"
  ],
  "keywords": ["javascript", "library"],
  "author": "Your Name",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/user/my-library"
  },
  "scripts": {
    "dev": "rollup -c -w",
    "build": "rollup -c",
    "test": "vitest",
    "lint": "eslint src",
    "prepublishOnly": "npm run build"
  },
  "peerDependencies": {
    "react": ">=16.8.0",
    "react-dom": ">=16.8.0"
  },
  "devDependencies": {
    "rollup": "^4.0.0",
    "@rollup/plugin-node-resolve": "^15.0.0",
    "@rollup/plugin-commonjs": "^25.0.0",
    "@rollup/plugin-typescript": "^11.0.0",
    "@rollup/plugin-terser": "^0.4.0",
    "typescript": "^5.0.0"
  }
}

import resolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';
import typescript from '@rollup/plugin-typescript';
import terser from '@rollup/plugin-terser';
import dts from 'rollup-plugin-dts';

const isProduction = process.env.NODE_ENV === 'production';

const config = [
  {
    input: 'src/index.ts',
    output: [
      {
        file: 'dist/my-lib.cjs.js',
        format: 'cjs',
        sourcemap: true,
        exports: 'named'
      },
      {
        file: 'dist/my-lib.esm.js',
        format: 'es',
        sourcemap: true
      }
    ],
    external: ['react', 'react-dom'],
    plugins: [
      resolve({
        extensions: ['.ts', '.tsx', '.js', '.jsx']
      }),
      commonjs(),
      typescript({
        tsconfig: './tsconfig.json',
        declaration: true,
        declarationDir: 'dist/types'
      }),
      isProduction && terser()
    ].filter(Boolean)
  },
  {
    input: 'dist/types/index.d.ts',
    output: {
      file: 'dist/my-lib.d.ts',
      format: 'es'
    },
    plugins: [dts()]
  }
];

if (isProduction) {
  config.push({
    input: 'src/index.ts',
    output: {
      file: 'dist/my-lib.umd.js',
      format: 'umd',
      name: 'MyLib',
      sourcemap: true,
      globals: {
        react: 'React',
        'react-dom': 'ReactDOM'
      }
    },
    external: ['react', 'react-dom'],
    plugins: [
      resolve({
        extensions: ['.ts', '.tsx', '.js', '.jsx']
      }),
      commonjs(),
      typescript({
        tsconfig: './tsconfig.json'
      }),
      terser()
    ]
  });
}

export default config;

// src/index.ts
export { Button } from './components/Button';
export { Input } from './components/Input';
export { formatDate, debounce } from './utils/helpers';

export type { ButtonProps } from './components/Button';
export type { InputProps } from './components/Input';

my-app/
├── src/
│   ├── main.js            # 入口文件
│   ├── App.js             # 主应用
│   ├── components/        # 组件
│   ├── pages/             # 页面
│   ├── utils/             # 工具
│   ├── styles/            # 样式
│   └── assets/            # 静态资源
├── public/
│   └── index.html
├── dist/
├── rollup.config.js
└── package.json

import resolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';
import babel from '@rollup/plugin-babel';
import postcss from 'rollup-plugin-postcss';
import serve from 'rollup-plugin-serve';
import livereload from 'rollup-plugin-livereload';

export default {
  input: 'src/main.js',
  output: {
    file: 'dist/bundle.js',
    format: 'iife',
    name: 'App',
    sourcemap: true
  },
  plugins: [
    resolve({
      browser: true
    }),
    commonjs(),
    babel({
      babelHelpers: 'bundled',
      exclude: 'node_modules/**'
    }),
    postcss({
      extract: true,
      minimize: false,
      sourceMap: true
    }),
    serve({
      contentBase: ['dist', 'public'],
      port: 3000,
      open: true
    }),
    livereload({
      watch: 'dist'
    })
  ],
  watch: {
    clearScreen: false,
    include: 'src/**'
  }
};

import resolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';
import babel from '@rollup/plugin-babel';
import postcss from 'rollup-plugin-postcss';
import terser from '@rollup/plugin-terser';
import { visualizer } from 'rollup-plugin-visualizer';
import copy from 'rollup-plugin-copy';
import del from 'rollup-plugin-delete';

export default {
  input: 'src/main.js',
  output: {
    dir: 'dist',
    format: 'es',
    entryFileNames: '[name].[hash].js',
    chunkFileNames: 'chunks/[name].[hash].js',
    assetFileNames: 'assets/[name].[hash][extname]',
    sourcemap: true,
    manualChunks: {
      vendor: ['react', 'react-dom', 'react-router-dom']
    }
  },
  plugins: [
    del({ targets: 'dist/*' }),
    copy({
      targets: [
        { src: 'public/index.html', dest: 'dist' }
      ]
    }),
    resolve({
      browser: true
    }),
    commonjs(),
    babel({
      babelHelpers: 'bundled',
      exclude: 'node_modules/**'
    }),
    postcss({
      extract: 'style.css',
      minimize: true
    }),
    terser({
      compress: {
        drop_console: true,
        drop_debugger: true
      }
    }),
    visualizer({
      filename: 'dist/stats.html',
      gzipSize: true
    })
  ]
};

export default {
  external: (id) => {
    // 排除所有 node_modules
    if (id.includes('node_modules')) {
      return true;
    }
    
    // 排除特定大型库
    const largeLibs = ['lodash', 'moment', 'axios'];
    return largeLibs.some(lib => id.startsWith(lib));
  }
};

export default {
  output: {
    manualChunks(id) {
      // 第三方库分割
      if (id.includes('node_modules')) {
        // React 生态
        if (id.includes('react') || id.includes('react-dom')) {
          return 'vendor-react';
        }
        
        // 工具库
        if (id.includes('lodash')) {
          return 'vendor-lodash';
        }
        
        // 其他第三方库
        return 'vendor';
      }
      
      // 业务代码分割
      if (id.includes('src/features/')) {
        const match = id.match(/src\/features\/([^/]+)/);
        if (match) {
          return `feature-${match[1]}`;
        }
      }
    }
  }
};

// 使用 ES 模块导入
import { debounce } from 'lodash-es';  // ✅ 支持 Tree-shaking

// 避免 CommonJS 导入
const _ = require('lodash');  // ❌ 不支持 Tree-shaking

// 使用具名导入
import { Button } from './components';  // ✅

// 避免命名空间导入
import * as Components from './components';  // ❌ 所有都会被打包

import terser from '@rollup/plugin-terser';

export default {
  plugins: [
    terser({
      compress: {
        drop_console: true,
        drop_debugger: true,
        pure_funcs: ['console.log', 'console.info'],
        passes: 3  // 多次压缩
      },
      mangle: {
        properties: {
          regex: /^_/,  // 混淆以 _ 开头的属性
          reserved: ['_id']  // 保留特定属性
        }
      },
      format: {
        comments: false  // 移除注释
      }
    })
  ]
};

// 问题
import lodash from 'lodash';  // 可能无法正确解析

// 解决方案
import resolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';

export default {
  plugins: [
    resolve({
      preferBuiltins: true
    }),
    commonjs({
      transformMixedEsModules: true
    })
  ]
};

// 问题
const module = await import(`./modules/${name}.js`);  // 可能无法解析

// 解决方案
import dynamicImportVars from '@rollup/plugin-dynamic-import-vars';

export default {
  plugins: [
    dynamicImportVars({
      include: ['src/**'],
      exclude: ['node_modules/**']
    })
  ]
};

// 问题：CSS 未被提取

// 解决方案
import postcss from 'rollup-plugin-postcss';

export default {
  plugins: [
    postcss({
      extract: true,  // 提取到单独文件
      minimize: true,
      sourceMap: true,
      extensions: ['.css', '.scss', '.sass', '.less']
    })
  ]
};

import url from '@rollup/plugin-url';
import image from '@rollup/plugin-image';

export default {
  plugins: [
    url({
      include: ['**/*.svg', '**/*.png', '**/*.jpg', '**/*.gif'],
      limit: 8192,  // 小于 8KB 转 Base64
      emitFiles: true,
      fileName: 'assets/[name]-[hash][extname]'
    }),
    image({
      exclude: ['node_modules/**']
    })
  ]
};

import { builtinModules } from 'module';
import resolve from '@rollup/plugin-node-resolve';

export default {
  external: [
    ...builtinModules,
    ...builtinModules.map(m => `node:${m}`)
  ],
  plugins: [
    resolve({
      preferBuiltins: true
    })
  ]
};

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "lib": ["ES2020", "DOM"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "declaration": true,
    "declarationDir": "dist/types",
    "outDir": "dist",
    "rootDir": "src",
    "sourceMap": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": false
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "tests"]
}

// src/types/index.ts
export interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'danger';
  size?: 'small' | 'medium' | 'large';
  disabled?: boolean;
  onClick?: (event: MouseEvent) => void;
  children: React.ReactNode;
}

export interface InputProps {
  value?: string;
  onChange?: (value: string) => void;
  placeholder?: string;
  disabled?: boolean;
  error?: string;
}

// vitest.config.js
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globals: true,
    environment: 'jsdom',
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json', 'html']
    }
  }
});

// tests/utils.test.js
import { describe, it, expect } from 'vitest';
import { formatDate, debounce } from '../src/utils';

describe('formatDate', () => {
  it('should format date correctly', () => {
    const date = new Date('2024-01-01');
    expect(formatDate(date)).toBe('2024-01-01');
  });
});

describe('debounce', () => {
  it('should debounce function calls', async () => {
    let count = 0;
    const fn = debounce(() => count++, 100);
    
    fn();
    fn();
    fn();
    
    expect(count).toBe(0);
    
    await new Promise(resolve => setTimeout(resolve, 150));
    
    expect(count).toBe(1);
  });
});

// package.json
{
  "scripts": {
    "release": "standard-version",
    "release:minor": "standard-version --release-as minor",
    "release:major": "standard-version --release-as major"
  }
}

// package.json
{
  "scripts": {
    "prepublishOnly": "npm run lint && npm test && npm run build",
    "prepack": "npm run build"
  }
}

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run tests
        run: npm test
      
      - name: Build
        run: npm run build
      
      - name: Upload coverage
        uses: codecov/codecov-action@v3

# My Library

A modern JavaScript library for building awesome applications.

## Installation

```bash
npm install my-library

import { Button } from 'my-library';

function App() {
  return <Button>Click me</Button>;
}

### API 文档

```typescript
/**
 * Formats a date to a string
 * @param date - The date to format
 * @param format - The format string (default: 'YYYY-MM-DD')
 * @returns The formatted date string
 * @example
 * ```ts
 * formatDate(new Date(), 'YYYY-MM-DD')
 * // => '2024-01-01'
 * ```
 */
export function formatDate(date: Date, format?: string): string;