nuxt-bun-compile 0.1.15 → 0.1.18

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
  1. package/README.md +27 -81
  2. package/README.ptBR.md +59 -113
  3. package/dist/module.json +1 -1
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -10,64 +10,36 @@
10
10
 
11
11
  ---
12
12
 
13
- > **⚠️ IMPORTANT: Use `bun run -b build` to generate the binary**
14
- >
15
- > The following commands **DO NOT** trigger binary compilation:
16
- > ```bash
17
- > bun run build # ❌ does not generate the binary
18
- > npm run build # ❌ does not generate the binary
19
- > pnpm run build # ❌ does not generate the binary
20
- > ```
21
- >
22
- > The correct command is:
23
- > ```bash
24
- > bun run -b build # ✅ generates the binary (nuxtbin or the name set in outfile)
25
- > ```
26
- >
27
- > [Why is `-b` required?](https://github.com/jprando/nuxt-bun-compile?tab=readme-ov-file#why-is--b-required)
28
-
29
- ---
30
-
31
13
  ## ⚡ Quick Start
32
14
 
33
- ```bash
34
- # Install directly from GitHub
35
- bun add -D github:jprando/nuxt-bun-compile
36
-
37
- # Or link locally for development
38
- git clone https://github.com/jprando/nuxt-bun-compile.git
39
- cd nuxt-bun-compile && bun install && bun link
40
- cd your-nuxt-app && bun link nuxt-bun-compile && bun nuxt nuxt-bun-compile
41
- ```
15
+ Add the module to any Nuxt project in two steps:
42
16
 
43
- Add to your `nuxt.config.ts`:
17
+ **Step 1: Install the module**
44
18
 
45
- ```ts
46
- export default defineNuxtConfig({
47
- modules: ["nuxt-bun-compile"],
48
- bunCompile: {
49
- outfile: "myapp",
50
- },
51
- })
19
+ ```bash
20
+ bun nuxt add nuxt-bun-compile
52
21
  ```
53
22
 
54
- Build and run:
23
+ **Step 2: Build your binary**
55
24
 
56
25
  ```bash
57
- NODE_OPTIONS="--max-old-space-size=8192" bun run -b build
58
- ./myapp
26
+ bun run -b build
59
27
  ```
60
28
 
61
- That's it. One binary. No `node_modules`. No runtime. Just your app.
29
+ [Why is `-b` required?](https://github.com/jprando/nuxt-bun-compile?tab=readme-ov-file#why-is--b-required)
62
30
 
63
- ---
31
+ [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)
64
32
 
65
- ## 🌟 Example
33
+ **Step 3: Run your binary**
66
34
 
67
- Check out a real project using this module:
35
+ ```bash
36
+ ./nuxtbin
37
+ # Listening on http://localhost:3000
38
+ ```
68
39
 
69
- - **Repository:** [nuxt-duckdb-wasm](https://github.com/jprando/nuxt-duckdb-wasm)
70
- - **Demo:** [https://nuxt-duckdb-wasm.jeudi.workers.dev/](https://nuxt-duckdb-wasm.jeudi.workers.dev/)
40
+ Done! Your standalone binary is ready.
41
+
42
+ That's it. One binary. No `node_modules`. No runtime. Just your app.
71
43
 
72
44
  ---
73
45
 
@@ -130,14 +102,6 @@ bunCompile: {
130
102
 
131
103
  ## 🏗️ Architecture
132
104
 
133
- ```
134
- src/
135
- module.ts # Main module — configures Nitro + auto-compiles
136
- package.json
137
- tsconfig.json
138
- dprint.json # Code formatter config
139
- ```
140
-
141
105
  The module uses a **hook-based architecture**:
142
106
 
143
107
  - **`nitro:config`** — Adjusts Nitro settings (preset, externals, bundling)
@@ -177,7 +141,7 @@ The **`-b`** (or `--bun`) flag forces Bun to be the runtime that executes the sc
177
141
  |---|---|---|
178
142
  | 🔤 | **TypeScript** | ESNext target, strict mode, bundler resolution |
179
143
  | 🐰 | **Bun** | Runtime 1.3.9+, package manager |
180
- | 💚 | **Nuxt** | 3.x / 4.x via `@nuxt/kit` + `@nuxt/schema` |
144
+ | 💚 | **Nuxt** | 4.x |
181
145
  | 📐 | **dprint** | Code formatter (TS, JSON, MD, TOML, YAML, and more) |
182
146
  | 📦 | **ESM** | Pure ES modules (`"type": "module"`) |
183
147
 
@@ -185,43 +149,25 @@ The **`-b`** (or `--bun`) flag forces Bun to be the runtime that executes the sc
185
149
 
186
150
  ## 🧑‍💻 Development
187
151
 
188
- ### Commands
189
-
190
- ```bash
191
- # Install dependencies
192
- bun install
193
-
194
- # Format code
195
- bun run format
196
-
197
- # Link for local testing
198
- bun link
199
- ```
200
-
201
- ### Code Style
202
-
203
- - **Formatter:** dprint — always run `bun run format` before committing
204
- - **Strings:** Double quotes
205
- - **Semicolons:** Yes
206
- - **Constants:** `UPPER_SNAKE_CASE` for module-level (`DEFAULT_EXTERNALS`)
207
- - **Types:** `interface` for public APIs, `import type` for type-only imports
208
- - **Node built-ins:** Use `node:` prefix (e.g. `node:child_process`)
209
-
210
152
  ### Testing Locally in a Nuxt App
211
153
 
212
154
  ```bash
213
- # 1. Link the module
214
- cd nuxt-bun-compile && bun link
155
+ # 1. Clone this repo for local development
156
+ git clone https://github.com/jprando/nuxt-bun-compile.git
157
+
158
+ # 2. Link the module
159
+ cd nuxt-bun-compile && bun install && bun prepack && bun link
215
160
 
216
- # 2. Use it in your Nuxt app
161
+ # 3. Use it in your Nuxt app
217
162
  cd your-nuxt-app && bun link nuxt-bun-compile
218
163
 
219
- # 3. Add to nuxt.config.ts modules array
164
+ # 4. Add to nuxt.config.ts modules array
165
+ bun nuxt add nuxt-bun-compile
220
166
 
221
- # 4. Build
167
+ # 5. Build
222
168
  NODE_OPTIONS="--max-old-space-size=8192" bun run -b build
223
169
 
224
- # 5. Run the binary
170
+ # 6. Run the binary
225
171
  ./nuxtbin
226
172
  ```
227
173
 
package/README.ptBR.md CHANGED
@@ -4,108 +4,80 @@
4
4
 
5
5
  ![Logo Nuxt Bun Compile](/images/logo-transparent--nuxt-bun-compile.png "Logo Nuxt Bun Compile")
6
6
 
7
- > 🚀 Modulo Nuxt que configura automaticamente o Nitro para `bun build --compile`, gerando um **binario executavel standalone** a partir da sua aplicacao Nuxt — sem dependencias de runtime.
7
+ > 🚀 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.
8
8
 
9
9
  [Read in English](README.md)
10
10
 
11
11
  ---
12
12
 
13
- > **⚠️ IMPORTANTE: Use `bun run -b build` para gerar o binario**
14
- >
15
- > Os comandos abaixo **NAO** acionam a compilacao do binario:
16
- > ```bash
17
- > bun run build # ❌ nao gera o binario
18
- > npm run build # ❌ nao gera o binario
19
- > pnpm run build # ❌ nao gera o binario
20
- > ```
21
- >
22
- > O comando correto eh:
23
- > ```bash
24
- > bun run -b build # ✅ gera o binario (nuxtbin ou o nome definido em outfile)
25
- > ```
26
- >
27
- > [Por que é necessário o parâmetro `-b`?](https://github.com/jprando/nuxt-bun-compile/blob/main/README.ptBR.md#por-que-o--b-eh-obrigatorio)
13
+ ## ⚡ Início Rápido
28
14
 
29
- ---
15
+ Adicione o módulo a qualquer projeto Nuxt em dois passos:
30
16
 
31
- ## ⚡ Inicio Rapido
17
+ **Passo 1: Instalar o módulo**
32
18
 
33
19
  ```bash
34
- # Instalar diretamente do GitHub
35
- bun add -D github:jprando/nuxt-bun-compile
36
-
37
- # Ou linkar localmente para desenvolvimento
38
- git clone https://github.com/jprando/nuxt-bun-compile.git
39
- cd nuxt-bun-compile && bun install && bun link
40
- cd sua-app-nuxt && bun link nuxt-bun-compile && bun nuxt nuxt-bun-compile
41
- ```
42
-
43
- Adicione ao seu `nuxt.config.ts`:
44
-
45
- ```ts
46
- export default defineNuxtConfig({
47
- modules: ["nuxt-bun-compile"],
48
- bunCompile: {
49
- outfile: "myapp",
50
- },
51
- })
20
+ bun nuxt add nuxt-bun-compile
52
21
  ```
53
22
 
54
- Build e execucao:
23
+ **Passo 2: Compilar seu binário**
55
24
 
56
25
  ```bash
57
- NODE_OPTIONS="--max-old-space-size=8192" bun run -b build
58
- ./myapp
26
+ bun run -b build
59
27
  ```
60
28
 
61
- So isso. Um binario. Sem `node_modules`. Sem runtime. Apenas sua aplicacao.
29
+ [Por que é necessário o parâmetro `-b`?](https://github.com/jprando/nuxt-bun-compile?tab=readme-ov-file#por-que--b-eh-obrigatorio)
62
30
 
63
- ---
31
+ [Se você enfrentar problemas de memória durante a compilação](https://github.com/jprando/nuxt-bun-compile?tab=readme-ov-file#por-que-node_options---max-old-space-size8192)
64
32
 
65
- ## 🌟 Exemplo
33
+ **Passo 3: Executar seu binário**
66
34
 
67
- Veja um projeto real utilizando este modulo:
35
+ ```bash
36
+ ./nuxtbin
37
+ # Listening on http://localhost:3000
38
+ ```
68
39
 
69
- - **Repositorio:** [nuxt-duckdb-wasm](https://github.com/jprando/nuxt-duckdb-wasm)
70
- - **Demo:** [https://nuxt-duckdb-wasm.jeudi.workers.dev/](https://nuxt-duckdb-wasm.jeudi.workers.dev/)
40
+ Pronto! Seu binário standalone está pronto.
41
+
42
+ Só um binário. Sem `node_modules`. Sem runtime. Apenas sua aplicação.
71
43
 
72
44
  ---
73
45
 
74
- ## 🎯 O que faz
46
+ ## 🎯 O que Faz
75
47
 
76
- O modulo se conecta ao pipeline de build do Nuxt e cuida de **tudo** automaticamente:
48
+ O módulo se conecta ao pipeline de build do Nuxt e cuida de **tudo** automaticamente:
77
49
 
78
- 1. **Configura o Nitro** com as configuracoes otimas para compilacao em binario
79
- 2. **Externaliza pacotes problematicos** que quebram com bundling completo
80
- 3. **Executa `bun build --compile`** apos o build para produzir um executavel standalone
50
+ 1. **Configura o Nitro** com as configurações ótimas para compilação em binário
51
+ 2. **Externaliza pacotes problemáticos** que quebram com bundling completo
52
+ 3. **Executa `bun build --compile`** após o build para produzir um executável standalone
81
53
 
82
- ### Configuracao do Nitro (aplicada automaticamente)
54
+ ### Configuração do Nitro (aplicada automaticamente)
83
55
 
84
- | Configuracao | Valor | Motivo |
56
+ | Configuração | Valor | Motivo |
85
57
  |---|---|---|
86
58
  | `preset` | `"bun"` | Usar o runtime Bun como alvo |
87
59
  | `noExternals` | `true` | Empacotar tudo no output |
88
- | `inlineDynamicImports` | `true` | Achatar imports dinamicos para output em arquivo unico |
89
- | `serveStatic` | `"inline"` | Embutir assets estaticos no binario |
90
- | `esbuild.options.target` | `"esnext"` | Usar as features JS mais recentes para maximo desempenho |
60
+ | `inlineDynamicImports` | `true` | Achatar imports dinâmicos para output em arquivo único |
61
+ | `serveStatic` | `"inline"` | Embutir assets estáticos no binário |
62
+ | `esbuild.options.target` | `"esnext"` | Usar as features JS mais recentes para máximo desempenho |
91
63
 
92
64
  ---
93
65
 
94
- ## ⚙️ Opcoes
66
+ ## ⚙️ Opções
95
67
 
96
- | Opcao | Tipo | Padrao | Descricao |
68
+ | Opção | Tipo | Padrão | Descrição |
97
69
  |---|---|---|---|
98
- | `enabled` | `boolean` | `true` | Habilitar/desabilitar o modulo |
99
- | `outfile` | `string` | `"nuxtbin"` | Nome do arquivo binario de saida |
70
+ | `enabled` | `boolean` | `true` | Habilitar/desabilitar o módulo |
71
+ | `outfile` | `string` | `"nuxtbin"` | Nome do arquivo binário de saída |
100
72
  | `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. |
101
73
  | `extraExternals` | `(string \| RegExp)[]` | `[]` | Pacotes adicionais para marcar como external |
102
- | `autoCompile` | `boolean` | `true` | Executar `bun build --compile` automaticamente apos o build |
74
+ | `autoCompile` | `boolean` | `true` | Executar `bun build --compile` automaticamente após o build |
103
75
 
104
76
  ---
105
77
 
106
- ## 📦 Pacotes External Padrao
78
+ ## 📦 Pacotes External Padrão
107
79
 
108
- Estes pacotes sao conhecidos por quebrar com `noExternals: true` e sao excluidos por padrao:
80
+ Estes pacotes são conhecidos por quebrar com `noExternals: true` e são excluídos por padrão:
109
81
 
110
82
  | Pacote | Pattern |
111
83
  |---|---|
@@ -124,24 +96,16 @@ bunCompile: {
124
96
  }
125
97
  ```
126
98
 
127
- > **⚠️ Importante:** As bibliotecas listadas em `extraExternals` (assim como as externals padrao) **nao sao embutidas no binario**. Para que o binario `nuxtbin` execute corretamente, essas dependencias precisam estar disponiveis em uma pasta `node_modules` ao lado do binario gerado.
99
+ > **⚠️ 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.
128
100
 
129
101
  ---
130
102
 
131
103
  ## 🏗️ Arquitetura
132
104
 
133
- ```
134
- src/
135
- module.ts # Modulo principal — configura o Nitro + auto-compila
136
- package.json
137
- tsconfig.json
138
- dprint.json # Configuracao do formatador de codigo
139
- ```
140
-
141
- O modulo usa uma **arquitetura baseada em hooks**:
105
+ O módulo usa uma **arquitetura baseada em hooks**:
142
106
 
143
- - **`nitro:config`** — Ajusta configuracoes do Nitro (preset, externals, bundling)
144
- - **`nitro:compiled`** — Aciona `bun build --compile` apos o Nitro terminar o build do servidor
107
+ - **`nitro:config`** — Ajusta configurações do Nitro (preset, externals, bundling)
108
+ - **`nitro:compiled`** — Aciona `bun build --compile` após o Nitro terminar o build do servidor
145
109
 
146
110
  ### Como Funciona
147
111
 
@@ -154,12 +118,12 @@ bun run -b build
154
118
  │
155
119
  └─ hook nitro compiled ──▶ bun build .output/server/index.mjs --compile --outfile <nome>
156
120
  │
157
- └──▶ 🎉 Binario standalone pronto!
121
+ └──▶ 🎉 Binário standalone pronto!
158
122
  ```
159
123
 
160
- ### Por que o `-b` eh obrigatorio?
124
+ ### Por que `-b` é obrigatório?
161
125
 
162
- Quando voce executa `bun run build` (sem `-b`), o Bun age como um **gerenciador de tarefas** e pode delegar a execucao do script ao Node.js. Nesse cenario, as variaveis `globalThis.Bun` e `process.versions.bun` **nao existem**, e o modulo nao consegue detectar o runtime Bun:
126
+ 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:
163
127
 
164
128
  ```ts
165
129
  const isBun = typeof globalThis.Bun !== "undefined"
@@ -167,7 +131,7 @@ const isBun = typeof globalThis.Bun !== "undefined"
167
131
  ```
168
132
  [src/module.ts:L70-L76](https://github.com/jprando/nuxt-bun-compile/blob/main/src/module.ts#L70-L76)
169
133
 
170
- O parametro **`-b`** (ou `--bun`) forca o Bun a ser o runtime que executa o script. Com ele, as variaveis acima ficam disponiveis e a etapa de `bun build --compile` eh executada corretamente.
134
+ 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.
171
135
 
172
136
  ---
173
137
 
@@ -177,51 +141,33 @@ O parametro **`-b`** (ou `--bun`) forca o Bun a ser o runtime que executa o scri
177
141
  |---|---|---|
178
142
  | 🔤 | **TypeScript** | Target ESNext, strict mode, bundler resolution |
179
143
  | 🐰 | **Bun** | Runtime 1.3.9+, gerenciador de pacotes |
180
- | 💚 | **Nuxt** | 3.x / 4.x via `@nuxt/kit` + `@nuxt/schema` |
181
- | 📐 | **dprint** | Formatador de codigo (TS, JSON, MD, TOML, YAML e mais) |
144
+ | 💚 | **Nuxt** | 4.x |
145
+ | 📐 | **dprint** | Formatador de código (TS, JSON, MD, TOML, YAML e mais) |
182
146
  | 📦 | **ESM** | ES modules puro (`"type": "module"`) |
183
147
 
184
148
  ---
185
149
 
186
150
  ## 🧑‍💻 Desenvolvimento
187
151
 
188
- ### Comandos
152
+ ### Testando Localmente em uma Aplicação Nuxt
189
153
 
190
154
  ```bash
191
- # Instalar dependencias
192
- bun install
193
-
194
- # Formatar codigo
195
- bun run format
196
-
197
- # Linkar para testes locais
198
- bun link
199
- ```
200
-
201
- ### Estilo de Codigo
202
-
203
- - **Formatador:** dprint — sempre execute `bun run format` antes de commitar
204
- - **Strings:** Aspas duplas
205
- - **Ponto e virgula:** Sim
206
- - **Constantes:** `UPPER_SNAKE_CASE` para nivel de modulo (`DEFAULT_EXTERNALS`)
207
- - **Tipos:** `interface` para APIs publicas, `import type` para imports somente de tipo
208
- - **Built-ins do Node:** Use prefixo `node:` (ex: `node:child_process`)
209
-
210
- ### Testando Localmente em uma App Nuxt
155
+ # 1. Clone este repositório para desenvolvimento local
156
+ git clone https://github.com/jprando/nuxt-bun-compile.git
211
157
 
212
- ```bash
213
- # 1. Linkar o modulo
214
- cd nuxt-bun-compile && bun link
158
+ # 2. Linke o módulo
159
+ cd nuxt-bun-compile && bun install && bun prepack && bun link
215
160
 
216
- # 2. Usar na sua app Nuxt
161
+ # 3. Use em sua aplicação Nuxt
217
162
  cd sua-app-nuxt && bun link nuxt-bun-compile
218
163
 
219
- # 3. Adicionar ao array modules no nuxt.config.ts
164
+ # 4. Adicione ao array modules no nuxt.config.ts
165
+ bun nuxt add nuxt-bun-compile
220
166
 
221
- # 4. Build
167
+ # 5. Compile
222
168
  NODE_OPTIONS="--max-old-space-size=8192" bun run -b build
223
169
 
224
- # 5. Executar o binario
170
+ # 6. Execute o binário
225
171
  ./nuxtbin
226
172
  ```
227
173
 
@@ -231,7 +177,7 @@ NODE_OPTIONS="--max-old-space-size=8192" bun run -b build
231
177
 
232
178
  - [Bun](https://bun.sh) 1.3.9+ (para a etapa de `--compile`)
233
179
  - Nuxt 3.x / 4.x
234
- - Node 24+ (quando nao usar Bun como runtime)
180
+ - Node 24+ (quando não usar Bun como runtime)
235
181
 
236
182
  ---
237
183
 
@@ -239,18 +185,18 @@ NODE_OPTIONS="--max-old-space-size=8192" bun run -b build
239
185
 
240
186
  ### Por que `NODE_OPTIONS="--max-old-space-size=8192"`?
241
187
 
242
- O processo de build do Nuxt com `noExternals: true` e `inlineDynamicImports: true` faz com que o Rollup/esbuild tente empacotar **todas** as dependencias em um unico bundle. Em projetos com muitas dependencias, isso pode consumir mais memoria do que o limite padrao do V8 (aproximadamente 1.5–2 GB), causando o erro:
188
+ 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:
243
189
 
244
190
  ```
245
191
  FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
246
192
  ```
247
193
 
248
- A variavel `NODE_OPTIONS="--max-old-space-size=8192"` aumenta o limite de memoria heap do V8 para 8 GB, dando margem suficiente para que o bundling termine sem estourar a memoria. O valor de `8192` (MB) eh uma referencia segura para a maioria dos projetos — ajuste conforme necessario para projetos maiores ou maquinas com menos RAM.
194
+ 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.
249
195
 
250
- > **Nota:** Essa variavel afeta o processo do Node.js/V8 que roda o build do Nuxt, e nao o binario final gerado pelo `bun build --compile`.
196
+ > **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`.
251
197
 
252
198
  ---
253
199
 
254
- ## 📄 Licenca
200
+ ## 📄 Licença
255
201
 
256
202
  MIT
package/dist/module.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "nuxt-bun-compile",
3
3
  "configKey": "bunCompile",
4
- "version": "0.1.15",
4
+ "version": "0.1.18",
5
5
  "builder": {
6
6
  "@nuxt/module-builder": "1.0.2",
7
7
  "unbuild": "3.6.1"
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nuxt-bun-compile",
3
- "version": "0.1.15",
3
+ "version": "0.1.18",
4
4
  "description": "Nuxt module that automatically configures Nitro for `bun build --compile`, generating a standalone executable binary from your Nuxt app.",
5
5
  "repository": "jprando/nuxt-bun-compile",
6
6
  "license": "MIT",