npm - nuxt-bun-compile - Versions diffs - 0.1.26 → 0.1.28 - Mend

nuxt-bun-compile 0.1.26 → 0.1.28

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -2,7 +2,7 @@
 [![Socket Badge](https://badge.socket.dev/npm/package/nuxt-bun-compile/0.1.0)](https://badge.socket.dev/npm/package/nuxt-bun-compile/0.1.0)
-![Logo Nuxt Bun Compile](/images/logo-transparent--nuxt-bun-compile.png "Logo Nuxt Bun Compile")
+<img src="/images/logo-transparent--nuxt-bun-compile.png" alt="Logo Nuxt Bun Compile" width="50%">
 > 🚀 Nuxt module that automatically configures Nitro for `bun build --compile`, generating a **standalone executable binary** from your Nuxt app — zero runtime dependencies needed.
@@ -24,9 +24,9 @@ bun nuxt add nuxt-bun-compile
 bun run -b build
 ```
-[Why is `-b` required?](https://github.com/jprando/nuxt-bun-compile?tab=readme-ov-file#why-is--b-required)
+[Why is `-b` required?](/docs/ARCHITECTURE.md#why-is--b-required)
-[If you encounter memory issues during build](https://github.com/jprando/nuxt-bun-compile?tab=readme-ov-file#why-node_options--max-old-space-size8192)
+[If you encounter memory issues during build](/docs/NOTES.md#why-node_options--max-old-space-size8192)
 **Step 3: Run your binary**
@@ -41,240 +41,15 @@ That's it. One binary. No `node_modules`. No runtime. Just your app.
 ---
-## 🎯 What It Does
-The module hooks into Nuxt's build pipeline and handles **everything** automatically:
-1. **Configures Nitro** with the optimal settings for binary compilation
-2. **Externalizes problematic packages** that break with full bundling
-3. **Runs `bun build --compile`** after the build to produce a standalone executable
-### Nitro Configuration (auto-applied)
-| Setting | Value | Why |
-|---|---|---|
-| `preset` | `"bun"` | Target the Bun runtime |
-| `noExternals` | `true` | Bundle everything into the output |
-| `inlineDynamicImports` | `true` | Flatten dynamic imports for single-file output |
-| `serveStatic` | `"inline"` | Embed static assets in the binary |
-| `esbuild.options.target` | `"esnext"` | Use latest JS features for maximum performance |
----
-## ⚙️ Options
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `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 |
----
-## 📦 Default External Packages
-These packages are known to break with `noExternals: true` and are excluded by default:
-| Package | Pattern |
-|---|---|
-| sharp | `sharp` |
-| @img | `@img/*` |
-| css-tree | `css-tree`, `css-tree/*` |
-| csso | `csso`, `csso/*` |
-| svgo | `svgo` |
-| mdn-data | `mdn-data`, `mdn-data/*` |
-Need to add more? Use `extraExternals`:
-```ts
-bunCompile: {
-  extraExternals: ["problematic-package", /^@scope\//],
-}
-```
-> **⚠️ Important:** Libraries listed in `extraExternals` (as well as the default externals) are **not embedded in the binary**. For the `nuxtbin` binary to run correctly, these dependencies must be available in a `node_modules` folder alongside the generated binary.
----
-## ⚠️ 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**:
-- **`nitro:config`** — Adjusts Nitro settings (preset, externals, bundling)
-- **`nitro:compiled`** — Triggers `bun build --compile` after Nitro finishes building the server
-### How It Works
-```
-bun run -b build
-    │
-    ├─ nitro:config hook ──▶ Configure preset, bundling, externals
-    │
-    ├─ Nuxt/Nitro build pipeline runs normally
-    │
-    └─ nitro compiled hook ──▶ bun build .output/server/index.mjs --compile --outfile <name>
-                                   │
-                                   └──▶ 🎉 Standalone binary ready!
-```
-### Why is `-b` required?
-When you run `bun run build` (without `-b`), Bun acts as a **task runner** and may delegate script execution to Node.js. In that scenario, `globalThis.Bun` and `process.versions.bun` **do not exist**, and the module cannot detect the Bun runtime:
-```ts
-const isBun = typeof globalThis.Bun !== "undefined"
-  || process.versions.bun !== undefined;
-```
-[src/module.ts:L70-L76](https://github.com/jprando/nuxt-bun-compile/blob/main/src/module.ts#L70-L76)
-The **`-b`** (or `--bun`) flag forces Bun to be the runtime that executes the script. With it, the variables above become available and the `bun build --compile` step runs correctly.
----
-## 🛠️ Tech Stack
-| | Technology | Details |
-|---|---|---|
-| 🔤 | **TypeScript** | ESNext target, strict mode, bundler resolution |
-| 🐰 | **Bun** | Runtime 1.3.9+, package manager |
-| 💚 | **Nuxt** | 4.x |
-| 📐 | **dprint** | Code formatter (TS, JSON, MD, TOML, YAML, and more) |
-| 📦 | **ESM** | Pure ES modules (`"type": "module"`) |
----
-## 📚 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
-```bash
-# 1. Clone this repo for local development
-git clone https://github.com/jprando/nuxt-bun-compile.git
-# 2. Link the module
-cd nuxt-bun-compile && bun install && bun prepack && bun link
-# 3. Use it in your Nuxt app
-cd your-nuxt-app && bun link nuxt-bun-compile
-# 4. Add to nuxt.config.ts modules array
-bun nuxt add nuxt-bun-compile
-# 5. Build
-NODE_OPTIONS="--max-old-space-size=8192" bun run -b build
-# 6. Run the binary
-./nuxtbin
-```
+- [🎯 What It Does](/docs/WHAT-IT-DOES.md)
+- [⚙️ Options](/docs/OPTIONS.md)
+- [📦 Default External Packages](/docs/DEFAULT-EXTERNAL-PACKAGES.md)
+- [⚠️ Native Dependencies in Alpine Linux](/docs/NATIVE-DEPENDENCIES-IN-ALPINE-LINUX.md)
+- [🏗️ Architecture](/docs/ARCHITECTURE.md)
+- [📚 Usage Examples](/docs/USAGE-EXAMPLES.md)
+- [🧑‍💻 Development](/docs/DEVELOPMENT.md)
+- [🛠️ Tech Stack](/docs/TECH-STACK.md)
+- [📝 Notes](/docs/NOTES.md)
 ---
@@ -286,22 +61,6 @@ NODE_OPTIONS="--max-old-space-size=8192" bun run -b build
 ---
-## 📝 Notes
-### Why `NODE_OPTIONS="--max-old-space-size=8192"`?
-The Nuxt build process with `noExternals: true` and `inlineDynamicImports: true` causes Rollup/esbuild to bundle **all** dependencies into a single output. In projects with many dependencies, this can consume more memory than the default V8 heap limit (approximately 1.5–2 GB), resulting in the error:
-```
-FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
-```
-The `NODE_OPTIONS="--max-old-space-size=8192"` variable increases the V8 heap memory limit to 8 GB, providing enough headroom for the bundling process to complete. The value of `8192` (MB) is a safe reference for most projects — adjust as needed for larger projects or machines with less RAM.
-> **Note:** This variable affects the Node.js/V8 process that runs the Nuxt build, not the final binary generated by `bun build --compile`.
----
 ## 📄 License
 MIT

package/README.ptBR.md CHANGED Viewed

@@ -2,7 +2,7 @@
 [![Socket Badge](https://badge.socket.dev/npm/package/nuxt-bun-compile/0.1.0)](https://badge.socket.dev/npm/package/nuxt-bun-compile/0.1.0)
-![Logo Nuxt Bun Compile](/images/logo-transparent--nuxt-bun-compile.png "Logo Nuxt Bun Compile")
+<img src="/images/logo-transparent--nuxt-bun-compile.png" alt="Logo Nuxt Bun Compile" width="50%">
 > 🚀 Módulo Nuxt que configura automaticamente o Nitro para `bun build --compile`, gerando um **binário executável standalone** a partir da sua aplicação Nuxt — sem dependências de runtime.
@@ -24,9 +24,9 @@ bun nuxt add nuxt-bun-compile
 bun run -b build
 ```
-[Por que é necessário o parâmetro `-b`?](https://github.com/jprando/nuxt-bun-compile/blob/main/README.ptBR.md#por-que--b-%C3%A9-obrigat%C3%B3rio)
+[Por que é necessário o parâmetro `-b`?](/docs/ARCHITECTURE.ptBR.md#por-que--b-é-obrigatório)
-[Se você enfrentar problemas de memória durante a compilação](https://github.com/jprando/nuxt-bun-compile/blob/main/README.ptBR.md#por-que-node_options--max-old-space-size8192)
+[Se você enfrentar problemas de memória durante a compilação](/docs/NOTES.ptBR.md#por-que-node_options--max-old-space-size8192)
 **Passo 3: Executar seu binário**
@@ -41,240 +41,15 @@ Só um binário. Sem `node_modules`. Sem runtime. Apenas sua aplicação.
 ---
-## 🎯 O que Faz
-O módulo se conecta ao pipeline de build do Nuxt e cuida de **tudo** automaticamente:
-1. **Configura o Nitro** com as configurações ótimas para compilação em binário
-2. **Externaliza pacotes problemáticos** que quebram com bundling completo
-3. **Executa `bun build --compile`** após o build para produzir um executável standalone
-### Configuração do Nitro (aplicada automaticamente)
-| Configuração | Valor | Motivo |
-|---|---|---|
-| `preset` | `"bun"` | Usar o runtime Bun como alvo |
-| `noExternals` | `true` | Empacotar tudo no output |
-| `inlineDynamicImports` | `true` | Achatar imports dinâmicos para output em arquivo único |
-| `serveStatic` | `"inline"` | Embutir assets estáticos no binário |
-| `esbuild.options.target` | `"esnext"` | Usar as features JS mais recentes para máximo desempenho |
----
-## ⚙️ Opções
-| Opção | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `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 |
----
-## 📦 Pacotes External Padrão
-Estes pacotes são conhecidos por quebrar com `noExternals: true` e são excluídos por padrão:
-| Pacote | Pattern |
-|---|---|
-| sharp | `sharp` |
-| @img | `@img/*` |
-| css-tree | `css-tree`, `css-tree/*` |
-| csso | `csso`, `csso/*` |
-| svgo | `svgo` |
-| mdn-data | `mdn-data`, `mdn-data/*` |
-Precisa adicionar mais? Use `extraExternals`:
-```ts
-bunCompile: {
-  extraExternals: ["problematic-package", /^@scope\//],
-}
-```
-> **⚠️ Importante:** As bibliotecas listadas em `extraExternals` (assim como as externals padrão) **não são embutidas no binário**. Para que o binário `nuxtbin` execute corretamente, essas dependências precisam estar disponíveis em uma pasta `node_modules` ao lado do binário gerado.
----
-## ⚠️ 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**:
-- **`nitro:config`** — Ajusta configurações do Nitro (preset, externals, bundling)
-- **`nitro:compiled`** — Aciona `bun build --compile` após o Nitro terminar o build do servidor
-### Como Funciona
-```
-bun run -b build
-    │
-    ├─ hook nitro:config ──▶ Configura preset, bundling, externals
-    │
-    ├─ Pipeline de build Nuxt/Nitro executa normalmente
-    │
-    └─ hook nitro compiled ──▶ bun build .output/server/index.mjs --compile --outfile <nome>
-                                   │
-                                   └──▶ 🎉 Binário standalone pronto!
-```
-### Por que `-b` é obrigatório?
-Quando você executa `bun run build` (sem `-b`), o Bun age como um **gerenciador de tarefas** e pode delegar a execução do script ao Node.js. Nesse cenário, as variáveis `globalThis.Bun` e `process.versions.bun` **não existem**, e o módulo não consegue detectar o runtime Bun:
-```ts
-const isBun = typeof globalThis.Bun !== "undefined"
-  || process.versions.bun !== undefined;
-```
-[src/module.ts:L70-L76](https://github.com/jprando/nuxt-bun-compile/blob/main/src/module.ts#L70-L76)
-O parâmetro **`-b`** (ou `--bun`) força o Bun a ser o runtime que executa o script. Com ele, as variáveis acima ficam disponíveis e a etapa de `bun build --compile` é executada corretamente.
----
-## 🛠️ Tech Stack
-| | Tecnologia | Detalhes |
-|---|---|---|
-| 🔤 | **TypeScript** | Target ESNext, strict mode, bundler resolution |
-| 🐰 | **Bun** | Runtime 1.3.9+, gerenciador de pacotes |
-| 💚 | **Nuxt** | 4.x |
-| 📐 | **dprint** | Formatador de código (TS, JSON, MD, TOML, YAML e mais) |
-| 📦 | **ESM** | ES modules puro (`"type": "module"`) |
----
-## 📚 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
-```bash
-# 1. Clone este repositório para desenvolvimento local
-git clone https://github.com/jprando/nuxt-bun-compile.git
-# 2. Linke o módulo
-cd nuxt-bun-compile && bun install && bun prepack && bun link
-# 3. Use em sua aplicação Nuxt
-cd sua-app-nuxt && bun link nuxt-bun-compile
-# 4. Adicione ao array modules no nuxt.config.ts
-bun nuxt add nuxt-bun-compile
-# 5. Compile
-NODE_OPTIONS="--max-old-space-size=8192" bun run -b build
-# 6. Execute o binário
-./nuxtbin
-```
+- [🎯 O que Faz](/docs/WHAT-IT-DOES.ptBR.md)
+- [⚙️ Opções](/docs/OPTIONS.ptBR.md)
+- [📦 Pacotes External Padrão](/docs/DEFAULT-EXTERNAL-PACKAGES.ptBR.md)
+- [⚠️ Dependências Nativas no Alpine Linux](/docs/NATIVE-DEPENDENCIES-IN-ALPINE-LINUX.ptBR.md)
+- [🏗️ Arquitetura](/docs/ARCHITECTURE.ptBR.md)
+- [📚 Exemplos de Uso](/docs/USAGE-EXAMPLES.ptBR.md)
+- [🧑‍💻 Desenvolvimento](/docs/DEVELOPMENT.ptBR.md)
+- [🛠️ Tech Stack](/docs/TECH-STACK.ptBR.md)
+- [📝 Notas](/docs/NOTES.ptBR.md)
 ---
@@ -286,22 +61,6 @@ NODE_OPTIONS="--max-old-space-size=8192" bun run -b build
 ---
-## 📝 Notas
-### Por que `NODE_OPTIONS="--max-old-space-size=8192"`?
-O processo de build do Nuxt com `noExternals: true` e `inlineDynamicImports: true` faz com que o Rollup/esbuild tente empacotar **todas** as dependências em um único bundle. Em projetos com muitas dependências, isso pode consumir mais memória do que o limite padrão do V8 (aproximadamente 1.5–2 GB), causando o erro:
-```
-FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
-```
-A variável `NODE_OPTIONS="--max-old-space-size=8192"` aumenta o limite de memória heap do V8 para 8 GB, dando margem suficiente para que o bundling termine sem estourar a memória. O valor de `8192` (MB) é uma referência segura para a maioria dos projetos — ajuste conforme necessário para projetos maiores ou máquinas com menos RAM.
-> **Nota:** Essa variável afeta o processo do Node.js/V8 que roda o build do Nuxt, e não o binário final gerado pelo `bun build --compile`.
----
 ## 📄 Licença
 MIT

package/dist/module.json CHANGED Viewed

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

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-bun-compile",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "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",