In this tutorial, we will add explicit tracing to a Nuxt 3 API running under Nitro's Node server preset. We will preload the OpenTelemetry SDK, create a server span and a lookup span, and export them over OTLP/HTTP. A local receiver will verify the actual payload, including an incoming parent context, concurrent requests, errors, and the final shutdown flush.

The sample is a standalone Cloudmerce example with synthetic catalog data. It requires no hosted observability account. SigNoz and Jaeger are possible destinations later, but this exercise does not deploy either backend or claim to have verified a vendor dashboard.

Run the verified project

The project is a small Nuxt 3 app (nuxt-otel) built from the files shown in this tutorial. From its root directory:

npm ci
npm run build
npm run check

The verified environment used Node 22.23.3, Nuxt 3.21.11, Nitro 2.13.5, OpenTelemetry API 1.9.0, SDK Node 0.208.0, and the matching 0.208.0 OTLP HTTP exporter. Resources are supplied by @opentelemetry/resources 2.2.0. OpenTelemetry package families do not all share one version number; use the included lockfile to reproduce this combination.

The sample's check starts a loopback receiver on a free port and the built Nuxt server on port 3100. It sends requests, stops the server gracefully, and checks the exported data. Keep that application port free while running it.

Our instrumentation covers /api/catalog explicitly. It does not automatically trace every Nuxt route, browser navigation, or dependency. Starting with one route makes it possible to verify context and export behavior before introducing wider instrumentation.

Keep this application on Node

The relevant Nitro configuration is:

nitro: {
  preset: 'node-server',
  externals: { external: ['@opentelemetry/api'] }
}

This sample uses the Node SDK and its asynchronous context management. It is a separate deployment target from a Cloudflare Worker. Do not assume that changing the Nitro preset preserves the same SDK initialization and process lifecycle.

The API package is used by application code to request tracers and create spans. The SDK configures the provider that records and exports those spans. Without an initialized provider, application calls can succeed while producing no useful telemetry.

We initialize the SDK outside the Nitro bundle and before loading the built server. That also leaves a clear place to add Node library instrumentation later. If you introduce automatic instrumentation, review its loading requirements and verify that the libraries it patches are loaded after initialization.

Preload the SDK before the application

Create instrumentation.mjs at the project root:

import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { resourceFromAttributes } from '@opentelemetry/resources';

const sdk = new NodeSDK({
  resource: resourceFromAttributes({
    'service.name': process.env.OTEL_SERVICE_NAME || 'cloudmerce-nuxt-catalog'
  }),
  traceExporter: new OTLPTraceExporter()
});
sdk.start();
globalThis.__cloudmerceTelemetryShutdown = () => sdk.shutdown();

The resource identifies the service producing the telemetry. A stable service name helps group traces across process restarts. Do not put a request identifier into service.name; that would turn each request into a separate apparent service.

NodeSDK.start() registers the SDK components. Its shutdown method returns a promise, which we will await during server termination. These lifecycle methods are documented in the NodeSDK API.

The package's start script uses Node's preload option:

node --import ./instrumentation.mjs .output/server/index.mjs

Deploy the preload file and its production dependencies alongside the built output if you package this application elsewhere. Copying only .output would omit the SDK setup used here. Running the ordinary output entry point without the preload also bypasses tracing initialization.

Create a server span with an incoming parent

The route imports the API and obtains a named tracer:

import {
  context, propagation, SpanKind, SpanStatusCode, trace
} from '@opentelemetry/api'

const tracer = trace.getTracer('cloudmerce.catalog', '1.0.0')

At the start of the handler, extract context from the incoming headers:

const parent = propagation.extract(
  context.active(), getRequestHeaders(event)
)
return tracer.startActiveSpan('GET /api/catalog', {
  kind: SpanKind.SERVER,
  attributes: {
    'http.request.method': 'GET',
    'http.route': '/api/catalog'
  }
}, parent, async (span) => {
  // The operation and span cleanup go here.
})

This fragment shows the request boundary; the complete executable handler is in server/api/catalog.get.ts. When a valid sampled traceparent header arrives, the server span continues its trace. Without a valid incoming context, it can begin a new trace.

Using a route template as the span name keeps the set of names bounded. A raw URL can contain identifiers, search terms, or tokens and can create a different name for every request. The example also avoids recording request headers and query values as attributes.

startActiveSpan establishes the span as active while its callback executes. That matters when the callback crosses an await: a nested operation should still see the correct parent. OpenTelemetry's JavaScript instrumentation guide explains active spans and manual instrumentation.

If HTTP automatic instrumentation already creates a server span in your application, adapt this boundary to avoid duplicate server spans. You may only need an internal catalog operation under the existing active span. Verify the exported tree after making that change.

Trace the operation and its failure

Inside the request callback, the sample creates a child operation:

const items = await tracer.startActiveSpan('catalog.lookup', async (lookup) => {
  try {
    if (getQuery(event).fail === '1') {
      throw new Error('Synthetic catalog failure')
    }
    await new Promise(resolve => setTimeout(resolve, 5))
    return [{ sku: 'demo-book', available: true }]
  } catch (error) {
    lookup.recordException(error as Error)
    lookup.setStatus({
      code: SpanStatusCode.ERROR,
      message: 'Catalog lookup failed'
    })
    throw error
  } finally {
    lookup.end()
  }
})

The short timer represents asynchronous work; it is not a measured database latency. The explicit failure switch makes the error path reproducible without relying on an external outage.

Recording an exception and setting error status serve different purposes. The exception adds an event describing the failure, while the status marks the operation as failed. Ending the span in finally ensures both success and failure complete the span.

The outer callback records the HTTP response status, marks a failed request as an error, and returns a controlled 500 response through Nuxt's error helper. It ends the server span in its own finally block. The client receives a generic error while the lookup span contains the synthetic exception event.

In a real operation, review exception messages before exporting them. Database errors and upstream responses can contain sensitive fields. A tracing backend is another destination for application data, so choose attributes and events intentionally.

Configure OTLP without choosing a vendor

The selected exporter-trace-otlp-http package sends OTLP encoded as JSON over HTTP in this pinned version. The local check asserts its content type and decodes its payload. OTLP also supports HTTP/protobuf and gRPC; an HTTP port alone does not tell you which encoding the receiver accepts.

To inspect the demonstration manually, start the included receiver in one terminal:

npm run receiver

In another terminal in the same directory, run:

OTEL_SERVICE_NAME=cloudmerce-nuxt-catalog \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://127.0.0.1:4318/v1/traces \
OTEL_TRACES_SAMPLER=always_on \
OTEL_METRICS_EXPORTER=none \
OTEL_LOGS_EXPORTER=none \
npm start

Then request the two paths:

curl http://127.0.0.1:3000/api/catalog
curl 'http://127.0.0.1:3000/api/catalog?fail=1'

The receiver prints a span count rather than full telemetry. It is a loopback demonstration, with no storage, authentication, retry queue, or query interface. Stop both processes when finished. Export is batched, so receiving spans need not coincide immediately with the HTTP response.

The signal-specific OTEL_EXPORTER_OTLP_TRACES_ENDPOINT is a complete URL including /v1/traces. The generic OTEL_EXPORTER_OTLP_ENDPOINT has different path-appending behavior for HTTP. Check the OTLP exporter configuration specification rather than mixing the two forms.

For another backend, change the endpoint and provide any required authorization through secure environment configuration. A Collector can receive the app's OTLP and forward it to a destination, centralizing authentication and transport choices. Confirm that the receiver accepts this exporter's encoding; select a different exporter when it requires another protocol.

Jaeger's API documentation lists OTLP write endpoints, including HTTP on port 4318. SigNoz is another OpenTelemetry-based backend option. Neither product's web interface URL should be substituted for its ingestion endpoint. Backend installation and UI validation are outside this sample's verified scope.

Flush spans during Nitro shutdown

A batch exporter can still hold completed spans when the application stops. The preload exposes a shutdown callback, and server/plugins/telemetry.ts registers it with Nitro:

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('close', async () => {
    await (globalThis as typeof globalThis & {
      __cloudmerceTelemetryShutdown?: () => Promise<void>
    }).__cloudmerceTelemetryShutdown?.()
  })
})

The optional callback permits ordinary uninstrumented development. The integration check separately proves that the preloaded production path actually exports spans, so optional access cannot hide a broken SDK setup there. Nitro documents its asynchronous close hook in the plugin guide.

Use a graceful termination signal and allow sufficient shutdown time in the process manager. An immediate forced kill cannot run this hook. Exporter shutdown also cannot guarantee delivery during a network outage; it only gives pending work an opportunity to finish within its configured limits.

Verify the relationships, not just span counts

The automated check sends a successful request with a known remote parent and a concurrent failing request without that parent. It verifies four spans, the service resource, the server span kind, the incoming parent ID, the successful lookup's parent ID, and two error statuses isolated to the other trace. It also checks for the lookup exception event.

The check sets the scheduled batch delay to 60 seconds, then terminates Nitro immediately after the requests. Receiving the expected spans during graceful shutdown exercises the flush path rather than simply waiting for periodic export. These are correctness assertions, not latency or overhead benchmarks.

If the check passes but another environment shows no traces, first confirm that its launch command includes the preload. Then check the service name, endpoint path, receiver protocol, and sampling configuration. A healthy application response says nothing about exporter connectivity. Inspect bounded diagnostics without printing authorization headers or complete request payloads.

For production, choose sampling intentionally. always_on is useful for this tiny deterministic demonstration, but exporting every request can increase network traffic and backend storage. A parent-based sampling policy can preserve an upstream decision while controlling traces that originate in this service. Validate that policy with both sampled and unsampled incoming contexts before relying on trace counts during an incident.

Measure overhead against a representative workload if it matters to your deployment. The synthetic timer and four-span correctness check provide no basis for claiming a particular latency cost, throughput improvement, or storage reduction. Keep operational measurements separate from the evidence that spans have the right parents and reach an OTLP receiver.

What we learned

We initialized tracing before the built Node server, connected explicit request and operation spans, and exported real OTLP payloads locally. We verified parent propagation, concurrent context isolation, error recording, and shutdown delivery. That gives us a tested foundation for choosing an ingestion backend and expanding instrumentation deliberately.

We will migrate a small customer collection using a Node.js exporter and Wrangler's local D1 runtime. The exporter streams documents, validates their shape, and writes bounded SQL statements. Replaying those statements updates existing rows by their original identifiers. The sample uses synthetic fixtures; no live MongoDB server or remote D1 database was used during verification.

This is a practical pattern for a modest, controlled migration in a stack like Cloudmerce's. It is not a change-data-capture system, an arbitrary BSON converter, or a promise that moving databases improves application performance. Those are separate engineering questions.

Run the complete example first

The project lives in code/mongo-to-d1. From the articles directory:

cd code/mongo-to-d1
npm ci
npm run export:fixture
npm run check

Verification used Node 22.23.3, MongoDB's Node driver 6.21.0, and Wrangler 4.90.0. The package lockfile fixes the dependency tree. This project is plain JavaScript, so there is no compilation step: running the exporter and the integration check exercises the executable code.

The fixture export writes generated/export/manifest.json and numbered SQL files. It requires an empty output directory. To repeat the export, choose a fresh destination:

OUTPUT_DIR=generated/second-export npm run export:fixture

The check uses a separate temporary directory and its own local D1 state. It creates the schema, imports two batches, imports them again, and compares every stored value with the expected mapping. It also exercises invalid documents and an oversized row. It cleans up its temporary state afterward.

Decide what each field means

Our source contract is intentionally narrow:

Preserving _id keeps existing application references meaningful. Replacing it with an unrelated autoincrement key would require another mapping table and changes wherever those references are used.

We keep arrays as JSON because this example reads an entire customer record. If the application frequently filters by individual tags, consider a separate customer-tags table and suitable indexes. The schema should follow the destination access patterns rather than mechanically reproducing every document shape.

The sample treats a missing profile and an explicit null profile identically. It also projects away fields outside the contract. Both choices are data decisions: review them before exporting real records. An audit should identify any fields or distinctions that would be lost.

Create a schema with useful constraints

The accompanying schema.sql contains:

CREATE TABLE IF NOT EXISTS customers (
  id TEXT PRIMARY KEY NOT NULL,
  email TEXT NOT NULL,
  active INTEGER NOT NULL CHECK (active IN (0, 1)),
  created_at TEXT NOT NULL,
  tags_json TEXT NOT NULL CHECK (json_valid(tags_json)),
  profile_json TEXT CHECK (profile_json IS NULL OR json_valid(profile_json))
);
CREATE INDEX IF NOT EXISTS customers_email ON customers(email);

The email index supports lookups without imposing uniqueness that the source contract never guaranteed. If your product requires unique email addresses, first measure and resolve duplicates in the source, then make that constraint explicit.

SQLite's type system differs from MongoDB's BSON model. Here the exporter checks application types, while SQL constraints provide another boundary for required values, booleans, and valid JSON. The timestamp column's text declaration does not by itself validate a timestamp; that guarantee comes from the mapping function.

CREATE TABLE IF NOT EXISTS makes initial setup repeatable, but does not migrate an existing, incompatible table. For a real application, put schema changes under versioned migrations and test upgrades against a copy of the existing database.

The D1 import guide requires SQLite-compatible SQL rather than a raw SQLite database file. It also warns about transaction wrappers in imported dumps. Our generated files contain insert statements without explicit BEGIN or COMMIT wrappers.

Validate before converting

The full mapCustomer function is in export.mjs. Its most important property is that it rejects unexpected types instead of silently coercing them. For example:

if (typeof doc.active !== 'boolean') {
  throw new Error('Expected active boolean');
}
if (!(doc.createdAt instanceof Date) ||
    !Number.isFinite(doc.createdAt.getTime())) {
  throw new Error('Expected valid createdAt Date');
}

Using Boolean(doc.active) would turn the string "false" into true. Accepting an invalid date would defer the problem to serialization or create inconsistent output. Rejecting either record makes the migration's assumptions visible.

The mapping produces this ordered row:

return [
  doc._id.toHexString(),
  doc.email,
  doc.active ? 1 : 0,
  doc.createdAt.toISOString(),
  JSON.stringify(doc.tags),
  doc.profile == null ? null : JSON.stringify(doc.profile)
];

The executable version also validates ObjectIds, emails, tags, and the flat profile shape. A nested object inside profile is rejected. That prevents an unexpected BSON value from being flattened into a misleading string.

If your source includes Decimal128, binary data, or integers outside JavaScript's safe range, design additional mappings before extending the exporter. MongoDB's Extended JSON documentation explains a representation that preserves BSON type information. Ordinary JSON serialization is not a general solution to BSON fidelity.

Stream from MongoDB

For a real source, the exporter opens a client and obtains a cursor:

const documents = client.db(process.env.MONGO_DB)
  .collection(process.env.MONGO_COLLECTION)
  .find({}, {
    projection: {
      _id: 1, email: 1, active: 1,
      createdAt: 1, tags: 1, profile: 1
    }
  })
  .sort({ _id: 1 })
  .batchSize(100);

The surrounding function consumes it with for await (const doc of documents). This avoids loading the entire collection through toArray(). MongoDB documents asynchronous iteration in its cursor guide.

MongoDB's cursor batch size controls document fetching. It is independent of the SQL batch size used for D1. Keeping those settings separate lets us bound destination statements without pretending that source documents have uniform sizes.

The live-source branch reads MONGO_URI, MONGO_DB, and MONGO_COLLECTION from the process environment. Supply these through your existing secure environment mechanism, using a source account with read-only access. Run node export.mjs without --fixture. The script does not print the URI or raw driver errors, since those can expose connection details.

The live connection path is included for adaptation but was not verified against a running MongoDB instance. The fixture does use real driver ObjectId objects and JavaScript Dates, so the mapping runs against the intended types.

Bound inserts by rows and bytes

Each SQL file contains one multi-row insert followed by an upsert clause. The exporter flushes after at most 50 rows or before a statement would exceed 80,000 UTF-8 bytes. Those are conservative sample settings, not throughput recommendations.

D1's documented limits include a 100,000-byte SQL statement maximum and 100 bound parameters per query at the time of writing. This sample emits literal SQL rather than placeholders, so statement size is the relevant batching constraint. If you switch to prepared statements with six bound values per row, recalculate the row limit against the parameter budget.

Variable-length values make row counts alone unreliable. The exporter includes the insert prefix, separators, and upsert suffix in its byte accounting. It rejects a single row that cannot fit, rather than emitting a statement that the destination will reject later.

To serialize text safely into these generated files, it uses UTF-8 hex literals cast back to text:

function sql(value) {
  if (value === null) return 'NULL';
  if (typeof value === 'number') return String(value);
  return `CAST(X'${Buffer.from(value, 'utf8').toString('hex')}' AS TEXT)`;
}

Only the validated zero-or-one boolean reaches the numeric branch. Column and table names are fixed in code. Hex encoding avoids quote-escaping mistakes and preserves Unicode and embedded control characters; it is encoding, not encryption. Protect generated SQL files as carefully as the source data.

The fixture includes an apostrophe, non-Latin text, a newline, a null character inside a tag, and a string resembling SQL injection. Exact-value assertions confirm that those values remain data after importing.

Import locally and inspect the result

The Wrangler configuration contains a dummy database identifier. With --local, it identifies local development state and does not provision a remote database. Run:

npx wrangler d1 execute migration-demo --local --file schema.sql
for file in generated/export/*.sql; do
  npx wrangler d1 execute migration-demo --local --file "$file" || break
done
npx wrangler d1 execute migration-demo --local \
  --command 'SELECT id, active, created_at FROM customers ORDER BY id'

The loop stops after a failed batch. In an operational migration runner, record the completed filenames and return a failing exit code on error so automation cannot mistake partial progress for completion.

The upsert updates destination fields when id already exists. That makes retrying an immutable export safe for these columns, but it can overwrite edits made in D1 after the first import. It also does not remove destination rows whose source documents were deleted. Define destination ownership and deletion behavior before using this pattern beyond a rehearsal.

Plan the actual cutover

Sorting by _id produces stable ordering; it does not create a consistent snapshot while writers continue changing the collection. For a small migration, a scheduled write pause and a fresh export may be the clearest approach. Larger systems need an explicit snapshot and change-capture strategy.

Export files are individually finalized through a temporary-file rename, and the manifest is written only after iteration succeeds. A failure can still leave completed files from a partial export. Require the manifest, check its counts, and never import a failed export directory as though it were complete. Start the next attempt in a fresh directory.

Before a remote migration, provision the destination through an authorized process, replace the dummy identifier, rehearse against representative data, and define rollback. Compare source and destination counts, selected records, timestamps, and business invariants. A matching count alone cannot detect corrupted field values.

Also validate how the application reads the new representation. A query returns tags_json as text, so the destination data layer must parse it before exposing a string array. The integer active value should be converted deliberately when constructing an API response. Avoid letting a database migration silently change the public response contract.

Keep the original export and its manifest together during reconciliation, with access restricted to the migration operators. Record which export was imported into which destination and when writes resumed. If rollback remains possible, define how destination writes will be recovered first; switching the application back cannot automatically copy new D1 data into MongoDB.

What we learned

We made the migration contract explicit, streamed source documents through strict validation, and generated bounded, replayable SQL. Local D1 checks verified schema compatibility and exact values, including awkward strings. A production cutover still needs a consistent source, destination ownership rules, and independent reconciliation before application traffic moves.

A Nuxt application has more than one deployment target. Its Vue components run in the browser, but server rendering and API handlers need a server runtime. When that runtime is Cloudflare Workers, the build must produce a Worker entry point and make the browser assets available alongside it.

In this tutorial, we will build a small server-rendered page, read a runtime variable from a Nitro handler, and run the production output with Wrangler. We will also prepare the commands for a real deployment and a custom domain. The accompanying sample was built and exercised locally; account authentication, publishing, remote secrets, and DNS changes were not performed.

The example uses the kind of application boundary found in the Cloudmerce stack: a Nuxt frontend with a small server API. It is a standalone demonstration, with synthetic content and no production credentials or customer data.

Start from the runnable sample

The complete project is in code/nuxt-workers. From this articles directory, run:

cd code/nuxt-workers
npm ci
npm run build
npm run check

Use Node 22.23.3, the version used for verification, or a compatible supported Node release. The sample pins Nuxt 3.21.11 and Wrangler 4.90.0, and its lockfile records transitive dependencies. The verified build resolved Nitro 2.13.5. This is deliberately a Nuxt 3 example; copying a newer framework starter can give you a different major version and output layout.

npm run check starts Wrangler locally, requests the API and rendered page, fetches the referenced client assets, and shuts the process down. For an interactive preview, use npm run preview and open http://127.0.0.1:8787. Stop that preview before running the automated check because they share a port.

A build only checks one part of the system. The local runtime check matters because a successful bundle can still point Wrangler at the wrong output directory, omit assets, or read a variable at the wrong time.

Choose the Worker module preset

The sample's nuxt.config.ts selects the Nitro target explicitly:

export default defineNuxtConfig({
  compatibilityDate: '2026-05-01',
  devtools: { enabled: false },
  nitro: { preset: 'cloudflare_module' }
})

Nuxt handles the application build, while Nitro produces the server artifact for the selected platform. The Nitro 2 Cloudflare guide documents cloudflare_module for Workers and distinguishes it from the deprecated cloudflare service-worker preset. It also describes generated deployment configuration; here we keep a small, explicit Wrangler file so the deployment inputs are visible.

After building, the important paths are .output/server/index.mjs for the server and .output/public for static files. Do not use nuxt generate for this exercise: we want a server handler that reads bindings when a request arrives.

There are two compatibility dates in the project. The Nuxt configuration guides framework output choices. The Wrangler configuration selects runtime compatibility behavior. We keep them aligned so a future change is deliberate and reviewable. Neither date upgrades the packages recorded in the lockfile.

Connect the server and its assets

Here is the complete wrangler.jsonc:

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "cloudmerce-nuxt-workers-demo",
  "main": ".output/server/index.mjs",
  "compatibility_date": "2026-05-01",
  "compatibility_flags": ["nodejs_compat"],
  "assets": {
    "directory": ".output/public",
    "binding": "ASSETS"
  },
  "vars": {
    "APP_GREETING": "Hello from Cloudmerce on Workers"
  }
}

The entry point is relative to the project root. The ASSETS binding connects Nitro's asset handling to the uploaded public directory. This includes files copied from public/ and the compiled JavaScript that hydrates the page in the browser. The sample includes a small SVG so we can verify a plain public file as well as generated assets.

The nodejs_compat flag enables the supported Node compatibility surface in Workers. It does not turn a Worker into a persistent Node server. Before bringing an existing dependency into this target, check its runtime requirements, especially filesystem assumptions, native addons, and background processes. See Cloudflare's Node compatibility documentation for the supported APIs and limitations.

Keep application configuration in source and build artifacts out of source control. The repository ignore file excludes .nuxt, .output, node_modules, and Wrangler's local state. A clean checkout should reproduce the output through npm ci and npm run build.

Read bindings inside a request

Create server/api/health.get.ts:

export default defineEventHandler((event) => {
  const env = event.context.cloudflare?.env
  return {
    message: env?.APP_GREETING || 'Hello from Nuxt development',
    secretConfigured: Boolean(env?.API_TOKEN)
  }
})

The Cloudflare adapter places runtime bindings on the event context. Reading them inside the handler ties configuration to the current request. A module-level constant initialized during bundling would be the wrong place to resolve a deployment secret.

The fallback greeting makes the page usable during ordinary Nuxt development. The local Worker check asserts the configured greeting instead, so that fallback cannot quietly hide a missing binding in the verified production build.

secretConfigured demonstrates access without returning the token itself. It is only a teaching aid: a real public health endpoint usually needs to reveal less about internal configuration. Never return the environment object or spread it into a response. Server execution alone does not make response data private.

For a larger app, you may prefer Nuxt runtime configuration with explicitly declared keys and request-scoped access. Keep private values out of runtimeConfig.public, which is intended for client-visible configuration. This example reads the Worker binding directly to make the platform boundary easy to inspect.

Render the API result on the page

The sample's app.vue requests that handler:

<script setup lang="ts">
const { data } = await useFetch('/api/health')
</script>

<template>
  <main>
    <h1>Cloudmerce on Workers</h1>
    <p>{{ data?.message }}</p>
    <img src="/mark.svg" alt="Cloudmerce demo mark" width="48" height="48">
  </main>
</template>

useFetch integrates the request with Nuxt's rendering and payload handling. Using a relative application URL also avoids embedding a development hostname into the component.

The automated check looks for the configured greeting in the HTML response. This checks that the server-rendered page can reach the handler with the expected context, rather than merely proving that /api/health works when called directly.

The check also fetches client asset URLs from the HTML and confirms they return successful, non-HTML responses. A server can return a convincing page while serving an HTML fallback where JavaScript should be. Checking both paths catches that deployment mistake early. It does not replace a browser test of hydration and interaction when the application grows.

Separate ordinary variables from secrets

The greeting belongs in vars because it is harmless, reviewable configuration. Tokens belong in secret storage. For a local-only secret exercise, create an ignored .dev.vars file inside the sample directory with an intentionally fake value:

API_TOKEN="local-demo-value-not-a-real-token"

Restart Wrangler after changing the file. Requesting /api/health should now report secretConfigured: true, while still returning no token value. Delete the file when finished. The committed sample does not require it, and automated checks do not depend on any real secret.

Cloudflare documents .dev.vars for local secrets and wrangler secret put for remote values in its secrets guide. A local file is not automatically copied into remote secret storage during deployment.

Likewise, an environment variable available to the build machine is not automatically a Worker binding. Treat build inputs and runtime inputs as separate configuration surfaces. This distinction prevents confusing situations where a project works in CI but fails after deployment because a handler cannot find its runtime credential.

Avoid putting secrets in package scripts, committed configuration, browser payloads, or diagnostic screenshots. When debugging, inspect whether a binding exists and whether the downstream call succeeds, without logging its contents.

Prepare the deployment and domain

The following commands are a future deployment procedure. They were not executed for this sample. They require an existing Cloudflare account, an appropriate authorization method, and a review of the chosen account's limits and billing configuration.

First choose a unique Worker name in wrangler.jsonc. Build the exact revision you intend to publish, then authenticate and deploy from the sample directory:

npm run build
npx wrangler login
npx wrangler deploy

For a real server credential, use the interactive prompt rather than placing its value in the command:

npx wrangler secret put API_TOKEN

The example handler only reports presence, so it can run before that secret exists. An application that requires a credential should validate configuration and return a controlled failure until setup is complete. Verify that the authorization context points to the intended account before any remote command.

For a hostname such as app.example.com, add this top-level field to the Wrangler configuration, replacing the example with a hostname in your own Cloudflare zone:

"routes": [
  { "pattern": "app.example.com", "custom_domain": true }
]

This is a configuration fragment to merge into the existing object. Deploying that configuration attaches the hostname. A Custom Domain makes the Worker the origin; a route pattern that proxies an existing origin serves a different purpose. Cloudflare's Custom Domains guide explains zone prerequisites and certificate management.

Before attaching an existing hostname, inspect its current DNS and routing ownership. After an authorized deployment, verify the hostname over HTTPS, request the API, and inspect browser assets again. Local preview cannot validate account permissions, certificate issuance, public DNS, or behavior at Cloudflare's network edge.

Diagnose failures at the right boundary

If Wrangler cannot find the entry point, confirm the working directory and rebuild. If HTML loads but client scripts fail, inspect the assets directory and binding. If the greeting falls back unexpectedly, compare the runtime variable spelling with the handler and restart local preview.

When a package fails only under Wrangler, reproduce the issue with the production output and check whether the dependency expects an unsupported Node facility. Changing presets can make an error disappear while changing the intended deployment runtime, so keep the target explicit during investigation.

One failure found while preparing this sample was a compatibility date newer than the runtime bundled with the pinned Wrangler release. The application compiled, but the local Worker refused to start. Aligning both configuration dates to 2026-05-01 fixed the mismatch, and the check then passed. When updating the date later, update and test the local toolchain together rather than assuming a successful framework build proves runtime support.

For an existing application, extend the same check with one representative authenticated request and one expected failure response. Use synthetic credentials and fixtures. This gives you evidence about your own application's runtime assumptions before you involve public DNS or production services.

What we learned

We built a Nuxt 3 Worker with separate server and asset outputs, verified SSR and asset delivery locally, and read configuration from request-scoped bindings. We also prepared secret and custom-domain setup without performing remote changes. The useful deployment habit is to test the complete built artifact, then verify the account and network boundaries separately when deployment is authorized.