nuxt-bun-compile 0.1.24 → 0.1.26

package/README.md

@@ -68,6 +68,7 @@ The module hooks into Nuxt's build pipeline and handles **everything** automatic
 | `enabled` | `boolean` | `true` | Enable/disable the module |
 | `outfile` | `string` | `"nuxtbin"` | Output binary filename |
 | `bunPath` | `string` | `undefined` | Path to the bun executable. Can be a directory (e.g., `/opt/bun/`) or a direct path to the binary (e.g., `/opt/bun/bun`). If it's a directory, '/bun' will be appended. Defaults to 'bun' from the system's PATH. |
+| `target` | `'bun-linux-x64' \| 'bun-linux-x64-musl' \| 'bun-linux-arm64' \| 'bun-linux-arm64-musl'` | `auto-detected` | Target platform for binary compilation. Auto-detects your system architecture (x64/arm64) and libc type (glibc/musl). Override only if auto-detection fails or you need a specific target. |
 | `extraExternals` | `(string \| RegExp)[]` | `[]` | Additional packages to mark as external |
 | `autoCompile` | `boolean` | `true` | Run `bun build --compile` automatically after build |
 
@@ -98,6 +99,32 @@ bunCompile: {
 
 ---
 
+## ⚠️ Native Dependencies in Alpine Linux
+
+When compiling with `--target=bun-linux-x64-musl` or `--target=bun-linux-arm64-musl` (Alpine), the resulting binary still dynamically links to `libstdc++` and `libgcc` at runtime. This is documented Bun behavior:
+
+- [oven-sh/bun#23910](https://github.com/oven-sh/bun/issues/23910)
+- [oven-sh/bun#918](https://github.com/oven-sh/bun/issues/918)
+
+### Solution: Install Required Libraries in Docker
+
+If running the binary in an Alpine Linux container, install the required libraries:
+
+```dockerfile
+FROM alpine:latest
+
+RUN apk add --no-cache libstdc++ libgcc
+
+COPY nuxtbin /app/
+WORKDIR /app
+
+CMD ["./nuxtbin"]
+```
+
+This ensures all runtime dependencies are available in the container.
+
+---
+
 ## 🏗️ Architecture
 
 The module uses a **hook-based architecture**:
@@ -145,6 +172,86 @@ The **`-b`** (or `--bun`) flag forces Bun to be the runtime that executes the sc
 
 ---
 
+## 📚 Usage Examples
+
+### Custom Build Script
+
+Create a dedicated npm script in your `package.json`:
+
+```json
+{
+  "scripts": {
+    "build": "nuxt build",
+    "compile": "NODE_OPTIONS=\"--max-old-space-size=8192\" bun run -b build"
+  }
+}
+```
+
+Then run: `bun run compile`
+
+### Docker Deployment
+
+Before building, create a `.dockerignore` file to exclude unnecessary files from the build context:
+
+```
+.claude
+.devcontainer
+.gemini
+.git
+.github
+.husky
+.nuxt
+.output
+.serena
+.vscode
+.yarn
+dist
+node_modules
+nuxtbin
+test
+tests
+```
+
+Deploy the compiled binary in a Docker container using multi-stage build:
+
+```dockerfile
+# Stage 1: Base image with Bun runtime
+FROM oven/bun:alpine AS bun-base
+WORKDIR /app
+
+# Stage 2: Install dependencies
+FROM bun-base AS bun-install
+COPY package.json bun.lockb ./
+RUN bun install --frozen-lockfile
+
+# Stage 3: Build the binary
+FROM bun-base AS bun-build
+COPY --from=bun-install /app/node_modules /app/node_modules
+COPY . .
+RUN NODE_OPTIONS="--max-old-space-size=8192" bun run -b build
+
+# Stage 4: Release (lightweight production image)
+FROM alpine:latest AS release
+EXPOSE 3000/tcp
+WORKDIR /app
+# Required libraries for Bun binaries on Alpine
+# See: https://github.com/oven-sh/bun/issues/23910
+#      https://github.com/oven-sh/bun/issues/918
+RUN apk add --no-cache libstdc++ libgcc
+COPY --from=bun-build /app/nuxtbin /app/nuxtbin
+CMD ["./nuxtbin"]
+```
+
+Build and run:
+```bash
+docker build -t my-nuxt-app .
+docker run -p 3000:3000 my-nuxt-app
+```
+
+> **Reference:** See the complete multi-stage example in [nuxt-duckdb-wasm/Dockerfile](https://github.com/jprando/nuxt-duckdb-wasm/blob/main/Dockerfile) for a production-ready setup.
+
+---
+
 ## 🧑‍💻 Development
 
 ### Testing Locally in a Nuxt App

package/README.ptBR.md

@@ -68,6 +68,7 @@ O módulo se conecta ao pipeline de build do Nuxt e cuida de **tudo** automatica
 | `enabled` | `boolean` | `true` | Habilitar/desabilitar o módulo |
 | `outfile` | `string` | `"nuxtbin"` | Nome do arquivo binário de saída |
 | `bunPath` | `string` | `undefined` | Caminho para o executável do bun. Pode ser um diretório (ex: `/opt/bun/`) ou o caminho direto para o binário (ex: `/opt/bun/bun`). Se for um diretório, '/bun' será anexado. O padrão é 'bun' do PATH do sistema. |
+| `target` | `'bun-linux-x64' \| 'bun-linux-x64-musl' \| 'bun-linux-arm64' \| 'bun-linux-arm64-musl'` | `auto-detectado` | Plataforma alvo para compilação do binário. Auto-detecta sua arquitetura (x64/arm64) e tipo de libc (glibc/musl). Sobrescreva apenas se a auto-detecção falhar ou você precisar de um target específico. |
 | `extraExternals` | `(string \| RegExp)[]` | `[]` | Pacotes adicionais para marcar como external |
 | `autoCompile` | `boolean` | `true` | Executar `bun build --compile` automaticamente após o build |
 
@@ -98,6 +99,32 @@ bunCompile: {
 
 ---
 
+## ⚠️ Dependências Nativas no Alpine Linux
+
+Ao compilar com `--target=bun-linux-x64-musl` ou `--target=bun-linux-arm64-musl` (Alpine), o binário resultante ainda faz link dinâmico com `libstdc++` e `libgcc` em tempo de execução. Este é um comportamento documentado do Bun:
+
+- [oven-sh/bun#23910](https://github.com/oven-sh/bun/issues/23910)
+- [oven-sh/bun#918](https://github.com/oven-sh/bun/issues/918)
+
+### Solução: Instalar Bibliotecas Necessárias no Docker
+
+Se rodar o binário em um container Alpine Linux, instale as bibliotecas necessárias:
+
+```dockerfile
+FROM alpine:latest
+
+RUN apk add --no-cache libstdc++ libgcc
+
+COPY nuxtbin /app/
+WORKDIR /app
+
+CMD ["./nuxtbin"]
+```
+
+Isso garante que todas as dependências de runtime estejam disponíveis no container.
+
+---
+
 ## 🏗️ Arquitetura
 
 O módulo usa uma **arquitetura baseada em hooks**:
@@ -145,6 +172,86 @@ O parâmetro **`-b`** (ou `--bun`) força o Bun a ser o runtime que executa o sc
 
 ---
 
+## 📚 Exemplos de Uso
+
+### Script Customizado de Build
+
+Crie um script npm/bun dedicado no seu `package.json`:
+
+```json
+{
+  "scripts": {
+    "build": "nuxt build",
+    "compile": "NODE_OPTIONS=\"--max-old-space-size=8192\" bun run -b build"
+  }
+}
+```
+
+Execute com: `bun run compile`
+
+### Deploy com Docker
+
+Antes de compilar, crie um arquivo `.dockerignore` para excluir arquivos desnecessários do contexto de build:
+
+```
+.claude
+.devcontainer
+.gemini
+.git
+.github
+.husky
+.nuxt
+.output
+.serena
+.vscode
+.yarn
+dist
+node_modules
+nuxtbin
+test
+tests
+```
+
+Faça deploy do binário compilado em um container Docker usando multi-stage build:
+
+```dockerfile
+# Estágio 1: Imagem base com runtime Bun
+FROM oven/bun:alpine AS bun-base
+WORKDIR /app
+
+# Estágio 2: Instalar dependências
+FROM bun-base AS bun-install
+COPY package.json bun.lockb ./
+RUN bun install --frozen-lockfile
+
+# Estágio 3: Compilar o binário
+FROM bun-base AS bun-build
+COPY --from=bun-install /app/node_modules /app/node_modules
+COPY . .
+RUN NODE_OPTIONS="--max-old-space-size=8192" bun run -b build
+
+# Estágio 4: Release (imagem de produção otimizada)
+FROM alpine:latest AS release
+EXPOSE 3000/tcp
+WORKDIR /app
+# Bibliotecas necessárias para binários Bun no Alpine
+# Ver: https://github.com/oven-sh/bun/issues/23910
+#      https://github.com/oven-sh/bun/issues/918
+RUN apk add --no-cache libstdc++ libgcc
+COPY --from=bun-build /app/nuxtbin /app/nuxtbin
+CMD ["./nuxtbin"]
+```
+
+Build e execute:
+```bash
+docker build -t minha-app-nuxt .
+docker run -p 3000:3000 minha-app-nuxt
+```
+
+> **Referência:** Veja um exemplo completo com multi-stage em [nuxt-duckdb-wasm/Dockerfile](https://github.com/jprando/nuxt-duckdb-wasm/blob/main/Dockerfile) para um setup pronto para produção.
+
+---
+
 ## 🧑‍💻 Desenvolvimento
 
 ### Testando Localmente em uma Aplicação Nuxt

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-bun-compile",
   "configKey": "bunCompile",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-bun-compile",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "description": "Nuxt module that automatically configures Nitro for `bun build --compile`, generating a standalone executable binary from your Nuxt app.",
   "repository": "jprando/nuxt-bun-compile",
   "license": "MIT",