next-bun-docker

Fix Next.js build issues when using Bun in Docker containers. This plugin resolves webpack configuration problems that occur when Bun spawns Node.js for webpack compilation in containerized environments.

The Problem

When building Next.js applications with Bun inside Docker containers, you may encounter:

• Module not found: Can't resolve '@/components/...' errors
• TypeScript path alias resolution failures
• Symlink-related issues in Docker's filesystem layer
• Build failures despite working locally

The Solution

This plugin automatically detects Bun+Docker environments and applies the necessary webpack fixes to ensure successful builds.

Installation

npm install next-bun-docker
# or
yarn add next-bun-docker
# or
pnpm add next-bun-docker
# or
bun add next-bun-docker

Usage

Basic Setup

// next.config.js
const { withBunDocker } = require('next-bun-docker');

module.exports = withBunDocker({
  // your existing Next.js config
});

With Options

// next.config.js
const { withBunDocker } = require('next-bun-docker');

module.exports = withBunDocker(
  {
    // your existing Next.js config
  },
  {
    // plugin options
    debug: true, // Enable debug logging
    aliases: {
      // Add custom path aliases
      '@custom': './src/custom',
    },
  }
);

TypeScript/ES Modules

// next.config.mjs
import { withBunDocker } from 'next-bun-docker';

export default withBunDocker({
  // your existing Next.js config
});

Docker Build

In your Dockerfile, ensure you set the environment variable:

FROM oven/bun:latest

WORKDIR /app
COPY . .

RUN bun install

# This helps the plugin detect the Docker environment
ENV DOCKER_BUILD=true

RUN bun run build

CMD ["bun", "run", "start"]

How It Works

The plugin:

1. Detects when running in a Bun+Docker environment
2. Disables webpack's symlink resolution (symlinks: false)
3. Explicitly configures TypeScript path aliases
4. Optimizes module resolution for containerized environments

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | aliases | object | {} | Additional path aliases to add to webpack config | | debug | boolean | false | Enable debug logging to see what changes are applied | | detectBun | function | Auto-detect | Custom function to determine if in Bun environment |

Default Path Aliases

The plugin automatically configures these common Next.js path aliases:

• @ → src/
• @/components → src/components/
• @/lib → src/lib/
• @/utils → src/utils/
• @/styles → src/styles/
• @/types → src/types/
• @/hooks → src/hooks/
• @/app → src/app/
• @/pages → src/pages/

Environment Detection

The plugin detects Bun+Docker environments by checking:

• DOCKER_BUILD=true environment variable
• BUN_RUNTIME=true environment variable
• Process argv containing 'bun'
• process.versions.bun presence

Troubleshooting

Build still failing?

1. Ensure you're using the latest version of Bun
2. Set DOCKER_BUILD=true in your Dockerfile
3. Enable debug mode to see what's happening:

   withBunDocker(config, { debug: true })

Custom detection needed?

withBunDocker(config, {
  detectBun: () => {
    // Your custom detection logic
    return process.env.MY_CUSTOM_ENV === 'true';
  }
})

Why This Exists

Next.js's webpack configuration makes assumptions about module resolution that break when:

• Bun spawns Node.js for webpack compilation
• Docker's filesystem layer affects symlink resolution
• TypeScript path aliases need explicit resolution in hybrid environments

This plugin bridges that gap until official support lands in Next.js core.

Development

This package is built with Bun (because we believe in it!):

bun install        # Install dependencies
bun run build:all  # Build with Bun + generate types
bun run test       # Run tests (when added)

Contributing

Issues and PRs welcome! If you encounter build issues with Bun+Docker+Next.js, please open an issue with:

• Your Next.js version
• Your Bun version
• Your Dockerfile
• The error message

License

MIT

Author

Created by vespo92 for the ESPO Engineering platform and the wider Next.js community.