Father (NPM Package Build Tool)

Common errors

• Error: Cannot find module 'father'

  cause The `father` package is not installed in the project or is not accessible in the current execution environment.
  fix Run `npm install father` or `pnpm install father` or `yarn add father` in your project's root directory. Ensure it's listed in `devDependencies`.

• TypeScript error: Argument of type '{ ... }' is not assignable to parameter of type 'IFatherConfig'.

  cause The configuration object passed to `defineConfig` in `father.config.ts` does not conform to the `IFatherConfig` type definition.
  fix Review your `father.config.ts` against the official documentation and the type definitions (`IFatherConfig`, `IBundlessConfig`, etc.) for any incorrect or missing properties. Your IDE should provide type hints.

• Build failed: 'output' cannot be set for 'esm' or 'cjs' when 'auto' is enabled.

  cause Conflicting configuration where an explicit output path is provided for ESModule or CommonJS builds while the `auto` output directory generation is also active.
  fix Either remove the `output` property from the `esm` or `cjs` configuration block, or disable `auto` if you intend to specify custom output paths manually.

Warnings

• breaking Upgrading from Father 2.x to Father 4.x introduces significant breaking changes due to a complete rewrite and architectural shifts. Direct upgrade often requires reconfiguring build processes.
  Fix: Refer to the official 'upgrading.md' guide (linked in the README) for detailed migration steps, focusing on configuration file changes and new build options.
• gotcha Incorrectly configuring Bundless vs. Bundle modes, or choosing the wrong build core (esbuild, Babel, SWC for Bundless; Webpack for Bundle) can lead to unexpected output formats or compatibility issues.
  Fix: Carefully review the `esm`, `cjs`, and `umd` configuration options in `father.config.ts`. Ensure `type` and `platform` settings match your target environment and module format requirements.
• gotcha While persistent caching is a feature, in rare cases it might lead to stale build artifacts if the cache is not properly invalidated after certain changes (e.g., changes to external dependencies not tracked by Father).
  Fix: If encountering unexpected build results, try clearing the Father cache by deleting the `.father` directory in your project root, or running `father build --clean` if available (check CLI options).

Install

• npm install father npm
• yarn add father yarn
• pnpm add father pnpm

Imports

• defineConfig
  wrong:

  const { defineConfig } = require('father');

  correct:

  import { defineConfig } from 'father';

  Primarily used in `father.config.ts` for type-safe configuration. CommonJS `require` is not supported for this utility.
• IFatherConfig
  wrong:

  import { IFatherConfig } from 'father';

  correct:

  import type { IFatherConfig } from 'father';

  A TypeScript interface for the main Father configuration object, used for advanced type-checking or custom config structures. Always use `import type`.
• IBundlessConfig
  wrong:

  import { IBundlessConfig } from 'father';

  correct:

  import type { IBundlessConfig } from 'father';

  A TypeScript interface for configuration specific to the Bundless build mode. Useful for detailed type-checking in complex scenarios. Always use `import type`.

Quickstart

Demonstrates setting up a basic TypeScript package with Father, including configuration for ESModule and CommonJS outputs, and a build script.

{
  "name": "my-package",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "build": "father build"
  },
  "devDependencies": {
    "father": "^4.6.18",
    "typescript": "^5.0.0"
  }
}
// father.config.ts
import { defineConfig } from 'father';

export default defineConfig({
  esm: { type: 'babel', importLibToEs: true },
  cjs: { type: 'babel', lazy: true },
  // Optional: UMD build for browser compatibility
  // umd: { name: 'myPackage', output: 'dist' },
  // Persistent caching for faster rebuilds
  extraBabelPlugins: [
    ['babel-plugin-import', { libraryName: 'lodash', libraryDirectory: 'es' }]
  ],
  targets: { esmodules: true, node: 14 }
});
// src/index.ts
export const greet = (name: string): string => `Hello, ${name} from Father!`;

export const add = (a: number, b: number): number => a + b;