next-bun-docker/README.md

Next.js plugin to fix Bun + Docker build issues with webpack and TypeScript path aliases

# 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

```bash
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

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

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

### With Options

```js
// 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

```ts
// 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:

```dockerfile
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:
   ```js
   withBunDocker(config, { debug: true })
   ```

### Custom detection needed?

```js
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!):

```bash
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.