@reasonabletech/config-tsup 0.1.0

package/README.md

@@ -0,0 +1,98 @@
+# @reasonabletech/config-tsup
+
+[![npm version](https://img.shields.io/npm/v/@reasonabletech/config-tsup.svg)](https://www.npmjs.com/package/@reasonabletech/config-tsup)
+[![npm downloads](https://img.shields.io/npm/dm/@reasonabletech/config-tsup.svg)](https://www.npmjs.com/package/@reasonabletech/config-tsup)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
+
+`@reasonabletech/config-tsup` provides shared `tsup` configuration factories for library and tooling packages. The defaults produce ESM-only output with declaration files, targeting a neutral platform — override only the options that differ from those defaults.
+
+## Installation
+
+```bash
+pnpm add -D @reasonabletech/config-tsup tsup typescript
+```
+
+## Peer Dependencies
+
+| Dependency | Version   | Required |
+| ---------- | --------- | -------- |
+| tsup       | >= 8.0    | Yes      |
+| typescript | >= 5.0    | Yes      |
+
+This package generates tsup configuration objects and requires tsup 8.0+ for ESM-first defaults and TypeScript 5.0+ for type checking.
+
+## Exported API
+
+```ts
+import {
+  createTsupConfig,
+  configPackageConfig,
+  nodeConfig,
+  reactConfig,
+  type EsbuildOptionsFunction,
+  type TsupConfigOptions,
+} from "@reasonabletech/config-tsup";
+```
+
+## Usage
+
+### Default Library Configuration
+
+```ts
+// tsup.config.ts
+import { createTsupConfig } from "@reasonabletech/config-tsup";
+
+export default createTsupConfig();
+```
+
+### Customized Configuration
+
+```ts
+// tsup.config.ts
+import { createTsupConfig } from "@reasonabletech/config-tsup";
+
+export default createTsupConfig({
+  dts: true,
+  entry: { index: "src/index.ts" },
+  external: ["react"],
+});
+```
+
+### Preset Configurations
+
+```ts
+import {
+  configPackageConfig,
+  nodeConfig,
+  reactConfig,
+} from "@reasonabletech/config-tsup";
+
+export default reactConfig;
+```
+
+## Defaults
+
+`createTsupConfig()` defaults to:
+
+- `entry: { index: "src/index.ts" }`
+- `format: ["esm"]`
+- `platform: "neutral"`
+- `target: "ES2023"`
+- `sourcemap: true`
+- `treeshake: true`
+- `splitting: false`
+- `clean: false`
+
+If `tsconfig` is omitted, the factory uses `tsconfig.build.json` automatically when present.
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for release history.
+
+This package follows [Semantic Versioning](https://semver.org/). Breaking changes are documented with migration guides when applicable.
+
+## Additional References
+
+- [Usage Guide](./docs/guides/usage-guide.md)
+- [Package Docs](./docs/README.md)

package/dist/index.js

@@ -0,0 +1,133 @@
+import { existsSync } from 'fs';
+import path from 'path';
+
+// src/config.ts
+function includeIfDefined(obj) {
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (value !== void 0) {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+function resolveDefaultBuildTsconfigPath() {
+  const buildTsconfigFileName = "tsconfig.build.json";
+  const packageJsonPath = process.env.npm_package_json;
+  if (packageJsonPath !== void 0) {
+    const packageDir = path.dirname(packageJsonPath);
+    const packageTsconfigPath = path.join(packageDir, buildTsconfigFileName);
+    if (existsSync(packageTsconfigPath)) {
+      return packageDir === process.cwd() ? buildTsconfigFileName : packageTsconfigPath;
+    }
+  }
+  const cwdTsconfigPath = path.join(process.cwd(), buildTsconfigFileName);
+  if (existsSync(cwdTsconfigPath)) {
+    return buildTsconfigFileName;
+  }
+  return void 0;
+}
+function createTsupConfig(options = {}) {
+  const {
+    entry = { index: "src/index.ts" },
+    format = ["esm"],
+    external,
+    noExternal,
+    dts = false,
+    bundle,
+    clean = false,
+    sourcemap = true,
+    treeshake = true,
+    splitting = false,
+    platform = "neutral",
+    target = "ES2023",
+    tsconfig,
+    esbuildPlugins = [],
+    esbuildOptions,
+    define,
+    onSuccess,
+    minify,
+    terserOptions,
+    metafile
+  } = options;
+  const defaultExternal = [
+    // Peer dependencies
+    "react",
+    "react-dom",
+    "next",
+    "next/headers",
+    "next/navigation",
+    "next/server",
+    "express",
+    "electron",
+    // Node.js built-ins
+    "fs",
+    "path",
+    "os",
+    "crypto",
+    "child_process",
+    "http",
+    "https",
+    "url",
+    "events",
+    "util",
+    "stream",
+    "buffer",
+    "querystring"
+  ];
+  let finalExternal;
+  if (noExternal !== void 0) {
+    finalExternal = external !== void 0 ? [...external] : void 0;
+  } else {
+    finalExternal = external !== void 0 ? [...defaultExternal, ...external] : defaultExternal;
+  }
+  const resolvedTsconfig = tsconfig ?? resolveDefaultBuildTsconfigPath();
+  const config = {
+    dts,
+    splitting,
+    sourcemap,
+    clean,
+    treeshake,
+    platform,
+    target,
+    outExtension() {
+      return { js: `.js` };
+    },
+    ...includeIfDefined({
+      entry,
+      format,
+      external: finalExternal,
+      noExternal,
+      bundle,
+      tsconfig: resolvedTsconfig,
+      esbuildPlugins,
+      esbuildOptions,
+      define,
+      onSuccess,
+      minify,
+      terserOptions,
+      metafile
+    })
+  };
+  return config;
+}
+var configPackageConfig = createTsupConfig({
+  external: ["tsup", "esbuild"]
+});
+var reactConfig = createTsupConfig({
+  external: ["@mui/icons-material"],
+  esbuildOptions(options) {
+    return {
+      ...options,
+      jsx: "automatic"
+    };
+  }
+});
+var nodeConfig = createTsupConfig({
+  platform: "node",
+  external: ["dotenv"]
+});
+
+export { configPackageConfig, createTsupConfig, nodeConfig, reactConfig };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/config.ts"],"names":[],"mappings":";;;;AAMA,SAAS,iBACP,GAAA,EACyB;AACzB,EAAA,MAAM,SAAkC,EAAC;AACzC,EAAA,KAAA,MAAW,CAAC,GAAA,EAAK,KAAK,KAAK,MAAA,CAAO,OAAA,CAAQ,GAAG,CAAA,EAAG;AAC9C,IAAA,IAAI,UAAU,MAAA,EAAW;AACvB,MAAA,MAAA,CAAO,GAAG,CAAA,GAAI,KAAA;AAAA,IAChB;AAAA,EACF;AACA,EAAA,OAAO,MAAA;AACT;AAEA,SAAS,+BAAA,GAAsD;AAC7D,EAAA,MAAM,qBAAA,GAAwB,qBAAA;AAC9B,EAAA,MAAM,eAAA,GAAkB,QAAQ,GAAA,CAAI,gBAAA;AAEpC,EAAA,IAAI,oBAAoB,MAAA,EAAW;AACjC,IAAA,MAAM,UAAA,GAAa,IAAA,CAAK,OAAA,CAAQ,eAAe,CAAA;AAC/C,IAAA,MAAM,mBAAA,GAAsB,IAAA,CAAK,IAAA,CAAK,UAAA,EAAY,qBAAqB,CAAA;AACvE,IAAA,IAAI,UAAA,CAAW,mBAAmB,CAAA,EAAG;AACnC,MAAA,OAAO,UAAA,KAAe,OAAA,CAAQ,GAAA,EAAI,GAC9B,qBAAA,GACA,mBAAA;AAAA,IACN;AAAA,EACF;AAEA,EAAA,MAAM,kBAAkB,IAAA,CAAK,IAAA,CAAK,OAAA,CAAQ,GAAA,IAAO,qBAAqB,CAAA;AACtE,EAAA,IAAI,UAAA,CAAW,eAAe,CAAA,EAAG;AAC/B,IAAA,OAAO,qBAAA;AAAA,EACT;AAEA,EAAA,OAAO,MAAA;AACT;AAyIO,SAAS,gBAAA,CACd,OAAA,GAA6B,EAAC,EACrB;AACT,EAAA,MAAM;AAAA,IACJ,KAAA,GAAQ,EAAE,KAAA,EAAO,cAAA,EAAe;AAAA,IAChC,MAAA,GAAS,CAAC,KAAK,CAAA;AAAA,IACf,QAAA;AAAA,IACA,UAAA;AAAA,IACA,GAAA,GAAM,KAAA;AAAA,IACN,MAAA;AAAA,IACA,KAAA,GAAQ,KAAA;AAAA,IACR,SAAA,GAAY,IAAA;AAAA,IACZ,SAAA,GAAY,IAAA;AAAA,IACZ,SAAA,GAAY,KAAA;AAAA,IACZ,QAAA,GAAW,SAAA;AAAA,IACX,MAAA,GAAS,QAAA;AAAA,IACT,QAAA;AAAA,IACA,iBAAiB,EAAC;AAAA,IAClB,cAAA;AAAA,IACA,MAAA;AAAA,IACA,SAAA;AAAA,IACA,MAAA;AAAA,IACA,aAAA;AAAA,IACA;AAAA,GACF,GAAI,OAAA;AAGJ,EAAA,MAAM,eAAA,GAAkB;AAAA;AAAA,IAEtB,OAAA;AAAA,IACA,WAAA;AAAA,IACA,MAAA;AAAA,IACA,cAAA;AAAA,IACA,iBAAA;AAAA,IACA,aAAA;AAAA,IACA,SAAA;AAAA,IACA,UAAA;AAAA;AAAA,IAEA,IAAA;AAAA,IACA,MAAA;AAAA,IACA,IAAA;AAAA,IACA,QAAA;AAAA,IACA,eAAA;AAAA,IACA,MAAA;AAAA,IACA,OAAA;AAAA,IACA,KAAA;AAAA,IACA,QAAA;AAAA,IACA,MAAA;AAAA,IACA,QAAA;AAAA,IACA,QAAA;AAAA,IACA;AAAA,GACF;AAGA,EAAA,IAAI,aAAA;AACJ,EAAA,IAAI,eAAe,MAAA,EAAW;AAE5B,IAAA,aAAA,GAAgB,QAAA,KAAa,MAAA,GAAY,CAAC,GAAG,QAAQ,CAAA,GAAI,MAAA;AAAA,EAC3D,CAAA,MAAO;AAEL,IAAA,aAAA,GACE,aAAa,MAAA,GACT,CAAC,GAAG,eAAA,EAAiB,GAAG,QAAQ,CAAA,GAChC,eAAA;AAAA,EACR;AAEA,EAAA,MAAM,gBAAA,GAAmB,YAAY,+BAAA,EAAgC;AAErE,EAAA,MAAM,MAAA,GAAkB;AAAA,IACtB,GAAA;AAAA,IACA,SAAA;AAAA,IACA,SAAA;AAAA,IACA,KAAA;AAAA,IACA,SAAA;AAAA,IACA,QAAA;AAAA,IACA,MAAA;AAAA,IACA,YAAA,GAAe;AACb,MAAA,OAAO,EAAE,IAAI,CAAA,GAAA,CAAA,EAAM;AAAA,IACrB,CAAA;AAAA,IACA,GAAG,gBAAA,CAAiB;AAAA,MAClB,KAAA;AAAA,MACA,MAAA;AAAA,MACA,QAAA,EAAU,aAAA;AAAA,MACV,UAAA;AAAA,MACA,MAAA;AAAA,MACA,QAAA,EAAU,gBAAA;AAAA,MACV,cAAA;AAAA,MACA,cAAA;AAAA,MACA,MAAA;AAAA,MACA,SAAA;AAAA,MACA,MAAA;AAAA,MACA,aAAA;AAAA,MACA;AAAA,KACD;AAAA,GACH;AAcA,EAAA,OAAO,MAAA;AACT;AAKO,IAAM,sBAAsB,gBAAA,CAAiB;AAAA,EAClD,QAAA,EAAU,CAAC,MAAA,EAAQ,SAAS;AAC9B,CAAC;AAKM,IAAM,cAAc,gBAAA,CAAiB;AAAA,EAC1C,QAAA,EAAU,CAAC,qBAAqB,CAAA;AAAA,EAEhC,eAAe,OAAA,EAAiC;AAC9C,IAAA,OAAO;AAAA,MACL,GAAG,OAAA;AAAA,MACH,GAAA,EAAK;AAAA,KACP;AAAA,EACF;AACF,CAAC;AAKM,IAAM,aAAa,gBAAA,CAAiB;AAAA,EACzC,QAAA,EAAU,MAAA;AAAA,EACV,QAAA,EAAU,CAAC,QAAQ;AACrB,CAAC","file":"index.js","sourcesContent":["import { type Options } from \"tsup\";\nimport type { BuildOptions } from \"esbuild\";\nimport { existsSync } from \"node:fs\";\nimport path from \"node:path\";\n\n// Local utility to avoid circular dependency with @reasonabletech/utils\nfunction includeIfDefined<T extends Record<string, unknown>>(\n  obj: T,\n): Record<string, unknown> {\n  const result: Record<string, unknown> = {};\n  for (const [key, value] of Object.entries(obj)) {\n    if (value !== undefined) {\n      result[key] = value;\n    }\n  }\n  return result;\n}\n\nfunction resolveDefaultBuildTsconfigPath(): string | undefined {\n  const buildTsconfigFileName = \"tsconfig.build.json\";\n  const packageJsonPath = process.env.npm_package_json;\n\n  if (packageJsonPath !== undefined) {\n    const packageDir = path.dirname(packageJsonPath);\n    const packageTsconfigPath = path.join(packageDir, buildTsconfigFileName);\n    if (existsSync(packageTsconfigPath)) {\n      return packageDir === process.cwd()\n        ? buildTsconfigFileName\n        : packageTsconfigPath;\n    }\n  }\n\n  const cwdTsconfigPath = path.join(process.cwd(), buildTsconfigFileName);\n  if (existsSync(cwdTsconfigPath)) {\n    return buildTsconfigFileName;\n  }\n\n  return undefined;\n}\n\n/**\n * Function signature for customizing tsup's `esbuildOptions`.\n */\nexport type EsbuildOptionsFunction = (\n  options: Readonly<BuildOptions>,\n) => BuildOptions;\n\n/**\n * Configuration options for creating a tsup build configuration.\n */\nexport interface TsupConfigOptions {\n  /**\n   * Entry points for the build. Can be a string, array, or object.\n   * Defaults to { index: \"src/index.ts\" }\n   */\n  readonly entry?:\n    | Readonly<Record<string, string>>\n    | string\n    | readonly string[];\n\n  /**\n   * Output formats. Defaults to [\"esm\"].\n   * ESM is the standard - other formats are strongly discouraged except with compelling justification.\n   */\n  readonly format?: ReadonlyArray<\"esm\" | \"cjs\" | \"iife\">;\n\n  /**\n   * External dependencies that should not be bundled.\n   * If not provided, sensible defaults are used based on platform.\n   * To override defaults completely, use noExternal: [/.*\\/] and provide exact externals.\n   */\n  readonly external?: readonly string[];\n\n  /**\n   * Dependencies that should always be bundled (opposite of external).\n   * Use [/.*\\/] to bundle everything except what's in external array.\n   */\n  readonly noExternal?: ReadonlyArray<string | RegExp>;\n\n  /**\n   * Whether to generate TypeScript declaration files. Defaults to false.\n   */\n  readonly dts?: boolean;\n\n  /**\n   * Whether to generate source maps. Defaults to true.\n   */\n  readonly sourcemap?: boolean;\n\n  /**\n   * Whether to bundle dependencies. Defaults to true.\n   */\n  readonly bundle?: boolean;\n\n  /**\n   * Whether to clean the output directory before building. Defaults to false.\n   *\n   * Rationale: A non-clean default avoids deleting artifacts unexpectedly in\n   * multi-step builds and keeps incremental local workflows predictable.\n   * Packages that need cleaning can explicitly set clean=true.\n   */\n  readonly clean?: boolean;\n\n  /**\n   * Whether to enable tree shaking. Defaults to true.\n   */\n  readonly treeshake?: boolean;\n\n  /**\n   * Whether to enable code splitting. Defaults to false for better compatibility.\n   */\n  readonly splitting?: boolean;\n\n  /**\n   * Target platform. Defaults to \"neutral\" for libraries.\n   */\n  readonly platform?: \"node\" | \"browser\" | \"neutral\";\n\n  /**\n   * Target environment. Defaults to \"ES2023\" (Node.js 22 compatible).\n   */\n  readonly target?: string;\n\n  /**\n   * Path to TypeScript config file.\n   */\n  readonly tsconfig?: string;\n\n  /**\n   * Additional esbuild plugins.\n   */\n  readonly esbuildPlugins?: readonly unknown[];\n\n  /**\n   * Custom esbuild options function.\n   */\n  readonly esbuildOptions?: (options: Readonly<BuildOptions>) => BuildOptions;\n\n  /**\n   * Build-time environment variable definitions.\n   */\n  readonly define?: Readonly<Record<string, string>>;\n\n  /**\n   * Custom onSuccess callback.\n   */\n  readonly onSuccess?: () => void | Promise<void>;\n\n  /**\n   * Minification options.\n   */\n  readonly minify?: boolean | \"terser\";\n\n  /**\n   * Terser-specific options (when minify: \"terser\").\n   */\n  readonly terserOptions?: {\n    readonly compress?: Record<string, unknown>;\n    readonly mangle?: Record<string, unknown>;\n  };\n\n  /**\n   * Whether to generate metafile for bundle analysis.\n   */\n  readonly metafile?: boolean;\n}\n\n/**\n * Base tsup configuration for packages in the ReasonableTech project.\n *\n * This configuration provides sensible defaults for most packages while allowing\n * for customization through options or by extending this configuration.\n * @param options Configuration options to customize the tsup build\n * @returns Configured tsup build settings\n */\nexport function createTsupConfig(\n  options: TsupConfigOptions = {},\n): Options {\n  const {\n    entry = { index: \"src/index.ts\" },\n    format = [\"esm\"],\n    external,\n    noExternal,\n    dts = false,\n    bundle,\n    clean = false,\n    sourcemap = true,\n    treeshake = true,\n    splitting = false,\n    platform = \"neutral\",\n    target = \"ES2023\",\n    tsconfig,\n    esbuildPlugins = [],\n    esbuildOptions,\n    define,\n    onSuccess,\n    minify,\n    terserOptions,\n    metafile,\n  } = options;\n\n  // Default externals - only used if user doesn't provide noExternal\n  const defaultExternal = [\n    // Peer dependencies\n    \"react\",\n    \"react-dom\",\n    \"next\",\n    \"next/headers\",\n    \"next/navigation\",\n    \"next/server\",\n    \"express\",\n    \"electron\",\n    // Node.js built-ins\n    \"fs\",\n    \"path\",\n    \"os\",\n    \"crypto\",\n    \"child_process\",\n    \"http\",\n    \"https\",\n    \"url\",\n    \"events\",\n    \"util\",\n    \"stream\",\n    \"buffer\",\n    \"querystring\",\n  ];\n\n  // Determine final external list\n  let finalExternal: string[] | undefined;\n  if (noExternal !== undefined) {\n    // If noExternal is provided, only use the explicit external list\n    finalExternal = external !== undefined ? [...external] : undefined;\n  } else {\n    // Default behavior: merge user external with defaults\n    finalExternal =\n      external !== undefined\n        ? [...defaultExternal, ...external]\n        : defaultExternal;\n  }\n\n  const resolvedTsconfig = tsconfig ?? resolveDefaultBuildTsconfigPath();\n\n  const config: Options = {\n    dts,\n    splitting,\n    sourcemap,\n    clean,\n    treeshake,\n    platform,\n    target,\n    outExtension() {\n      return { js: `.js` };\n    },\n    ...includeIfDefined({\n      entry: entry as Options[\"entry\"],\n      format: format as Options[\"format\"],\n      external: finalExternal as Options[\"external\"],\n      noExternal: noExternal as Options[\"noExternal\"],\n      bundle,\n      tsconfig: resolvedTsconfig,\n      esbuildPlugins,\n      esbuildOptions,\n      define,\n      onSuccess,\n      minify,\n      terserOptions,\n      metafile,\n    }),\n  };\n  //   ...(tsconfig !== undefined ? { tsconfig } : {}),\n  //   ...(esbuildPlugins.length > 0\n  //     ? { esbuildPlugins: esbuildPlugins as Options[\"esbuildPlugins\"] }\n  //     : {}),\n  //   ...(esbuildOptions !== undefined\n  //     ? { esbuildOptions: esbuildOptions as Options[\"esbuildOptions\"] }\n  //     : {}),\n  //   ...(define !== undefined ? { define: define as Options[\"define\"] } : {}),\n  //   ...(onSuccess !== undefined\n  //     ? { onSuccess: onSuccess as Options[\"onSuccess\"] }\n  //     : {}),\n  // };\n\n  return config;\n}\n\n/**\n * Pre-configured tsup config for build/config packages.\n */\nexport const configPackageConfig = createTsupConfig({\n  external: [\"tsup\", \"esbuild\"],\n});\n\n/**\n * Pre-configured tsup config for React component libraries.\n */\nexport const reactConfig = createTsupConfig({\n  external: [\"@mui/icons-material\"],\n\n  esbuildOptions(options: Readonly<BuildOptions>) {\n    return {\n      ...options,\n      jsx: \"automatic\",\n    };\n  },\n});\n\n/**\n * Pre-configured tsup config for Node.js applications/CLIs.\n */\nexport const nodeConfig = createTsupConfig({\n  platform: \"node\",\n  external: [\"dotenv\"],\n});\n"]}

package/dist/src/config.d.ts

@@ -0,0 +1,125 @@
+import { type Options } from "tsup";
+import type { BuildOptions } from "esbuild";
+/**
+ * Function signature for customizing tsup's `esbuildOptions`.
+ */
+export type EsbuildOptionsFunction = (options: Readonly<BuildOptions>) => BuildOptions;
+/**
+ * Configuration options for creating a tsup build configuration.
+ */
+export interface TsupConfigOptions {
+    /**
+     * Entry points for the build. Can be a string, array, or object.
+     * Defaults to { index: "src/index.ts" }
+     */
+    readonly entry?: Readonly<Record<string, string>> | string | readonly string[];
+    /**
+     * Output formats. Defaults to ["esm"].
+     * ESM is the standard - other formats are strongly discouraged except with compelling justification.
+     */
+    readonly format?: ReadonlyArray<"esm" | "cjs" | "iife">;
+    /**
+     * External dependencies that should not be bundled.
+     * If not provided, sensible defaults are used based on platform.
+     * To override defaults completely, use noExternal: [/.*\/] and provide exact externals.
+     */
+    readonly external?: readonly string[];
+    /**
+     * Dependencies that should always be bundled (opposite of external).
+     * Use [/.*\/] to bundle everything except what's in external array.
+     */
+    readonly noExternal?: ReadonlyArray<string | RegExp>;
+    /**
+     * Whether to generate TypeScript declaration files. Defaults to false.
+     */
+    readonly dts?: boolean;
+    /**
+     * Whether to generate source maps. Defaults to true.
+     */
+    readonly sourcemap?: boolean;
+    /**
+     * Whether to bundle dependencies. Defaults to true.
+     */
+    readonly bundle?: boolean;
+    /**
+     * Whether to clean the output directory before building. Defaults to false.
+     *
+     * Rationale: A non-clean default avoids deleting artifacts unexpectedly in
+     * multi-step builds and keeps incremental local workflows predictable.
+     * Packages that need cleaning can explicitly set clean=true.
+     */
+    readonly clean?: boolean;
+    /**
+     * Whether to enable tree shaking. Defaults to true.
+     */
+    readonly treeshake?: boolean;
+    /**
+     * Whether to enable code splitting. Defaults to false for better compatibility.
+     */
+    readonly splitting?: boolean;
+    /**
+     * Target platform. Defaults to "neutral" for libraries.
+     */
+    readonly platform?: "node" | "browser" | "neutral";
+    /**
+     * Target environment. Defaults to "ES2023" (Node.js 22 compatible).
+     */
+    readonly target?: string;
+    /**
+     * Path to TypeScript config file.
+     */
+    readonly tsconfig?: string;
+    /**
+     * Additional esbuild plugins.
+     */
+    readonly esbuildPlugins?: readonly unknown[];
+    /**
+     * Custom esbuild options function.
+     */
+    readonly esbuildOptions?: (options: Readonly<BuildOptions>) => BuildOptions;
+    /**
+     * Build-time environment variable definitions.
+     */
+    readonly define?: Readonly<Record<string, string>>;
+    /**
+     * Custom onSuccess callback.
+     */
+    readonly onSuccess?: () => void | Promise<void>;
+    /**
+     * Minification options.
+     */
+    readonly minify?: boolean | "terser";
+    /**
+     * Terser-specific options (when minify: "terser").
+     */
+    readonly terserOptions?: {
+        readonly compress?: Record<string, unknown>;
+        readonly mangle?: Record<string, unknown>;
+    };
+    /**
+     * Whether to generate metafile for bundle analysis.
+     */
+    readonly metafile?: boolean;
+}
+/**
+ * Base tsup configuration for packages in the ReasonableTech project.
+ *
+ * This configuration provides sensible defaults for most packages while allowing
+ * for customization through options or by extending this configuration.
+ * @param options Configuration options to customize the tsup build
+ * @returns Configured tsup build settings
+ */
+export declare function createTsupConfig(options?: TsupConfigOptions): Options;
+/**
+ * Pre-configured tsup config for build/config packages.
+ */
+export declare const configPackageConfig: Options;
+/**
+ * Pre-configured tsup config for React component libraries.
+ */
+export declare const reactConfig: Options;
+/**
+ * Pre-configured tsup config for Node.js applications/CLIs.
+ */
+export declare const nodeConfig: Options;
+//# sourceMappingURL=config.d.ts.map

package/dist/src/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,MAAM,CAAC;AACpC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAuC5C;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,CACnC,OAAO,EAAE,QAAQ,CAAC,YAAY,CAAC,KAC5B,YAAY,CAAC;AAElB;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EACX,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAChC,MAAM,GACN,SAAS,MAAM,EAAE,CAAC;IAEtB;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC,CAAC;IAExD;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAEtC;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,aAAa,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;IAErD;;OAEG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IAEvB;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAE1B;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;IAEnD;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B;;OAEG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IAE7C;;OAEG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC,YAAY,CAAC,KAAK,YAAY,CAAC;IAE5E;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAEnD;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhD;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IAErC;;OAEG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE;QACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC5C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC3C,CAAC;IAEF;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CA2GT;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB,SAE9B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,WAAW,SAStB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,UAAU,SAGrB,CAAC"}

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+export { createTsupConfig, reactConfig, nodeConfig, configPackageConfig, } from "./config.js";
+export type { EsbuildOptionsFunction, TsupConfigOptions } from "./config.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,UAAU,EACV,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC"}

package/docs/README.md

@@ -0,0 +1,30 @@
+# @reasonabletech/config-tsup Documentation
+
+Reference documentation for shared `tsup` configuration in the core-utils monorepo.
+
+## Start Here
+
+- [Usage Guide](./guides/usage-guide.md)
+
+## API Reference
+
+- [API Reference](./api/api-reference.md) — Factory functions, options, and preset configs
+
+## Quick Example
+
+```ts
+// tsup.config.ts
+import { createTsupConfig } from "@reasonabletech/config-tsup";
+
+export default createTsupConfig({
+  dts: true,
+  clean: true,
+});
+```
+
+## Monorepo Context
+
+- [Package README](../README.md)
+- [Architecture](../../../docs/architecture.md) — How packages relate
+- [Tooling](../../../docs/tooling.md) — Turbo, Changesets, tsup details
+- [Contributing](../../../CONTRIBUTING.md)

package/docs/api/api-reference.md

@@ -0,0 +1,337 @@
+# config-tsup API Reference
+
+## Package Exports
+
+```typescript
+import {
+  createTsupConfig,
+  reactConfig,
+  nodeConfig,
+  configPackageConfig,
+} from "@reasonabletech/config-tsup";
+
+import type {
+  TsupConfigOptions,
+  EsbuildOptionsFunction,
+} from "@reasonabletech/config-tsup";
+```
+
+---
+
+## Factory Function
+
+### `createTsupConfig(options?)`
+
+Creates a customized tsup build configuration with sensible defaults for TypeScript libraries.
+
+**Signature:**
+
+```typescript
+function createTsupConfig(options?: TsupConfigOptions): Options;
+```
+
+**Parameters:**
+
+| Parameter | Type               | Default | Description                   |
+| --------- | ------------------ | ------- | ----------------------------- |
+| `options` | `TsupConfigOptions` | `{}`    | Configuration options object  |
+
+**Returns:** `Options` — A tsup configuration object
+
+---
+
+## Configuration Options
+
+### `TsupConfigOptions`
+
+```typescript
+interface TsupConfigOptions {
+  entry?: Record<string, string> | string | string[];
+  format?: Array<"esm" | "cjs" | "iife">;
+  external?: string[];
+  noExternal?: Array<string | RegExp>;
+  dts?: boolean;
+  sourcemap?: boolean;
+  bundle?: boolean;
+  clean?: boolean;
+  treeshake?: boolean;
+  splitting?: boolean;
+  platform?: "node" | "browser" | "neutral";
+  target?: string;
+  tsconfig?: string;
+  esbuildPlugins?: unknown[];
+  esbuildOptions?: EsbuildOptionsFunction;
+  define?: Record<string, string>;
+  onSuccess?: () => void | Promise<void>;
+  minify?: boolean | "terser";
+  terserOptions?: {
+    compress?: Record<string, unknown>;
+    mangle?: Record<string, unknown>;
+  };
+  metafile?: boolean;
+}
+```
+
+### Option Details
+
+| Option            | Type                                   | Default                   | Description                                                                                                |
+| ----------------- | -------------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `entry`           | `Record<string, string> \| string \| string[]` | `{ index: "src/index.ts" }` | Entry points for the build                                                                                 |
+| `format`          | `Array<"esm" \| "cjs" \| "iife">`      | `["esm"]`                 | Output formats. ESM is standard; other formats are discouraged except with compelling justification        |
+| `external`        | `string[]`                             | See below                 | Dependencies that should not be bundled                                                                    |
+| `noExternal`      | `Array<string \| RegExp>`              | `undefined`               | Dependencies that should always be bundled. Use `[/.*/]` to bundle everything except explicit externals    |
+| `dts`             | `boolean`                              | `false`                   | Generate TypeScript declaration files                                                                      |
+| `sourcemap`       | `boolean`                              | `true`                    | Generate source maps                                                                                       |
+| `bundle`          | `boolean`                              | `undefined` (tsup default) | Bundle dependencies                                                                                        |
+| `clean`           | `boolean`                              | `false`                   | Clean output directory before building. Non-clean default avoids deleting artifacts in multi-step builds   |
+| `treeshake`       | `boolean`                              | `true`                    | Enable tree shaking                                                                                        |
+| `splitting`       | `boolean`                              | `false`                   | Enable code splitting. Disabled by default for better compatibility                                        |
+| `platform`        | `"node" \| "browser" \| "neutral"`     | `"neutral"`               | Target platform. "neutral" is best for libraries                                                           |
+| `target`          | `string`                               | `"ES2023"`                | Target environment (Node.js 22 compatible)                                                                 |
+| `tsconfig`        | `string`                               | Auto-detected             | Path to TypeScript config file. Auto-resolves `tsconfig.build.json` if present                             |
+| `esbuildPlugins`  | `unknown[]`                            | `[]`                      | Additional esbuild plugins                                                                                 |
+| `esbuildOptions`  | `EsbuildOptionsFunction`               | `undefined`               | Custom esbuild options transformer                                                                         |
+| `define`          | `Record<string, string>`               | `undefined`               | Build-time environment variable definitions                                                                |
+| `onSuccess`       | `() => void \| Promise<void>`          | `undefined`               | Callback executed after successful build                                                                   |
+| `minify`          | `boolean \| "terser"`                  | `undefined`               | Minification options                                                                                       |
+| `terserOptions`   | `object`                               | `undefined`               | Terser-specific options (when `minify: "terser"`)                                                          |
+| `metafile`        | `boolean`                              | `undefined`               | Generate metafile for bundle analysis                                                                      |
+
+### Default Externals
+
+When `noExternal` is not provided, these dependencies are automatically externalized:
+
+```typescript
+const defaultExternal = [
+  // Peer dependencies
+  "react", "react-dom", "next", "next/headers", "next/navigation",
+  "next/server", "express", "electron",
+  // Node.js built-ins
+  "fs", "path", "os", "crypto", "child_process", "http", "https",
+  "url", "events", "util", "stream", "buffer", "querystring",
+];
+```
+
+---
+
+## Type Exports
+
+### `EsbuildOptionsFunction`
+
+Function signature for customizing tsup's `esbuildOptions`.
+
+```typescript
+type EsbuildOptionsFunction = (options: Readonly<BuildOptions>) => BuildOptions;
+```
+
+---
+
+## Preset Configurations
+
+### `configPackageConfig`
+
+Pre-configured config for build/config packages (like this one).
+
+```typescript
+const configPackageConfig = createTsupConfig({
+  external: ["tsup", "esbuild"],
+});
+```
+
+**Use for:** Packages that provide configuration (eslint configs, tsup configs, etc.)
+
+---
+
+### `reactConfig`
+
+Pre-configured config for React component libraries.
+
+```typescript
+const reactConfig = createTsupConfig({
+  external: ["@mui/icons-material"],
+  esbuildOptions(options) {
+    return {
+      ...options,
+      jsx: "automatic",
+    };
+  },
+});
+```
+
+**Includes:**
+
+- Automatic JSX transform (no React import required)
+- `@mui/icons-material` externalized
+
+**Use for:** React UI component libraries
+
+---
+
+### `nodeConfig`
+
+Pre-configured config for Node.js applications and CLIs.
+
+```typescript
+const nodeConfig = createTsupConfig({
+  platform: "node",
+  external: ["dotenv"],
+});
+```
+
+**Includes:**
+
+- Platform set to `"node"`
+- `dotenv` externalized
+
+**Use for:** Node.js servers, CLIs, and backend utilities
+
+---
+
+## Usage Examples
+
+### Basic Library
+
+```typescript
+// tsup.config.ts
+import { createTsupConfig } from "@reasonabletech/config-tsup";
+
+export default createTsupConfig();
+```
+
+### Library with Declaration Files
+
+```typescript
+// tsup.config.ts
+import { createTsupConfig } from "@reasonabletech/config-tsup";
+
+export default createTsupConfig({
+  dts: true,
+  clean: true,
+});
+```
+
+### Multiple Entry Points
+
+```typescript
+// tsup.config.ts
+import { createTsupConfig } from "@reasonabletech/config-tsup";
+
+export default createTsupConfig({
+  entry: {
+    index: "src/index.ts",
+    cli: "src/cli.ts",
+    utils: "src/utils/index.ts",
+  },
+});
+```
+
+### React Component Library
+
+```typescript
+// tsup.config.ts
+import { reactConfig } from "@reasonabletech/config-tsup";
+
+export default reactConfig;
+```
+
+### Custom React Config with Overrides
+
+```typescript
+// tsup.config.ts
+import { createTsupConfig } from "@reasonabletech/config-tsup";
+
+export default createTsupConfig({
+  external: ["@mui/icons-material", "framer-motion"],
+  esbuildOptions(options) {
+    return {
+      ...options,
+      jsx: "automatic",
+      jsxImportSource: "@emotion/react",
+    };
+  },
+});
+```
+
+### Node.js CLI Application
+
+```typescript
+// tsup.config.ts
+import { createTsupConfig } from "@reasonabletech/config-tsup";
+
+export default createTsupConfig({
+  entry: { cli: "src/cli.ts" },
+  platform: "node",
+  external: ["dotenv", "commander"],
+  minify: true,
+});
+```
+
+### Bundle All Dependencies
+
+```typescript
+// tsup.config.ts
+import { createTsupConfig } from "@reasonabletech/config-tsup";
+
+export default createTsupConfig({
+  noExternal: [/.*/],
+  external: ["react", "react-dom"], // Only externalize peer deps
+});
+```
+
+### Config Package
+
+```typescript
+// tsup.config.ts
+import { configPackageConfig } from "@reasonabletech/config-tsup";
+
+export default configPackageConfig;
+```
+
+### With Build-Time Definitions
+
+```typescript
+// tsup.config.ts
+import { createTsupConfig } from "@reasonabletech/config-tsup";
+
+export default createTsupConfig({
+  define: {
+    "process.env.PACKAGE_VERSION": JSON.stringify(process.env.npm_package_version),
+  },
+});
+```
+
+### Production Build with Minification
+
+```typescript
+// tsup.config.ts
+import { createTsupConfig } from "@reasonabletech/config-tsup";
+
+export default createTsupConfig({
+  minify: "terser",
+  terserOptions: {
+    compress: { drop_console: true },
+  },
+  clean: true,
+  metafile: true,
+});
+```
+
+---
+
+## tsconfig Auto-Resolution
+
+The `tsconfig` option auto-resolves in this order:
+
+1. If `tsconfig` is explicitly provided, use it
+2. Look for `tsconfig.build.json` in the package directory (via `npm_package_json`)
+3. Look for `tsconfig.build.json` in the current working directory
+4. Fall back to tsup's default behavior
+
+This allows packages to use a separate `tsconfig.build.json` for builds while keeping `tsconfig.json` for IDE/editor use.
+
+---
+
+## Related Documentation
+
+- [Usage Guide](../guides/usage-guide.md) — Setup and common patterns
+- [Package README](../../README.md) — Quick start

package/docs/guides/migration.md

@@ -0,0 +1,47 @@
+# Migration Guide
+
+This guide documents breaking changes and how to migrate between major versions of @reasonabletech/config-tsup.
+
+## Current Version
+
+The current major version is **0.x** (pre-1.0). The API is stabilizing but may have breaking changes before 1.0.
+
+## Future Migration Notes
+
+_No breaking changes documented yet. This section will be updated when breaking changes are released._
+
+---
+
+## Migration Template
+
+When documenting a breaking change, use this structure:
+
+### Migrating from X.x to Y.0
+
+#### Breaking Changes
+
+1. **Change description** - Brief explanation of what changed
+   
+   **Before:**
+   ```typescript
+   // Old usage
+   ```
+   
+   **After:**
+   ```typescript
+   // New usage
+   ```
+
+2. **Another change** - Description
+
+#### Deprecations
+
+- `oldFunction()` is deprecated in favor of `newFunction()`
+
+#### New Features
+
+- Feature description
+
+---
+
+_Last updated: [date]_

package/docs/guides/usage-guide.md

@@ -0,0 +1,96 @@
+# @reasonabletech/config-tsup Usage Guide
+
+This guide covers canonical usage of `@reasonabletech/config-tsup` for greenfield package builds.
+
+## Installation
+
+```bash
+pnpm add -D @reasonabletech/config-tsup tsup typescript
+```
+
+## Quick Start
+
+```ts
+// tsup.config.ts
+import { createTsupConfig } from "@reasonabletech/config-tsup";
+
+export default createTsupConfig();
+```
+
+## Exported API
+
+```ts
+import {
+  createTsupConfig,
+  configPackageConfig,
+  nodeConfig,
+  reactConfig,
+  type EsbuildOptionsFunction,
+  type TsupConfigOptions,
+} from "@reasonabletech/config-tsup";
+```
+
+## Common Configuration Patterns
+
+### Library Build
+
+```ts
+import { createTsupConfig } from "@reasonabletech/config-tsup";
+
+export default createTsupConfig({
+  dts: true,
+  entry: { index: "src/index.ts" },
+  format: ["esm"],
+});
+```
+
+### React Component Package
+
+```ts
+import { reactConfig } from "@reasonabletech/config-tsup";
+
+export default reactConfig;
+```
+
+### Node Runtime Package
+
+```ts
+import { nodeConfig } from "@reasonabletech/config-tsup";
+
+export default nodeConfig;
+```
+
+### Config/Tooling Package
+
+```ts
+import { configPackageConfig } from "@reasonabletech/config-tsup";
+
+export default configPackageConfig;
+```
+
+## Defaults from `createTsupConfig()`
+
+- `entry: { index: "src/index.ts" }`
+- `format: ["esm"]`
+- `platform: "neutral"`
+- `target: "ES2023"`
+- `sourcemap: true`
+- `treeshake: true`
+- `splitting: false`
+- `clean: false`
+
+When `tsconfig` is omitted, the factory uses `tsconfig.build.json` automatically if present.
+
+## Troubleshooting
+
+### Unexpected bundled dependencies
+
+Use `external` and `noExternal` explicitly if your package has strict bundling requirements.
+
+### Wrong TypeScript config used
+
+Pass `tsconfig` directly to `createTsupConfig` if your package does not use `tsconfig.build.json`.
+
+## Related Documentation
+
+- [Package README](../../README.md)

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@reasonabletech/config-tsup",
+  "version": "0.1.0",
+  "description": "Shared tsup configuration for ReasonableTech packages",
+  "keywords": [
+    "reasonabletech",
+    "config",
+    "typescript",
+    "tsup",
+    "bundler",
+    "build-config",
+    "esm",
+    "esbuild"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs/**/*"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@types/node": "25.3.1",
+    "@vitest/coverage-v8": "4.0.18",
+    "esbuild": "0.27.3",
+    "eslint": "10.0.2",
+    "tsup": "8.5.1",
+    "typescript": "5.9.3",
+    "vitest": "4.0.18",
+    "@reasonabletech/config-eslint": "0.1.0",
+    "@reasonabletech/config-typescript": "0.1.0"
+  },
+  "license": "MIT",
+  "author": "Reasonable Tech Company",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ReasonableTech/core-utils.git",
+    "directory": "packages/config-tsup"
+  },
+  "bugs": {
+    "url": "https://github.com/ReasonableTech/core-utils/issues"
+  },
+  "homepage": "https://github.com/ReasonableTech/core-utils/tree/main/packages/config-tsup",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsup && tsc --emitDeclarationOnly -p tsconfig.build.json",
+    "clean": "rm -rf dist .turbo node_modules tsconfig.tsbuildinfo tsconfig.build.tsbuildinfo",
+    "dev": "tsup --watch",
+    "docs:coverage": "tsx ../../../scripts/analysis/check-doc-coverage.ts --html",
+    "lint": "eslint . --fix",
+    "lint:check": "eslint .",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:e2e": "vitest run tests/e2e",
+    "test:integration": "vitest run tests/integration",
+    "test:ui": "vitest --ui",
+    "test:unit": "vitest run tests/unit",
+    "test:watch": "vitest --watch",
+    "typecheck": "tsc --noEmit",
+    "verify:release": "pnpm typecheck && pnpm lint:check && pnpm test && pnpm build"
+  }
+}