{"id":14573,"library":"father-build","title":"father-build (UmiJS Father)","description":"Father-build is the primary library build tool within the UmiJS ecosystem, often referred to simply as 'Father'. Currently stable at version 4.6.17, it's a powerful and highly configurable solution for packaging JavaScript and TypeScript libraries. It leverages Rollup for robust bundling and integrates esbuild for performance optimizations across various output formats, including ESM, CJS, UMD, and a 'bundless' mode for individual file compilation. The project maintains a very active development pace, frequently issuing multiple minor and patch updates each month, incorporating new features like CSS extraction, enhanced JSX runtime support, and parallel bundless compilation. Key differentiators include comprehensive TypeScript support (shipping its own types and regularly upgrading internal TS versions), flexible configuration via `father.config.ts` using `defineConfig`, and a strong focus on delivering optimized output for diverse JavaScript environments. It aims to streamline library development by abstracting complex build configurations and providing a consistent developer experience.","status":"active","version":"1.22.5","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/umijs/father","tags":["javascript","typescript"],"install":[{"cmd":"npm install father-build","lang":"bash","label":"npm"},{"cmd":"yarn add father-build","lang":"bash","label":"yarn"},{"cmd":"pnpm add father-build","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primarily used in `father.config.ts` for type-safe configuration. CommonJS `require` is generally not used for config files with TypeScript.","wrong":"const { defineConfig } = require('father');","symbol":"defineConfig","correct":"import { defineConfig } from 'father';"},{"note":"The primary interaction is via the `father` CLI, often through `npx` or a `package.json` script. While the package name is 'father-build' in some contexts, the CLI command is 'father'.","wrong":"node_modules/.bin/father-build build","symbol":"father CLI","correct":"npx father build"}],"quickstart":{"code":"// package.json\n{\n  \"name\": \"my-library\",\n  \"version\": \"1.0.0\",\n  \"main\": \"dist/index.cjs.js\",\n  \"module\": \"dist/index.esm.js\",\n  \"types\": \"dist/index.d.ts\",\n  \"scripts\": {\n    \"build\": \"father build\"\n  },\n  \"devDependencies\": {\n    \"father\": \"^4.6.17\",\n    \"typescript\": \"^5.0.0\"\n  }\n}\n\n// father.config.ts\nimport { defineConfig } from 'father';\n\nexport default defineConfig({\n  // Target Node.js v14+ environments\n  targets: {\n    node: '14',\n  },\n  // Configure ESM build (for modern environments)\n  esm: {\n    output: 'dist/esm', // Output directory for ESM\n    platform: 'browser', // For browser-compatible ESM\n    // Optional: add aliases\n    alias: {\n      '@/utils': './src/utils',\n    },\n  },\n  // Configure CommonJS build (for Node.js)\n  cjs: {\n    output: 'dist/cjs', // Output directory for CJS\n    platform: 'node', // For Node.js CommonJS\n  },\n  // Configure UMD build (for browser globals)\n  umd: {\n    output: 'dist/umd', // Output directory for UMD\n    name: 'MyLibrary', // Global variable name\n    // Optional: define external globals\n    globals: {\n      react: 'React',\n      'react-dom': 'ReactDOM',\n    },\n  },\n  // Configure Bundless build (individual file compilation)\n  bundless: {\n    output: 'dist/lib', // Output directory for bundless\n  },\n  // Enable TypeScript declaration generation automatically\n  // extraBabelPlugins: [], // Uncomment and add if you need custom Babel plugins\n  // entry: 'src/index.ts', // Father can auto-detect entries, specify if needed\n});\n\n// src/index.ts\nexport function greet(name: string): string {\n  return `Hello, ${name}! Welcome to my library.`;\n}\n\nexport function add(a: number, b: number): number {\n  return a + b;\n}\n\n// Example of an exported type definition\nexport type User = {\n  id: string;\n  name: string;\n};\n\n// Example function (could be framework-dependent in a real library)\nexport function createUser(id: string, name: string): User {\n  console.log(`Creating user with id: ${id} and name: ${name}`);\n  return { id, name };\n}\n","lang":"typescript","description":"Demonstrates a typical `father` setup in a `package.json` with a comprehensive `father.config.ts` for ESM, CJS, UMD, and bundless outputs, along with a simple TypeScript source file. Run `npm install` then `npm run build`."},"warnings":[{"fix":"Consult the official Father v4 migration guide for a detailed overview of breaking changes and updated configuration patterns.","message":"Upgrading from `father` v3 to v4 involves a complete rewrite of the build tool, requiring significant refactoring of existing configurations. The configuration schema, API, and underlying build mechanisms have been revamped for improved performance and simplicity.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Remove `babel-plugin-dynamic-import-node` from your Babel configuration. `father` now handles async chunks internally; review if your dynamic import statements require any specific adjustments for the new behavior.","message":"Starting from `father` v4.5.1, the internal mechanism for handling dynamic imports shifted from `babel-plugin-dynamic-import-node` to an `asyncChunks` approach. Projects explicitly relying on or configuring the old Babel plugin for dynamic imports will experience build failures.","severity":"breaking","affected_versions":">=4.5.1"},{"fix":"If your UMD bundle relies on specific polyfills in a Node.js environment, you must manually include these polyfills in your project or ensure the target Node.js version natively supports the required APIs.","message":"UMD bundles generated with `father` v4.6.11 and later, specifically targeting the 'node' platform, no longer include polyfills from `node-polyfill-provider`. This change can lead to runtime errors in Node.js environments if the application expects certain browser-like polyfills to be present.","severity":"gotcha","affected_versions":">=4.6.11"},{"fix":"If experiencing `ajv`-related issues with `Bun`, consider using `npm` or `yarn` for dependency installation as an alternative, or check for updated `Bun` compatibility information and `father` releases addressing these specific scenarios.","message":"When using `Bun` as a package manager, users might encounter unexpected compatibility issues with the `ajv` package during installation or build processes. A workaround was introduced in v4.5.5, but environmental factors can still cause problems.","severity":"gotcha","affected_versions":">=4.5.5"},{"fix":"Ensure your project's `typescript` dependency is compatible with TypeScript 5.4.x, or a version range that is known to work well with `father`'s internal TS version. Review your `tsconfig.json` for any compiler options that might conflict with newer TypeScript versions.","message":"The internal TypeScript version used by `father` was upgraded to 5.4.2 in v4.5.3. While this is a feature, projects with older or very specific TypeScript setups might face implicit compatibility issues if their own TypeScript version is not compatible with the one `father` uses internally for type processing.","severity":"gotcha","affected_versions":">=4.5.3"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Remove `babel-plugin-dynamic-import-node` from your Babel configuration. Father v4.5.1+ handles dynamic imports via its internal `asyncChunks` mechanism.","cause":"Configuration for an older version of father-build (pre-4.5.1) attempting to use a deprecated Babel plugin for dynamic imports.","error":"Error: Cannot find module 'babel-plugin-dynamic-import-node'"},{"fix":"Try `npm install` or `yarn install` instead of `bun install`. Ensure your `father` and `ajv` versions are the latest to pick up any compatibility fixes.","cause":"Compatibility issues between Bun and the `ajv` dependency, often related to module resolution or package structure differences.","error":"TypeError: (0, import_ajv.default) is not a constructor (or similar 'ajv' related error when using Bun)"},{"fix":"For UMD bundles used in Node.js, explicitly add necessary polyfills to your project or adjust your build target if these polyfills are critical for your library's runtime.","cause":"UMD bundles targeting the 'node' platform no longer automatically include Node.js polyfills since father v4.6.11, leading to missing global objects or functions.","error":"ReferenceError: Buffer is not defined (or other Node.js global/polyfill errors in UMD bundles on Node.js)"}],"ecosystem":"npm"}