Skip to content

feat(node,deno,bun): implement env vars, remove srvx-deprecated ones, fix handler docs #4013

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wadefletch wants to merge 3 commits into from
+60 −13
Closed

feat(node,deno,bun): implement env vars, remove srvx-deprecated ones, fix handler docs #4013

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cd7850a
feat: implement NITRO_UNIX_SOCKET and graceful shutdown env vars
wadefletch Feb 9, 2026
4218d87
docs: add env var documentation to bun and deno runtime pages
wadefletch Feb 9, 2026
3482064
docs(node): fix handler preset name and export
wadefletch Feb 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 8 additions & 10 deletions docs/2.deploy/10.runtimes/1.node.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,12 +31,10 @@ You can customize server behavior using following environment variables:

- `NITRO_PORT` or `PORT` (defaults to `3000`)
- `NITRO_HOST` or `HOST`
- `NITRO_UNIX_SOCKET` - if provided (a path to the desired socket file) the service will be served over the provided UNIX socket.
- `NITRO_UNIX_SOCKET` - if provided (a path to the desired socket file) the service will be served over the provided UNIX socket (Node.js and Bun only).
- `NITRO_SSL_CERT` and `NITRO_SSL_KEY` - if both are present, this will launch the server in HTTPS mode. In the vast majority of cases, this should not be used other than for testing, and the Nitro server should be run behind a reverse proxy like nginx or Cloudflare which terminates SSL.
- `NITRO_SHUTDOWN_DISABLED` - Disables the graceful shutdown feature when set to `'true'`. If it's set to `'true'`, the graceful shutdown is bypassed to speed up the development process. Defaults to `'false'`.
- `NITRO_SHUTDOWN_SIGNALS` - Allows you to specify which signals should be handled. Each signal should be separated with a space. Defaults to `'SIGINT SIGTERM'`.
- `NITRO_SHUTDOWN_TIMEOUT` - Sets the amount of time (in milliseconds) before a forced shutdown occurs. Defaults to `'30000'` milliseconds.
- `NITRO_SHUTDOWN_FORCE` - When set to true, it triggers `process.exit()` at the end of the shutdown process. If it's set to `'false'`, the process will simply let the event loop clear. Defaults to `'true'`.
- `NITRO_SHUTDOWN_DISABLED` - Disables the graceful shutdown feature when set to `'true'`. Defaults to `'false'`.
- `NITRO_SHUTDOWN_TIMEOUT` - Sets the amount of time (in milliseconds) before a forced shutdown occurs. Defaults to `5000` milliseconds.

## Cluster mode

Expand All @@ -52,18 +50,18 @@ In addition to environment variables from the `node_server` preset, you can cust

## Handler (advanced)

**Preset:** `node`
**Preset:** `node_middleware`

Nitro also has a more low-level preset that directly exports a function with `(req, res) => {}` signature usable for middleware and custom servers.
Nitro also has a more low-level preset that directly exports a Node.js compatible handler usable for middleware and custom servers.
Copy link

@coderabbitai coderabbitai bot Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Hyphenate “Node.js‑compatible”.

Grammar nit: “Node.js compatible” should be “Node.js‑compatible”.

🧰 Tools
🪛 LanguageTool

[grammar] ~57-~57: Use a hyphen to join words.
Context: ...l preset that directly exports a Node.js compatible handler usable for middleware...

(QB_NEW_EN_HYPHEN)

🤖 Prompt for AI Agents 
In `@docs/2.deploy/10.runtimes/1.node.md` at line 57, Replace the unhyphenated
phrase "Node.js compatible handler" with "Node.js-compatible handler" in the
sentence that reads "Nitro also has a more low-level preset that directly
exports a Node.js compatible handler usable for middleware and custom servers."
to apply the correct hyphenation for the compound modifier; update the string
exactly where that text appears in the docs.


When running `nitro build` with the Node preset, the result will be an entry point exporting a function with the `(req, res) => {}` signature.
When running `nitro build` with the Node middleware preset, the result will be an entry point exporting a `middleware` handler.

**Example:**

```js
import { createServer } from 'node:http'
import { listener } from './.output/server'
import { middleware } from './.output/server'

const server = createServer(listener)
const server = createServer(middleware)
server.listen(8080)
```
11 changes: 11 additions & 0 deletions docs/2.deploy/10.runtimes/bun.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,3 +17,14 @@ bun run ./.output/server/index.mjs
```

:read-more{to="https://bun.sh"}

### Environment Variables
Copy link

@coderabbitai coderabbitai bot Feb 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Same h1 → h3 heading level skip as in deno.md.

Same markdownlint MD001 concern. Consistent with the project pattern but worth addressing if the project decides to fix heading levels.

🤖 Prompt for AI Agents 
In `@docs/2.deploy/10.runtimes/bun.md` at line 21, The document has a
heading-level skip (h1 to h3) at the "Environment Variables" section similar to
deno.md which triggers markdownlint MD001; update the heading hierarchy so
levels are consecutive (e.g., change the "Environment Variables" heading to h2
or adjust surrounding headings) to eliminate the h1→h3 jump and keep consistency
with the project style and deno.md; ensure the change only alters the markdown
heading markers (e.g., from ### to ##) in the docs/2.deploy/10.runtimes/bun.md
file.


You can customize server behavior using following environment variables:

- `NITRO_PORT` or `PORT` (defaults to `3000`)
- `NITRO_HOST` or `HOST`
- `NITRO_UNIX_SOCKET` - if provided (a path to the desired socket file) the service will be served over the provided UNIX socket.
- `NITRO_SSL_CERT` and `NITRO_SSL_KEY` - if both are present, this will launch the server in HTTPS mode. In the vast majority of cases, this should not be used other than for testing, and the Nitro server should be run behind a reverse proxy like nginx or Cloudflare which terminates SSL.
- `NITRO_SHUTDOWN_DISABLED` - Disables the graceful shutdown feature when set to `'true'`. Defaults to `'false'`.
- `NITRO_SHUTDOWN_TIMEOUT` - Sets the amount of time (in milliseconds) before a forced shutdown occurs. Defaults to `3000` milliseconds.
Comment on lines +29 to +30
Copy link

@coderabbitai coderabbitai bot Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Inconsistent default for NITRO_SHUTDOWN_TIMEOUT across runtime docs.

This says the default is 3000 milliseconds, but the Node.js docs (line 37 of 1.node.md) document it as 5000 milliseconds. Per the PR objectives and srvx's default gracefulTimeout of 5 seconds, the correct value should be 5000.

Proposed fix 
-- `NITRO_SHUTDOWN_TIMEOUT` - Sets the amount of time (in milliseconds) before a forced shutdown occurs. Defaults to `3000` milliseconds.
+- `NITRO_SHUTDOWN_TIMEOUT` - Sets the amount of time (in milliseconds) before a forced shutdown occurs. Defaults to `5000` milliseconds.
🤖 Prompt for AI Agents 
In `@docs/2.deploy/10.runtimes/bun.md` around lines 29 - 30, Update the docs entry
for the environment variable NITRO_SHUTDOWN_TIMEOUT in the Bun runtime docs to
use the correct default of 5000 milliseconds (to match Node.js docs and srvx's
gracefulTimeout), i.e., change the documented default from `3000` to `5000` and
ensure the description remains consistent with the existing
NITRO_SHUTDOWN_DISABLED line and the Node.js `NITRO_SHUTDOWN_TIMEOUT`
documentation.

10 changes: 10 additions & 0 deletions docs/2.deploy/10.runtimes/deno.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,16 @@ NITRO_PRESET=deno_server npm run build
deno run --unstable --allow-net --allow-read --allow-env .output/server/index.ts
```

### Environment Variables
Copy link

@coderabbitai coderabbitai bot Feb 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Heading level skips from h1 to h3.

Static analysis (markdownlint MD001) flags this as jumping from # to ###. However, this is consistent with the existing pattern in 1.node.md (Line 28), so this may be intentional for the project. Consider aligning with the project's heading conventions.

🧰 Tools
🪛 markdownlint-cli2 (0.20.0)

[warning] 21-21: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3

(MD001, heading-increment)

🤖 Prompt for AI Agents 
In `@docs/2.deploy/10.runtimes/deno.md` at line 21, The "Environment Variables"
heading currently uses an h3 (###) which jumps from h1 to h3; change it to h2
(##) so heading levels don't skip, or alternatively change surrounding headings
in this doc to match the project's existing convention (as seen in "1.node.md")
so all runtime docs use consistent heading levels; update the "Environment
Variables" heading text accordingly and verify the rest of this markdown follows
the same h-level pattern.


You can customize server behavior using following environment variables:

- `NITRO_PORT` or `PORT` (defaults to `3000`)
- `NITRO_HOST` or `HOST`
- `NITRO_SSL_CERT` and `NITRO_SSL_KEY` - if both are present, this will launch the server in HTTPS mode. In the vast majority of cases, this should not be used other than for testing, and the Nitro server should be run behind a reverse proxy like nginx or Cloudflare which terminates SSL.
- `NITRO_SHUTDOWN_DISABLED` - Disables the graceful shutdown feature when set to `'true'`. Defaults to `'false'`.
- `NITRO_SHUTDOWN_TIMEOUT` - Sets the amount of time (in milliseconds) before a forced shutdown occurs. Defaults to `3000` milliseconds.
Comment on lines +28 to +29
Copy link

@coderabbitai coderabbitai bot Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Same inconsistent NITRO_SHUTDOWN_TIMEOUT default as in bun.md.

Should be 5000 milliseconds to match the Node.js docs and srvx's default gracefulTimeout of 5 seconds.

Proposed fix 
-- `NITRO_SHUTDOWN_TIMEOUT` - Sets the amount of time (in milliseconds) before a forced shutdown occurs. Defaults to `3000` milliseconds.
+- `NITRO_SHUTDOWN_TIMEOUT` - Sets the amount of time (in milliseconds) before a forced shutdown occurs. Defaults to `5000` milliseconds.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
- `NITRO_SHUTDOWN_DISABLED` - Disables the graceful shutdown feature when set to `'true'`. Defaults to `'false'`.
- `NITRO_SHUTDOWN_TIMEOUT` - Sets the amount of time (in milliseconds) before a forced shutdown occurs. Defaults to `3000` milliseconds.
- `NITRO_SHUTDOWN_DISABLED` - Disables the graceful shutdown feature when set to `'true'`. Defaults to `'false'`.
- `NITRO_SHUTDOWN_TIMEOUT` - Sets the amount of time (in milliseconds) before a forced shutdown occurs. Defaults to `5000` milliseconds.
🤖 Prompt for AI Agents 
In `@docs/2.deploy/10.runtimes/deno.md` around lines 28 - 29, Update the
NITRO_SHUTDOWN_TIMEOUT default in docs/2.deploy/10.runtimes/deno.md from 3000 to
5000 to match the Node.js docs and srvx's default gracefulTimeout (5 seconds);
specifically change the `NITRO_SHUTDOWN_TIMEOUT` line so it states the default
is `5000` milliseconds (and verify the `NITRO_SHUTDOWN_DISABLED` line remains
unchanged) to keep defaults consistent with bun.md and Node.js documentation.


## Deno Deploy

:read-more{to="/deploy/providers/deno-deploy"}
12 changes: 11 additions & 1 deletion src/presets/bun/runtime/bun.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,15 @@ const port = Number.isNaN(_parsedPort) ? 3000 : _parsedPort;
const host = process.env.NITRO_HOST || process.env.HOST;
const cert = process.env.NITRO_SSL_CERT;
const key = process.env.NITRO_SSL_KEY;
// const socketPath = process.env.NITRO_UNIX_SOCKET; // TODO
const socketPath = process.env.NITRO_UNIX_SOCKET;

const _shutdownTimeout = Number.parseInt(process.env.NITRO_SHUTDOWN_TIMEOUT || "", 10);
const gracefulShutdown =
process.env.NITRO_SHUTDOWN_DISABLED === "true"
? false
: _shutdownTimeout > 0
? { gracefulTimeout: _shutdownTimeout / 1000 }
: undefined;

const nitroApp = useNitroApp();

Expand All @@ -35,7 +43,9 @@ serve({
hostname: host,
tls: cert && key ? { cert, key } : undefined,
fetch: _fetch,
gracefulShutdown,
bun: {
unix: socketPath,
websocket: import.meta._websocket ? ws?.websocket : undefined,
},
});
Expand Down
10 changes: 9 additions & 1 deletion src/presets/deno/runtime/deno-server.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,14 @@ const port = Number.isNaN(_parsedPort) ? 3000 : _parsedPort;
const host = process.env.NITRO_HOST || process.env.HOST;
const cert = process.env.NITRO_SSL_CERT;
const key = process.env.NITRO_SSL_KEY;
// const socketPath = process.env.NITRO_UNIX_SOCKET; // TODO

const _shutdownTimeout = Number.parseInt(process.env.NITRO_SHUTDOWN_TIMEOUT || "", 10);
const gracefulShutdown =
process.env.NITRO_SHUTDOWN_DISABLED === "true"
? false
: _shutdownTimeout > 0
? { gracefulTimeout: _shutdownTimeout / 1000 }
: undefined;

const nitroApp = useNitroApp();

Expand All @@ -35,6 +42,7 @@ serve({
hostname: host,
tls: cert && key ? { cert, key } : undefined,
fetch: _fetch,
gracefulShutdown,
});

trapUnhandledErrors();
Expand Down
12 changes: 11 additions & 1 deletion src/presets/node/runtime/node-server.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,15 @@ const port = Number.isNaN(_parsedPort) ? 3000 : _parsedPort;
const host = process.env.NITRO_HOST || process.env.HOST;
const cert = process.env.NITRO_SSL_CERT;
const key = process.env.NITRO_SSL_KEY;
// const socketPath = process.env.NITRO_UNIX_SOCKET; // TODO
const socketPath = process.env.NITRO_UNIX_SOCKET;

const _shutdownTimeout = Number.parseInt(process.env.NITRO_SHUTDOWN_TIMEOUT || "", 10);
const gracefulShutdown =
process.env.NITRO_SHUTDOWN_DISABLED === "true"
? false
: _shutdownTimeout > 0
? { gracefulTimeout: _shutdownTimeout / 1000 }
: undefined;

const nitroApp = useNitroApp();

Expand All @@ -22,6 +30,8 @@ const server = serve({
hostname: host,
tls: cert && key ? { cert, key } : undefined,
fetch: nitroApp.fetch,
gracefulShutdown,
node: socketPath ? { path: socketPath } : undefined,
});

if (import.meta._websocket) {
Expand Down
Loading