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 (Zero Config)

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

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

That's it! The plugin automatically:

• Reads path aliases from your tsconfig.json
• Detects Bun+Docker environments
• Applies the necessary webpack fixes

With Debug Mode

When troubleshooting, enable debug mode to see exactly what's happening:

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

module.exports = withBunDocker(
  {
    // your existing Next.js config
  },
  {
    debug: true, // Shows detection reason, aliases loaded, and configuration applied
  }
);

Example debug output:

🔧 next-bun-docker: Detected Bun environment
   Reason: DOCKER_BUILD=true
   Build type: server
   📖 Loaded 3 aliases from tsconfig.json
   📁 9/12 alias paths exist

✅ next-bun-docker: Configuration applied
   • Symlinks: disabled
   • Aliases: 12 configured
   • Extensions: .ts, .tsx, .js, .jsx, .json

With Custom Options

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

module.exports = withBunDocker(
  {
    // your existing Next.js config
  },
  {
    debug: true,
    aliases: {
      '@custom': './src/custom', // Additional aliases (highest priority)
    },
    loadTsConfig: true,           // Auto-load from tsconfig.json (default: true)
    tsConfigPath: 'tsconfig.json' // Custom tsconfig path (default: 'tsconfig.json')
  }
);

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, set the environment variable for reliable detection:

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 (via env vars, process.argv, or process.versions)
2. Reads path aliases from your tsconfig.json automatically
3. Disables webpack's symlink resolution (symlinks: false)
4. Configures TypeScript path aliases for webpack
5. Optimizes module resolution for containerized environments

Configuration Options

Option	Type	Default	Description
aliases	Record<string, string>	{}	Additional path aliases (highest priority, overrides tsconfig)
debug	boolean	false	Enable debug logging with detailed output
detectBun	() => boolean	Auto-detect	Custom function to determine if in Bun environment
loadTsConfig	boolean	true	Auto-load path aliases from tsconfig.json
tsConfigPath	string	'tsconfig.json'	Path to tsconfig.json (relative to project root)

Alias Priority

When multiple alias sources exist, they are merged with this priority (highest wins):

1. User-provided aliases (via aliases option)
2. tsconfig.json paths (auto-loaded)
3. Default aliases (fallback)

Default Path Aliases

The plugin provides these fallback aliases when not found in tsconfig:

• @ → 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 (in order):

1. DOCKER_BUILD=true environment variable
2. BUN_RUNTIME=true environment variable
3. Process argv containing 'bun'
4. process.versions.bun presence

Troubleshooting

Build still failing?

1. Enable debug mode to see what's happening:

   withBunDocker(config, { debug: true })

2. Check the debug output:

   • Is Bun being detected? (look for "Detected Bun environment")
   • Are your tsconfig aliases being loaded?
   • Do the alias paths exist?

3. Ensure you're using the latest version of Bun

4. Set DOCKER_BUILD=true in your Dockerfile

Custom detection needed?

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

Using a custom tsconfig path?

// For monorepos or custom setups
withBunDocker(config, {
  tsConfigPath: 'tsconfig.app.json'
})

Want to disable tsconfig auto-loading?

withBunDocker(config, {
  loadTsConfig: false,
  aliases: {
    // Manually specify all your aliases
    '@': './src',
  }
})

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
bun run test:watch # Run tests in watch mode
bun run typecheck  # Type check without emitting
bun run lint       # Check code with Biome
bun run lint:fix   # Auto-fix lint issues
bun run check      # Run all checks (types + lint + tests)
bun run dev        # Build and start test watcher

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
• Debug output (debug: true)

License

MIT

Author

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