prepare-package 2.0.7 → 2.1.0

package/README.md

@@ -46,6 +46,7 @@ npx prepare-package
 * Two modes: **copy** (default) and **bundle** (esbuild)
 * Copy mode: copies `src/` to `dist/`, replaces `{version}` in main file
 * Bundle mode: builds ESM, CJS, and/or IIFE outputs via esbuild
+* **Before/after hooks** — run arbitrary shell commands as part of the prepare lifecycle
 * Blocks `npm publish` when local `file:` dependencies are detected
 * Cleans up sensitive files (`.env`, `.DS_Store`, etc.) before publish
 * Purges jsDelivr CDN cache after publish
@@ -140,6 +141,45 @@ To override the footer, set `build.cjs.footer` in your config.
 #### IIFE global export
 The IIFE build automatically unwraps the default export so `window[globalName]` is the class/function directly, not a `{ default }` wrapper.
 
+### Hooks
+
+Run arbitrary shell commands before or after the copy/bundle step. Useful for fetching remote data, generating files, uploading artifacts, or running any command that needs to happen as part of the prepare lifecycle — so the output lands in both your git commits and your published tarball.
+
+```json
+{
+  "preparePackage": {
+    "input": "src",
+    "output": "dist",
+    "hooks": {
+      "before": "node scripts/update-disposable-domains.js",
+      "after": "node scripts/notify-deploy.js"
+    }
+  }
+}
+```
+
+| Hook | When it runs | On failure |
+|------|-------------|-----------|
+| `before` | After publish safety checks, before the copy/bundle step | **Blocks** — throws and aborts prepare |
+| `after` | After the copy/bundle step, before the CDN purge | **Warns** — logs a warning and continues |
+
+Both hooks accept a single command string or an array of commands:
+
+```json
+{
+  "preparePackage": {
+    "hooks": {
+      "before": [
+        "node scripts/update-disposable-domains.js",
+        "node scripts/build-manifest.js"
+      ]
+    }
+  }
+}
+```
+
+Commands run synchronously from the package root with `stdio` inherited, so their output appears in the parent process. Hooks are **skipped** in watch mode (single-file updates) and during postinstall — they only run on full prepare runs (`npm run prepare`, `npm publish`, etc.).
+
 ## Usage
 
 ```shell

package/dist/index.js

@@ -1,9 +1,66 @@
 const jetpack = require('fs-jetpack');
 const fetch = require('wonderful-fetch');
 const path = require('path');
+const { spawn } = require('child_process');
 const { default: chalk } = require('chalk');
 const logger = require('./logger');
 
+/**
+ * Run a single shell command and resolve/reject when it exits.
+ * Streams stdio to the parent process so output is visible during prepare/publish.
+ *
+ * @param {string} cmd - Shell command to run
+ * @param {string} cwd - Working directory for the command
+ * @returns {Promise<void>} - Resolves on exit code 0, rejects otherwise
+ */
+function runCommand(cmd, cwd) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, {
+      cwd: cwd,
+      stdio: 'inherit',
+      shell: true,
+    });
+
+    child.on('error', reject);
+    child.on('exit', (code) => {
+      if (code === 0) {
+        return resolve();
+      }
+      return reject(new Error(`Command exited with code ${code}`));
+    });
+  });
+}
+
+/**
+ * Run a hook command (or array of commands) sequentially from the consumer's cwd.
+ *
+ * @param {string|string[]} command - Shell command(s) to run
+ * @param {string} cwd - Working directory for the command
+ * @param {string} label - 'before' or 'after' (used in logs)
+ * @param {boolean} blocking - If true, throws on failure; if false, warns and continues
+ */
+async function runHook(command, cwd, label, blocking) {
+  if (!command) {
+    return;
+  }
+
+  const commands = Array.isArray(command) ? command : [command];
+
+  for (const cmd of commands) {
+    logger.log(chalk.cyan(`Running ${label} hook: ${cmd}`));
+
+    try {
+      await runCommand(cmd, cwd);
+    } catch (e) {
+      if (blocking) {
+        logger.error(`${label} hook failed: ${cmd}`);
+        throw e;
+      }
+      logger.error(chalk.yellow(`${label} hook failed (non-blocking): ${cmd} — ${e.message}`));
+    }
+  }
+}
+
 // const argv = require('yargs').argv;
 
 // Helper function to check for local dependencies
@@ -111,6 +168,7 @@ module.exports = async function (options) {
   theirPackageJSON.preparePackage.output = theirPackageJSON.preparePackage.output || './dist';
   theirPackageJSON.preparePackage.replace = theirPackageJSON.preparePackage.replace || {};
   theirPackageJSON.preparePackage.type = theirPackageJSON.preparePackage.type || 'copy';
+  theirPackageJSON.preparePackage.hooks = theirPackageJSON.preparePackage.hooks || {};
 
   // Add script
   theirPackageJSON.scripts = theirPackageJSON.scripts || {};
@@ -138,6 +196,13 @@ module.exports = async function (options) {
     });
   }
 
+  // Run the `before` hook
+  // Only runs on live preparation (not on prepare-package's own build) and never in postinstall
+  // or single-file watch mode (which runs on every file change).
+  if (isLivePreparation && !options.isPostInstall && !options.singleFile) {
+    await runHook(theirPackageJSON.preparePackage.hooks.before, options.cwd, 'before', true);
+  }
+
   // --- BUNDLE MODE ---
   if (isBundleMode) {
     const { build } = require('./build');
@@ -225,6 +290,12 @@ module.exports = async function (options) {
     // ... moveed to another package
   }
 
+  // Run the `after` hook
+  // Non-blocking — failures warn but don't break the prepare flow (same philosophy as CDN purge).
+  if (isLivePreparation && !options.isPostInstall && !options.singleFile) {
+    await runHook(theirPackageJSON.preparePackage.hooks.after, options.cwd, 'after', false);
+  }
+
   // If purge is disabled, then return
   if (options.purge === false) {
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prepare-package",
-  "version": "2.0.7",
+  "version": "2.1.0",
   "description": "Prepare a Node.js package before being published",
   "main": "dist/index.js",
   "bin": {
@@ -48,9 +48,9 @@
   "dependencies": {
     "chalk": "^5.6.2",
     "chokidar": "^5.0.0",
-    "esbuild": "^0.27.4",
+    "esbuild": "^0.28.0",
     "fs-jetpack": "^5.1.0",
-    "wonderful-fetch": "^2.0.4"
+    "wonderful-fetch": "^2.0.5"
   },
   "devDependencies": {
     "mocha": "^11.7.5"