docs(node): align ingest URL, ESM-only guidance, Express error handler

apps/dashboard/app/docs/node/page.tsx

@@ -3,6 +3,8 @@ import Link from "next/link";
 import { CodeBlock } from "@/app/components/docs/CodeBlock";
 import { DocsAlsoSee } from "@/app/components/docs/DocsAlsoSee";
 import { DocsArticle } from "@/app/components/docs/DocsArticle";
+import { HOSTED_API_URL } from "@/lib/hosted-cloud";
+import { nodeCommonJs, nodeExpressErrorHandler, nodeSetup } from "@/lib/sdk-setup-snippets";
 
 export const metadata: Metadata = {
   title: "Node.js",
@@ -35,19 +37,23 @@ npm install @telemetry-tracker/node`}
       <p>
         Call <code>init()</code> as early as possible (e.g. at the top of your entry file):
       </p>
-      <CodeBlock
-        code={`import { init, trackEvent, trackError } from "@telemetry-tracker/node";
-
-init({
-  ingestUrl: process.env.TELEMETRY_INGEST_URL || "https://your-api.example.com",
-  app: "my-api",
-  apiKey: process.env.TELEMETRY_API_KEY,
-  platform: "node",
-});
+      <CodeBlock code={nodeSetup} />
+      <p>
+        <code>ingestUrl</code> is required: the SDK has no built-in default. The fallback above is
+        the hosted API (<code>{HOSTED_API_URL}</code>); set <code>TELEMETRY_INGEST_URL</code> to
+        your own API when self-hosting.
+      </p>
 
-trackEvent("server_started", { version: "1.0.0" });
-trackError(new Error("DB connection failed"), { db: "primary" });`}
-      />
+      <h2>ES modules only</h2>
+      <p>
+        <code>@telemetry-tracker/node</code> is published as an ES module only: its <code>package.json</code> sets{" "}
+        <code>{`"type": "module"`}</code> and exports only an <code>import</code> condition. Use{" "}
+        <code>import</code> in <code>.mjs</code> files or packages with{" "}
+        <code>{`"type": "module"`}</code>. <code>{`require("@telemetry-tracker/node")`}</code> is not
+        supported. From CommonJS code, load it with a dynamic <code>import()</code> and await{" "}
+        <code>flush()</code> inside an async function:
+      </p>
+      <CodeBlock code={nodeCommonJs} />
 
       <h2>Short-lived scripts and jobs</h2>
       <p>
@@ -110,6 +116,14 @@ app.use((req, res, next) => {
         .
       </p>
 
+      <h2>Express error handler</h2>
+      <p>
+        Errors that Express catches in a route never reach the global handlers. Report them from an
+        error-handling middleware (four arguments, registered after your routes) with{" "}
+        <code>trackError()</code>, then pass the error on:
+      </p>
+      <CodeBlock code={nodeExpressErrorHandler} />
+
       <DocsAlsoSee
         links={[
           { href: "/error-tracking/nodejs", label: "Node.js error tracking guide" },

apps/dashboard/app/error-tracking/nodejs/page.tsx

@@ -11,7 +11,8 @@ import {
   webPageJsonLd,
 } from "@/lib/marketing-guide-metadata";
 import { marketingSiteOrigin } from "@/lib/marketing-json-ld";
-import { nodeInstall, nodeMiddleware, nodeSetup, nodeTestError } from "@/lib/sdk-setup-snippets";
+import { nodeExpressErrorHandler, nodeInstall, nodeMiddleware, nodeSetup, nodeTestError } from "@/lib/sdk-setup-snippets";
+import { HOSTED_API_URL } from "@/lib/hosted-cloud";
 
 const PATH = "/error-tracking/nodejs";
 const TITLE = "Node.js Error Tracking";
@@ -111,6 +112,12 @@ export default function NodeJsErrorTrackingPage() {
         <h2>Minimal setup</h2>
         <p>Call init at the top of your entry file. Keep the API key in an environment variable:</p>
         <CodeBlock code={nodeSetup} lang="typescript" caption="init" />
+        <p>
+          <code>ingestUrl</code> is required: the SDK has no built-in default. The fallback above is
+          the hosted API (<code>{HOSTED_API_URL}</code>); point <code>TELEMETRY_INGEST_URL</code> at
+          your own API when self-hosting. The package is ES modules only; see the{" "}
+          <Link href="/docs/node" className="text-brand hover:underline">Node.js docs</Link> for use from CommonJS.
+        </p>
 
         <h2>Send a test error</h2>
         <CodeBlock code={nodeTestError} lang="typescript" caption="Test error" />
@@ -127,6 +134,13 @@ export default function NodeJsErrorTrackingPage() {
         </p>
         <CodeBlock code={nodeMiddleware} lang="typescript" caption="middleware" />
 
+        <h2>Express error handler</h2>
+        <p>
+          Errors Express catches in a route do not reach the global handlers. Report them from an
+          error-handling middleware registered after your routes:
+        </p>
+        <CodeBlock code={nodeExpressErrorHandler} lang="typescript" caption="Express error handler" />
+
         <h2>What you will see</h2>
         <p>
           Server errors group like browser issues: fingerprint, stack, and the context object you

apps/dashboard/lib/sdk-setup-snippets.ts

@@ -172,6 +172,36 @@ app.use((req, res, next) => {
   });
 });`;
 
+export const nodeExpressErrorHandler = `import express from "express";
+import { init, middleware, trackError } from "@telemetry-tracker/node";
+
+init({
+  ingestUrl: process.env.TELEMETRY_INGEST_URL || "${HOSTED_API_URL}",
+  app: "my-api",
+  apiKey: process.env.TELEMETRY_API_KEY,
+});
+
+const app = express();
+app.use(middleware());
+
+// ... your routes ...
+
+// Error-handling middleware: four arguments, registered after all routes.
+app.use((err, req, res, next) => {
+  trackError(err, { method: req.method, url: req.originalUrl });
+  next(err); // keep Express's default error response (or send your own)
+});`;
+
+export const nodeCommonJs = `// CommonJS file (.cjs, or "type" is not "module"): load the ESM package with import()
+async function main() {
+  const { init, trackEvent, flush } = await import("@telemetry-tracker/node");
+  init({ ingestUrl: process.env.TELEMETRY_INGEST_URL || "${HOSTED_API_URL}", app: "my-script", apiKey: process.env.TELEMETRY_API_KEY });
+  trackEvent("script_finished");
+  await flush();
+}
+
+main();`;
+
 export const nodeTestError = `import { trackError } from "@telemetry-tracker/node";
 
 trackError(new Error("Test error from Node.js"), { route: "/health" });`;