makepack

A zero‑config (yet configurable) CLI to scaffold, develop, build, and publish modern JavaScript / TypeScript / React libraries.

Create a production‑ready npm package in seconds: pick a template, start a hot‑reloading dev server, bundle to ESM + CJS (and optionally a single bundle), generate type declarations, and publish – all with one tool.

---

✨ Features

• Rapid project creation with four templates:
  • TypeScript library
  • JavaScript library
  • React + TypeScript component library
  • React + JavaScript component library
• Development server with hot reload + optional Express middleware (express.ts / express.js)
• Automatic dependency graph tracking (via madge) for efficient reloads
• Incremental TypeScript compilation and declaration output
• Dual module build (esm, cjs, or both) with optional single bundled file
• Tree‑shaken and optionally minified output
• Sourcemaps & type declarations by default
• Clean build output in an isolated .mpack directory (publish‑ready)
• Simple release workflow (makepack release or npm run release guidance)

---

🚀 Quick Start

Install globally (recommended) or use npx.

npm install -g makepack            # global
# or
npx makepack create                # without global install

Create a new project:

makepack create
# Answer the interactive prompts:
#  - Project name
#  - Template

Enter the project (if created in a new folder) and start the dev server:

cd your-project
npm start

Build the library:

makepack build

Release (after building):

makepack release   # publishes the contents of ./.mpack to npm

Tip: You can also run via package scripts (auto‑generated or added manually): npm run build / npm run start.

---

📦 Generated Project Structure

Depending on template, you’ll get something like:

your-lib/
	package.json
	readme.md
	tsconfig.json (TypeScript templates)
	src/
		index.(ts|js|tsx|jsx)
		(React templates include an example component + export)

During development/build:

.mpack/          # Build output (cleaned & regenerated each build)
	package.json   # Stripped (scripts & "type" removed for publishing clarity)
	readme.md
	dist files     # ESM/CJS outputs + declarations + sourcemaps

Do not edit files inside .mpack directly. Treat it as a disposable publish directory.

---

🧪 Development Server

Run: makepack start --port 3000

Features:

• Hot reload on dependency change
• Optional custom Express bootstrap via a root express.ts or express.js exporting a default function (app) => { ... }
• Safe handler wrapping to catch async errors

Example express.ts:

import { Express } from 'express';

export default function routes(app: Express) {
	app.get('/health', (_req, res) => {
		res.json({ ok: true, ts: Date.now() });
	});
}

If present, it’s reloaded automatically when edited.

---

🏗 Build System

Command:

makepack build [options]

Option	Default	Values	Description
--format / -f	both	cjs, esm, both	Module formats to output
--bundle / -b	false	true/false	Bundle into a single file (rollup/esbuild assisted)
--minify / -m	false	true/false	Minify output (Terser)
--sourcemap / -s	true	true/false	Emit source maps
--declaration / -d	true	true/false	Emit TypeScript .d.ts files

Behavior notes:

• The tool auto‑detects src/index.(ts|js|tsx|jsx) as the entry.
• Boolean flags accept either actual booleans or string equivalents: --minify=true.
• Output is always placed in .mpack/ (cleaned each run).
• package.json in output has scripts and type removed for neutral publishing.

Example Builds

Dual build with declarations (default):

makepack build

ESM only, minified, bundled:

makepack build --format=esm --bundle=true --minify=true

Disable sourcemaps & declarations (faster):

makepack build -s=false -d=false

---

🚢 Releasing

1. Ensure you are logged in to npm: npm login
2. Build your package: makepack build
3. Publish from the generated directory:
   • Quick command: makepack release
   • Manual: cd .mpack && npm publish

The release command simply runs npm publish inside .mpack after verifying a build exists.

---

🔌 Express Integration (Optional)

Add express.ts or express.js in the project root. Export a default function receiving the Express app. Example with middleware:

import compression from 'compression';

export default function(app) {
	app.use(compression());
	app.get('/', (_req, res) => res.send('Hello from makepack dev server'));
}

The file and all its dependency graph (resolved via madge) are watched; edits trigger a reload.

---

🧬 Technology Stack

Area	Tooling
CLI	commander
Dev Server	express, vite, chokidar, madge
Builds	rollup, @rollup/plugin-*, esbuild, rollup-plugin-dts, terser
UX	inquirer, ora
FS/Utils	fs-extra, lodash.debounce

---

🛠 Templates Overview

Template	Use Case	Entry	Extras
typescript	Library in TypeScript	src/index.ts	tsconfig.json
javascript	Plain JS library	src/index.js	–
react with typescript	React component library (TSX)	src/index.tsx	React + types setup
react with javascript	React component library (JSX)	src/index.jsx	React setup

Generated React templates export a sample component you can replace.

---

🔄 Lifecycle Summary

1. create → scaffold + install deps
2. start → hot dev (optionally with express middleware)
3. build → produce distributable code in .mpack
4. release → publish the build to npm

---

📘 Command Reference

makepack create            # Interactive project scaffolding
makepack start --port 4000 # Start dev server on custom port
makepack build [flags]     # Build library
makepack release           # Publish from .mpack

See build flags in the Build System section.

---

🧩 Using From package.json

You can wire scripts (some templates already do this):

{
	"scripts": {
		"start": "makepack start --port 3000",
		"build": "makepack build",
		"release": "makepack release"
	}
}

Run with npm run build etc.

---

🧷 Best Practices

• Keep a clean root: limit extra build artifacts outside src/.
• Export your public API from a single src/index.*.
• Use semantic versioning (e.g. npm version patch).
• For React libraries, avoid bundling peer deps – list react & react-dom as peerDependencies in your own package.json before publishing.
• Add a LICENSE file (see below) – required for many consumers.

---

🐞 Troubleshooting

Issue	Cause	Fix
"No entry file found"	Missing src/index.*	Create src/index.ts or equivalent
Express not reloading	File outside dependency graph	Import files directly from `express.(ts
Declarations missing	--declaration=false or JS template	Use TS template or enable flag
Publish fails	Not built	Run makepack build first
ESM import errors	Missing "type": "module" in root	Add type back in your source project (it’s stripped only in .mpack)

---

🤝 Contributing

Contributions welcome! Suggested flow:

1. Fork & clone
2. Create a feature branch: git checkout -b feat/your-idea
3. Implement + add/update docs
4. Commit with conventional style: feat(build): add xyz
5. Open a PR

Please include clear reproduction steps for any bug fix.

Future Ideas (Open for PRs)

• Plugin system for custom build steps
• Peer dependency auto‑detection
• Template customization presets
• E2E test harness

---

🔐 Security

No network calls are performed beyond npm install/publish and user code execution. Always audit generated dependencies before publishing.

Report vulnerabilities via GitHub Issues (consider labeling as security). Avoid posting exploit details publicly – request a private channel if needed.

---

📄 License

License: TBD (e.g. MIT). Add a LICENSE file such as:

MIT License
Copyright (c) 2025 Devnax
Permission is hereby granted, free of charge, to any person obtaining a copy...

---

🙋 FAQ

Why strip scripts and type from the published package.json?
To minimize accidental exposure of internal scripts and to keep the distributed package neutral; consumers rarely need them.

Can I output only one format?
Yes: --format=esm or --format=cjs.

How do I include assets (e.g. CSS)?
Import them from your entry; configure rollup/esbuild plugins in future versions (PRs welcome) – currently you’d manually copy in a post-step.

Does it support monorepos?
Not natively; you can still run it per package folder.

Why another tool?
To reduce the ceremony of picking + wiring rollup, tsconfig, scripts, vite dev preview, express hooks, and publish layout – all unified.

---

📬 Support

Open an issue for bugs, ideas, or questions: https://github.com/devnax/makepack/issues

---

_{Built with ❤️ to streamline modern package creation.}