https://github.com/refinist/distpkg
Post-build tool that generates minimal package.json in dist/ and re-installs deps to ensure bundled code runs correctly
https://github.com/refinist/distpkg
build-tool bun bundler cli dependencies deployment dist docker node package-json post-build secondary-install typescript
Last synced: 26 days ago
JSON representation
Post-build tool that generates minimal package.json in dist/ and re-installs deps to ensure bundled code runs correctly
- Host: GitHub
- URL: https://github.com/refinist/distpkg
- Owner: refinist
- License: mit
- Created: 2025-08-19T03:07:17.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2025-09-09T13:07:21.000Z (28 days ago)
- Last Synced: 2025-09-09T16:31:30.453Z (28 days ago)
- Topics: build-tool, bun, bundler, cli, dependencies, deployment, dist, docker, node, package-json, post-build, secondary-install, typescript
- Language: TypeScript
- Homepage: https://npmjs.com/distpkg
- Size: 212 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
distpkg
A tool for post-build projects (generally used after bundling into a single file with 
(bun) or node, etc.), which generates a minimal package.json in the dist directory. Then, by running install again in the dist directory, it ensures that the final code can execute correctly.
## Why do we need to install again?
Because some packages may depend on the current environment, or some packages may only determine at runtime that they need to load their dependencies (which might be installed directly in `node_modules/some-package`). Therefore, we need to extract these "special" packages separately. For example, put foo in the dependencies of dist/package.json, so that by running install again in the dist directory, we can ensure the code executes correctly!
## Why bundle? π€¨
[Why bundle?](https://bun.sh/docs/bundler#why-bundle) Let's read this article together. This is Bun's summary, and although it focuses more on frontend applications, in my opinion, bundling definitely brings benefits: 1. Easier to publish 2. Smaller package size 3. More convenient for handling obfuscation and similar logic.
## Features
- π **Fast and Simple**: Quickly generate dist/package.json
- π¦ **Flexible Configuration**: Support both CLI options and config files
- π§ **Customizable**: Choose which package.json fields to include
- π **TypeScript Support**: Full TypeScript support with type definitions
- π **Auto Sorting**: Automatically sort package.json fields, perfect for OCD
- β
**100% Test Coverage**: Project stability and reliability guaranteed
- **Bun Perfect Integration**: Optimized for Bun single-file bundling, seamless integration
## Installation
```bash
# pnpm
pnpm add -D distpkg
# bun
bun add -D distpkg
# npm
npm install -D distpkg
# yarn
yarn add -D distpkg
```
## Quick Start
### Basic Usage (Only 2 Steps)
1. Configure scripts in package.json
```json
{
"scripts": {
"build": "pnpm run build:project && distpkg",
"build:project": "your build command"
}
}
```
2. Configure distpkg.config.ts
```typescript
// distpkg.config.ts
import { defineConfig } from 'distpkg';
export default defineConfig({
packageJson: {
dependencies: {
foo: '^1.0.0'
/* more dependencies */
}
}
});
```
> [!TIP]
> When building your project, you should exclude the foo package, such as `"build": "bun build src/index.ts --target bun --outdir=dist --bytecode --minify --external foo"`
## CLI Options
```
Usage:
$ distpkg [...package-keys]
Commands:
[...package-keys] Keys to copy from project package.json to dist/package.json
For more info, run any command with the `--help` flag:
$ distpkg --help
Options:
-c, --config Use a custom config file
-d, --out-dir Output directory (default: dist)
--cwd Working directory (default: process.cwd())
-s, --sort Sort package.json (default: true)
-h, --help Display this message
-v, --version Display version number
```
### Programmatic Usage
```typescript
import { build } from 'distpkg';
// your build js
// ...
const result = await build({
/* ... */
});
if (!result.success) {
console.error('Build failed with errors:', result.message);
}
```
## Docker Deployment
With this tool, our project best practices should be as follows (personal opinion only):
install -> build -> cd dist -> install -> package into image -> deploy to docker -> deploy successfully and start service
## License
[MIT](./LICENSE)
Copyright (c) 2025-present, Zhifeng (Jeff) Wang