> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/zhcndoc/bun/llms.txt
> Use this file to discover all available pages before exploring further.

# Lifecycle Scripts

Lifecycle scripts run at specific points during package installation and other operations.

## Available scripts

### Installation scripts

Run during `bun install`:

* **`preinstall`** - Before package is installed
* **`install`** - After package is installed
* **`postinstall`** - After package and its dependencies are installed
* **`prepare`** - After package is installed and before publishing
* **`preprepare`** - Before `prepare`
* **`postprepare`** - After `prepare`

### Publishing scripts

Run during `bun publish`:

* **`prepublishOnly`** - Before package is published
* **`prepack`** - Before tarball is created
* **`postpack`** - After tarball is created
* **`publish`** - After package is published
* **`postpublish`** - After package is published

### Other scripts

Run during specific commands:

* **`preuninstall`** - Before package is removed
* **`uninstall`** - When package is removed
* **`postuninstall`** - After package is removed

## Defining scripts

Define lifecycle scripts in `package.json`:

```json theme={null}
{
  "scripts": {
    "preinstall": "echo 'About to install'",
    "install": "node-gyp rebuild",
    "postinstall": "bun run build",
    "prepare": "bun run build"
  }
}
```

## Execution order

### During `bun install`

For each package:

1. `preinstall`
2. Install package files
3. `install` / `postinstall` (of dependencies)
4. `postinstall` (of current package)
5. `preprepare` / `prepare` / `postprepare`

### During `bun publish`

1. `prepare`
2. `prepublishOnly`
3. `prepack`
4. Create tarball
5. `postpack`
6. Upload to registry
7. `publish`
8. `postpublish`

## Common use cases

### Build native modules

```json theme={null}
{
  "scripts": {
    "install": "node-gyp rebuild"
  }
}
```

### Build TypeScript

```json theme={null}
{
  "scripts": {
    "prepare": "tsc"
  }
}
```

### Download binaries

```json theme={null}
{
  "scripts": {
    "postinstall": "node scripts/download-binary.js"
  }
}
```

### Generate files

```json theme={null}
{
  "scripts": {
    "postinstall": "bun run codegen"
  }
}
```

### Setup database

```json theme={null}
{
  "scripts": {
    "postinstall": "bun run db:migrate"
  }
}
```

## Disabling scripts

### Skip all lifecycle scripts

```bash theme={null}
bun install --ignore-scripts
```

### Via bunfig.toml

```toml theme={null}
[install]
ignoreScripts = true
```

### Skip specific packages

Bun skips scripts for untrusted packages by default.

## Trusted dependencies

By default, Bun only runs scripts for trusted packages.

### Default trusted packages

Bun trusts these packages by default:

* `esbuild`
* `puppeteer`
* `sharp`
* `msgpackr-extract`
* `@biomejs/biome`
* Many more (see `bun pm default-trusted`)

### View default trusted list

```bash theme={null}
bun pm default-trusted
```

### Trust specific packages

Add to `trustedDependencies` in `package.json`:

```json theme={null}
{
  "trustedDependencies": [
    "my-package",
    "@myorg/another-package"
  ]
}
```

### Trust during install

```bash theme={null}
bun install --trust my-package
```

Or trust all:

```bash theme={null}
bun install --trust
```

### View untrusted dependencies

```bash theme={null}
$ bun pm untrusted
The following dependencies have install scripts but are not trusted:
  - puppeteer@21.0.0
  - electron@27.0.0

To trust them, run:
  bun pm trust puppeteer electron
```

### Trust untrusted dependencies

```bash theme={null}
bun pm trust puppeteer electron
```

Or trust all:

```bash theme={null}
bun pm trust --all
```

## Script environment

### Environment variables

Bun sets these variables:

* `npm_package_name` - Package name
* `npm_package_version` - Package version
* `npm_lifecycle_event` - Current script name
* `npm_lifecycle_script` - Current script command
* `INIT_CWD` - Original working directory

### Example

```json theme={null}
{
  "name": "my-package",
  "version": "1.0.0",
  "scripts": {
    "postinstall": "echo $npm_package_name@$npm_package_version"
  }
}
```

Output:

```
my-package@1.0.0
```

## Parallel execution

Bun runs scripts in parallel when possible.

### Set concurrency

```bash theme={null}
bun install --concurrent-scripts 4
```

### Via bunfig.toml

```toml theme={null}
[install]
concurrentScripts = 4
```

Default: Number of CPU cores

## Exit codes

### Success

Script exits with code `0`:

```json theme={null}
{
  "scripts": {
    "postinstall": "echo 'Done'"
  }
}
```

### Failure

Script exits with non-zero code:

```json theme={null}
{
  "scripts": {
    "postinstall": "exit 1"
  }
}
```

Bun fails the installation.

### Ignore failures

Prefix command with `-` to ignore failures:

```json theme={null}
{
  "scripts": {
    "postinstall": "-command-that-might-fail"
  }
}
```

## Shell

Bun uses the system shell to run scripts:

* **Unix**: `/bin/sh`
* **Windows**: `cmd.exe`

### Shell commands

```json theme={null}
{
  "scripts": {
    "postinstall": "echo 'Hello' && ls -la"
  }
}
```

### Node scripts

```json theme={null}
{
  "scripts": {
    "postinstall": "node scripts/setup.js"
  }
}
```

### Bun scripts

```json theme={null}
{
  "scripts": {
    "postinstall": "bun run scripts/setup.ts"
  }
}
```

## Workspace scripts

In monorepos, lifecycle scripts run for each workspace package.

### Root scripts

Run after all workspace packages:

```json theme={null}
{
  "workspaces": ["packages/*"],
  "scripts": {
    "postinstall": "echo 'All packages installed'"
  }
}
```

### Workspace package scripts

Run for each workspace:

```json theme={null}
// packages/app/package.json
{
  "scripts": {
    "postinstall": "bun run build"
  }
}
```

## Best practices

### Keep scripts fast

Slow scripts delay installations:

```json theme={null}
{
  "scripts": {
    // Bad: Slow compilation
    "postinstall": "npm run build:full",
    
    // Good: Fast setup
    "postinstall": "node scripts/quick-setup.js"
  }
}
```

### Use `prepare` for publishing

Build before publishing:

```json theme={null}
{
  "scripts": {
    "prepare": "bun run build"
  }
}
```

Runs before `bun publish` and after `bun install`.

### Don't use `postinstall` for building

Avoid building in `postinstall` for packages:

```json theme={null}
// Bad (in published package)
{
  "scripts": {
    "postinstall": "tsc"
  }
}

// Good (build before publishing)
{
  "scripts": {
    "prepare": "tsc",
    "prepublishOnly": "bun test"
  },
  "files": ["dist"]
}
```

### Check for required tools

```json theme={null}
{
  "scripts": {
    "preinstall": "node -v && bun -v"
  }
}
```

### Use `.bunignore`

Prevent scripts in development:

```
# .bunignore
node_modules/
```

## Debugging

### Verbose output

```bash theme={null}
bun install --verbose
```

Shows script execution:

```
Running postinstall script for my-package...
> bun run build

Build complete
```

### View script timing

Bun logs slow scripts (>500ms):

```
postinstall script for my-package took 1.2s
```

### Debug script failures

If a script fails:

```bash theme={null}
$ bun install

Error running postinstall for my-package:
  Command failed: exit code 1
  
Run with --verbose for more details
```

Debug:

```bash theme={null}
bun install --verbose
```

## Examples

### Build TypeScript package

```json theme={null}
{
  "name": "my-lib",
  "scripts": {
    "prepare": "tsc",
    "prepublishOnly": "bun test"
  },
  "files": ["dist"],
  "main": "dist/index.js",
  "types": "dist/index.d.ts"
}
```

### Download platform binary

```json theme={null}
{
  "scripts": {
    "postinstall": "node scripts/download-binary.js"
  }
}
```

**scripts/download-binary.js:**

```js theme={null}
const os = require('os');
const fs = require('fs');
const https = require('https');

const platform = os.platform();
const arch = os.arch();
const url = `https://example.com/binary-${platform}-${arch}`;

const file = fs.createWriteStream('bin/binary');
https.get(url, (response) => {
  response.pipe(file);
  file.on('finish', () => {
    fs.chmodSync('bin/binary', 0o755);
  });
});
```

### Native module compilation

```json theme={null}
{
  "scripts": {
    "install": "node-gyp rebuild"
  },
  "devDependencies": {
    "node-gyp": "^10.0.0"
  }
}
```

### Generate code

```json theme={null}
{
  "scripts": {
    "postinstall": "bun run generate",
    "generate": "bun run scripts/codegen.ts"
  }
}
```

### Setup development environment

```json theme={null}
{
  "scripts": {
    "postinstall": "bun run setup",
    "setup": "bun run db:migrate && bun run seed"
  }
}
```