Bun Standalone API Heroku Buildpack

This is a custom Heroku buildpack designed to deploy Node.js applications using Bun runtime, specifically targeting applications in the standalone-api directory.

Features

• Installs Bun runtime (version 1.0.25)
• Automatically detects and uses the standalone-api directory as the working directory
• Handles both bun.lockb and package.json files
• Supports build scripts and automatic dependency installation
• Provides fallback startup mechanisms

Usage

1. Using with Heroku CLI

# Set this buildpack for your Heroku app
heroku buildpacks:set https://github.com/yourusername/yourrepo.git -a your-app-name

# Or add it to existing buildpacks
heroku buildpacks:add https://github.com/yourusername/yourrepo.git -a your-app-name

2. Using with app.json

{
  "buildpacks": [
    {
      "url": "https://github.com/yourusername/yourrepo.git"
    }
  ]
}

3. Project Structure

The buildpack expects your project to have one of these structures:

your-project/
├── standalone-api/
│   ├── package.json
│   ├── bun.lockb (optional)
│   └── src/
│       └── index.js
└── ...

Or if standalone-api doesn't exist:

your-project/
├── package.json
├── bun.lockb (optional)
└── src/
    └── index.js

Build Process

1. Detection: Checks for package.json or bun.lockb in standalone-api/ or root directory
2. Bun Installation: Downloads and installs Bun runtime
3. Dependency Installation: Runs bun install --production
4. Build: Runs bun run build if build script exists
5. Runtime Setup: Creates startup script for production

Startup Process

The buildpack creates a start.sh script that:

1. Sets up the PATH to include Bun
2. Navigates to standalone-api if it exists
3. Attempts to run the start script: bun run start
4. Falls back to the main file specified in package.json

Environment Variables

The buildpack automatically sets:

• PATH: Includes the Bun binary location

Requirements

• Your application must have a package.json file
• For optimal performance, include a bun.lockb file
• Include a start script in your package.json or specify a main field

Example package.json

{
  "name": "standalone-api",
  "version": "1.0.0",
  "main": "src/index.js",
  "scripts": {
    "start": "bun run src/index.js",
    "build": "bun run build-script.js"
  },
  "dependencies": {
    "express": "^4.18.0"
  }
}

Troubleshooting

1. Build fails: Check that your package.json is valid and dependencies are correctly specified
2. Start fails: Ensure you have a start script or valid main field in package.json
3. Dependencies not found: Make sure you're using dependencies that are compatible with Bun

Support

This buildpack is designed specifically for applications using Bun runtime with the standalone-api directory structure.