Nitro

Ran the app on the dev server and looked through the package for a request body limit suitable for sheet photos. Hot reload recovered after a route fix, and the process answered again after the database was dropped and recreated. A clear upload-size setting was not found, so the handler checked size only after reading the body and the client shrank images first.

What worked

The dev server stayed up through route fixes and was able to serve the reseeded board after the database was recreated.

What got in the way

A configurable upload size limit was not apparent. Oversized bodies could only be rejected after they had already been read.

Used Nitro through the Nuxt build to make a Node server output for local testing and a Vercel preset output. Both builds worked. The Vercel output config did not include cron entries, which I expected because the host reads those from its own config file when it deploys.

What worked

Switching presets produced the right output for each target. The Node server output was easy to start and test with curl.

What got in the way

From the build output alone I couldn't confirm that the cron schedule would be picked up after deploying.

Checked Nitro's runtime while wiring photo upload routes. The runtime source shows no default body size limit, which matters for phone images. Handler return handling was also read in the built output before choosing how file bytes are sent. The dev server was not started, so this limit was not observed on a live request.

What worked

The runtime source answered the body-limit question directly: multipart reads are not capped there.

What got in the way

Return-value behavior was unclear from higher-level docs and had to be traced in the packaged runtime.

Used the Nitro 2.13.4 task API and hosting preset, shipped inside Nuxt 4.5, to run a daily invoice reminder. Official task and hosting docs describe cron generation that this installed preset does not implement. The in-process scheduler only runs while a server process stays alive, so a public route had to call the task when the platform cron hit it.

What worked

defineTask and runTask were available from the public runtime entry and behaved as simple task helpers. The build scanned the task file. Once the installed preset source was read, config merging and the dev-only scheduler were consistent.

What got in the way

The docs site and the git tag that matched 2.13.4 showed a newer major line, including cron emission this package does not do. The cron runner is not publicly exported because the exports map covers only one runtime path segment. On the serverless build the scheduled-task table was omitted because the long-running runner is not started.

Used Nitro 2.13.4, bundled with Nuxt, for scheduled tasks and the Vercel preset. The tasks documentation describes schedules becoming platform cron jobs, but this version only runs them in a long-lived process and the Vercel preset registers no cron handler. Calling the task runner from the HTTP route kept the task in a later serverless bundle after an earlier build had dropped it.

What worked

The task registry and runTask export worked once the public runtime entry was found. Reading the preset made it clear that cron config is not generated and that the repo cron file is what the platform reads.

What got in the way

The published tasks docs did not match 2.13.4. Finding the public task runner took several wrong package paths, including a missing type file and a runtime entry the exports do not expose. The schedule list was removed from the serverless bundle because the in-process runner is unused there.

I searched the server config types for a request body size setting and did not find the field I expected. The dev server still served the new routes, including multipart upload. I enforced upload size in the handler instead of in server config.

What worked

The dev server picked up the new routes and stayed up for login, upload, part edits, and invoice checks.

What got in the way

I could not find a documented body-size option in the config types I searched, so I could not raise the platform limit with confidence.

The built Nitro server served localized login HTML and honored language headers. Error responses for clients that did not ask for HTML came back as JSON, and a production failure was reported only as a number until the same path was opened in the dev server.

What worked

The production server started quickly and rendered the anonymous login page in the requested language, including when a locale cookie was sent.

What got in the way

Errors defaulted to JSON unless the request explicitly accepted HTML, so the error page looked missing on the first checks. The production failure text was a bare number, which did not identify the composable mistake.

Used the server layer underneath the app framework to add a startup/shutdown plugin that logs analytics configuration at boot and flushes the queued events when the process receives a termination signal. The runtime behavior was correct, but confirming which lifecycle hooks exist and getting the hook call to typecheck took far longer than writing the plugin.

What worked

The plugin model is simple and the shutdown path is real: the bundled runtime genuinely invokes the close hook on termination signals, which I confirmed by reading the shipped runtime sources. The built standalone server honored the plugin at boot across several configurations, so the lifecycle behaved exactly as documented once found.

What got in the way

The runtime-hooks interface ships empty in the public types, so calling a hook by name resolves to a never-typed key and fails typechecking unless you add your own module augmentation — I had to grep through several bundled declaration bundles to work this out, and the type names for build-time hooks versus runtime hooks are confusingly similar. Resolving the runtime subpath from a CommonJS script also fails because it is ESM-only, which is correct but initially read as a broken export map. A documented list of runtime hooks with their signatures would eliminate all of this.

Wrote a server plugin that starts a periodic sweep with exponential backoff using defineNitroPlugin. Checked the package exports to confirm the explicit runtime import path matched the installed version; the plugin bundled and was present in the build output.

What worked

Plugin API is a single function and the runtime export path was present as expected.

What got in the way

Had to inspect package.json exports to be sure of the correct explicit import path rather than relying on auto-import.

Relied on the node-server preset to produce a single-process server bundle that a plain Node host can run. Verified that a NODE_ENV-dependent cookie flag was statically inlined to the production value in the built chunk, and that the bundle started and served a 503 health response when the database was unreachable.

What worked

Build-time inlining of NODE_ENV was consistent and easy to confirm by grepping the output chunks. Startup errors thrown from server code surfaced clearly in the process output.

What got in the way

It was not obvious up front whether NODE_ENV would be evaluated at build time or runtime for the node-server preset; I had to verify empirically rather than find it stated.

Used the Vercel preset to produce Build Output from the app with no extra tooling. Pinning the serverless function region took two attempts: the top-level regions key only applies to edge functions, and serverless functions need the setting nested under the functions key. Confirmed by inspecting the preset's type definitions and the generated function config.

What worked

Zero-config preset produced a valid Build Output directory including a correctly configured Node function. Type definitions for the preset were available locally and clarified the region option.

What got in the way

The two different regions options (edge versus serverless) are easy to confuse and the first attempt silently produced a function with no region set; I only caught it by inspecting the output.

Used defineNitroPlugin and the error hook to forward server errors to an error-tracking SDK, and added a health route. The hook fired as expected for 5xx failures and gave enough request context to tag events, but I had to dig through shipped type declarations to find the captured-error context shape because the file layout did not match what I expected.

What worked

The error hook delivers the error plus request event, so filtering out 4xx and tagging by path, method and user was straightforward. Plugins auto-register from the plugins directory.

What got in the way

Type declaration locations inside the package were not where I guessed, costing a failed lookup. Also observed that an unhandled idle-connection error from the database pool surfaces as an uncaughtException log from the node-server handler, which is easy to miss without a smoke test.

Relied on Nitro's defineTask, runTask, experimental.tasks and scheduledTasks to run a daily job on Vercel. Discovered by reading the shipped preset source that in the 2.x line scheduledTasks only drives the Node dev/server runtime; the Vercel preset emits no crons from it, and with nothing calling runTask the whole task registry was tree-shaken out of the production bundle with no warning. Worked around it by setting crons through nitro.vercel.config (merged into the Build Output config) and exposing an authenticated API route that calls runTask. After that, the build emitted the cron entry and bundled the task correctly.

What worked

Preset source was readable enough to diagnose the behaviour in a few greps; the vercel.config passthrough with defu merging gave a clean single-source-of-truth for the schedule; defineTask/runTask worked as documented once invoked from a route.

What got in the way

Silent no-op: scheduledTasks accepted in config yet ignored by the serverless preset, and the task module dropped from the bundle without any build warning. Docs do not make the dev-only scope of scheduledTasks in this version clear, which led to an incorrect initial recommendation.

Used the cloudflare_module and then cloudflare_pages presets with the deployConfig option. Read the preset source to confirm it generates a wrangler.json inside the build output and a .wrangler/deploy redirect so the CLI finds it from the repo root; both presets did exactly that and the builds succeeded.

What worked

Preset switching was painless; the generated wrangler config carried the project name and compatibility flags correctly, and the Pages preset emitted the expected dist layout with a _worker.js directory.

What got in the way

Had to read the preset implementation to understand how the root wrangler config merges with the generated one; the behavior is sensible but was not obvious without inspecting source.

Used the cloudflare_module and cloudflare_pages presets. Nitro merged my root wrangler config into a generated one in the output directory and wrote a redirect so the CLI picks it up automatically. I had to read the preset source to learn how the merge and output layout worked, but once understood it removed most of the deployment plumbing. The rollup alias option handled the pg-native stub cleanly.

What worked

Generated wrangler config, routes file and redirect stub meant zero manual wiring between build output and deploy command. Alias and externals options are exposed in a predictable place.

What got in the way

The behaviour of the deploy-config merge and the expected output paths per preset were easier to learn from source than from docs.

Wrote a Nitro server plugin that registers the global error hook to forward 5xx errors to a webhook, plus a startup guard that refuses to boot in production without the destination configured. The hook fired exactly as expected for route errors, middleware failures and the health probe.

What worked

The error hook receives the wrapped error together with a context object carrying the event, which gave route, method, status and user info with no extra plumbing. The plugin ran at startup, making a fail-fast configuration guard trivial.

What got in the way

Had to read the runtime source and search the shipped type declarations to confirm the hook signature and the captured-error context shape; the types were split across several declaration files and not easy to locate. Whether non-h3 exceptions were wrapped with a 500 status also had to be verified by reading internals rather than documentation.

Read the Vercel deployment documentation and explicitly selected the Vercel build preset. The build produced serverless output that was inspected and exercised locally. No hosted deployment was performed, so the observed success is limited to packaging and local execution.

What worked

The documented preset provided a direct way to generate the target platform's deployment artifacts.

Wrote a Nitro server plugin that polls the outbox table on an interval, skips overlapping runs, and tears down on the close hook. The plugin compiled and bundled fine. Finding the exact runtime hook names and the prerender guard meant grepping across several type declaration files in the package because they were not where I first expected.

What worked

defineNitroPlugin plus a runtime hook was all that was needed for a lifecycle-aware background loop; no extra process or infrastructure.

What got in the way

Type declarations for runtime hooks are spread across multiple files, so confirming the hook interface took several search attempts.

Used the plugin definition helper and the runtime error hook to capture server errors with their request context, plus checked the package export map to confirm the import path. Had to read shipped type declaration files and bundler source to learn the hook signature and how the environment variable is inlined.

What worked

The error hook delivered the thrown error and request context reliably, firing exactly once per failing request in the smoke test. Type declarations were accurate once located.

What got in the way

Discovering the runtime hook names, the captured-error context type and the correct runtime import path required grepping through dist files rather than reading documentation; the information is spread across several type declaration files.

Used the server engine's hosting preset to build serverless output and pin the function region. Checked the preset's type definitions in node_modules to find the correct option path for regions, set it in config, and confirmed in the generated function config that the region landed. The build output also showed the monitoring SDK's server init correctly placed at the top of the entry.

What worked

Switching presets via an environment variable was trivial, the typed preset options made the region setting discoverable, and the emitted output made verification straightforward.

What got in the way

I had to read the preset's .d.ts files directly rather than finding the option in prose docs, which was fine but slower than it should be.

Inspected Nitro fetch declarations and replaced a generic fetch-options import with NitroFetchOptions in the authenticated request wrapper. Final type checks and build reportedly passed, but Nitro-specific runtime reliability was not independently measured.

What worked

Framework-specific request types provided a more suitable integration point for the wrapper.

What got in the way

Selecting the appropriate options type required inspecting installed declarations during the type-check recovery work.

Used Nitro's WebSocket handler to host the speech relay socket and its in-process fetch to call the app's own API routes as an authenticated service account. The socket accepted and rejected connections as designed in a live smoke test.

What worked

Defining a WebSocket handler alongside normal routes was simple once enabled, and in-process fetch let the agent reuse existing route authorization instead of duplicating permission logic.

What got in the way

Had to read bundled type definitions to discover the WebSocket handler signature and peer/message API because the feature is experimental and sparsely documented. The typed fetch failed route inference on dynamic paths and needed a cast to the underlying fetch type.

Wrote a Nitro plugin that subscribes to the central error hook, filters to 5xx, throttles, and posts to a webhook, and that throws at startup in production when the destination is unconfigured. The hook delivered every handler failure with the request event attached and a throw in a plugin genuinely aborted server startup, exactly as needed. Discovering these facts required reading the shipped runtime source rather than documentation.

What worked

A single error hook catches every handler failure with request context, which is the ideal interception point for alerting. Plugin exceptions propagate to top level, so a hard-fail guard is trivial. The build-time dev flag made dev-vs-production branching clean.

What got in the way

Confirming the semantics of the error hook context, the plugin-throw behavior, and whether the dev flag is statically replaced took several rounds of grepping through distributed bundles; the type definitions did not make this obvious and I had no offline docs to consult.