@mohasinac/instrumentation 1.1.0

package/dist/index.cjs

@@ -0,0 +1,37 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createInstrumentation: () => createInstrumentation
+});
+module.exports = __toCommonJS(index_exports);
+function createInstrumentation(config) {
+  return {
+    register: async () => {
+      if (process.env.NEXT_RUNTIME === "edge") return;
+      await config.onNodeServer();
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createInstrumentation
+});

package/dist/index.d.cts

@@ -0,0 +1,66 @@
+/**
+ * @mohasinac/instrumentation
+ *
+ * Minimal Next.js instrumentation hook factory.
+ *
+ * ## What belongs HERE (in Next.js instrumentation)
+ *
+ *   - Provider/DI registration via registerProviders() — this MUST run before
+ *     any API route handler calls getProviders().
+ *
+ * ## What belongs in Firebase Functions instead of Next.js instrumentation
+ *
+ *   On Vercel Hobby (free) tier, each serverless function invocation is billed
+ *   and cold-start time is limited. Heavy observability setup should live in
+ *   Firebase Functions (free tier: 2 M invocations/month, 400 K GB-seconds):
+ *
+ *   - APM / OpenTelemetry tracing — use a Firebase scheduled function to poll
+ *     or process trace data asynchronously.
+ *   - Error alerting / log aggregation — use Firestore triggers or scheduled
+ *     jobs in functions/src/ (already present in this project).
+ *   - Health checks / uptime monitoring — Firebase scheduled function pinging
+ *     an internal pub/sub or writing to Firestore.
+ *   - Performance budget checks — scheduled Firebase function reading Cloud
+ *     Run metrics and writing summaries to Firestore.
+ *
+ * ## Usage (in app root instrumentation.ts)
+ *
+ * ```ts
+ * import { createInstrumentation } from "@mohasinac/instrumentation";
+ *
+ * const { register } = createInstrumentation({
+ *   onNodeServer: async () => {
+ *     await import("./src/providers.config");
+ *   },
+ * });
+ *
+ * export { register };
+ * ```
+ */
+interface InstrumentationConfig {
+    /**
+     * Called ONCE when the Node.js runtime initialises (never on Edge runtime).
+     * Use this to register providers and do any one-time server setup that must
+     * complete before the first API route handler runs.
+     *
+     * Keep this function fast (< 50 ms). Any slow I/O, monitoring agents, or
+     * APM SDKs should live in Firebase Functions instead.
+     */
+    onNodeServer: () => Promise<void>;
+}
+interface InstrumentationHook {
+    /**
+     * The `register` export required by Next.js instrumentation.ts.
+     * Next.js calls this exactly once per server process start.
+     */
+    register: () => Promise<void>;
+}
+/**
+ * Creates a Next.js-compatible instrumentation hook.
+ *
+ * The returned `register` function is a no-op on the Edge runtime and calls
+ * `onNodeServer` exactly once on the Node.js runtime.
+ */
+declare function createInstrumentation(config: InstrumentationConfig): InstrumentationHook;
+
+export { type InstrumentationConfig, type InstrumentationHook, createInstrumentation };

package/dist/index.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @mohasinac/instrumentation
+ *
+ * Minimal Next.js instrumentation hook factory.
+ *
+ * ## What belongs HERE (in Next.js instrumentation)
+ *
+ *   - Provider/DI registration via registerProviders() — this MUST run before
+ *     any API route handler calls getProviders().
+ *
+ * ## What belongs in Firebase Functions instead of Next.js instrumentation
+ *
+ *   On Vercel Hobby (free) tier, each serverless function invocation is billed
+ *   and cold-start time is limited. Heavy observability setup should live in
+ *   Firebase Functions (free tier: 2 M invocations/month, 400 K GB-seconds):
+ *
+ *   - APM / OpenTelemetry tracing — use a Firebase scheduled function to poll
+ *     or process trace data asynchronously.
+ *   - Error alerting / log aggregation — use Firestore triggers or scheduled
+ *     jobs in functions/src/ (already present in this project).
+ *   - Health checks / uptime monitoring — Firebase scheduled function pinging
+ *     an internal pub/sub or writing to Firestore.
+ *   - Performance budget checks — scheduled Firebase function reading Cloud
+ *     Run metrics and writing summaries to Firestore.
+ *
+ * ## Usage (in app root instrumentation.ts)
+ *
+ * ```ts
+ * import { createInstrumentation } from "@mohasinac/instrumentation";
+ *
+ * const { register } = createInstrumentation({
+ *   onNodeServer: async () => {
+ *     await import("./src/providers.config");
+ *   },
+ * });
+ *
+ * export { register };
+ * ```
+ */
+interface InstrumentationConfig {
+    /**
+     * Called ONCE when the Node.js runtime initialises (never on Edge runtime).
+     * Use this to register providers and do any one-time server setup that must
+     * complete before the first API route handler runs.
+     *
+     * Keep this function fast (< 50 ms). Any slow I/O, monitoring agents, or
+     * APM SDKs should live in Firebase Functions instead.
+     */
+    onNodeServer: () => Promise<void>;
+}
+interface InstrumentationHook {
+    /**
+     * The `register` export required by Next.js instrumentation.ts.
+     * Next.js calls this exactly once per server process start.
+     */
+    register: () => Promise<void>;
+}
+/**
+ * Creates a Next.js-compatible instrumentation hook.
+ *
+ * The returned `register` function is a no-op on the Edge runtime and calls
+ * `onNodeServer` exactly once on the Node.js runtime.
+ */
+declare function createInstrumentation(config: InstrumentationConfig): InstrumentationHook;
+
+export { type InstrumentationConfig, type InstrumentationHook, createInstrumentation };

package/dist/index.js

@@ -0,0 +1,12 @@
+// src/index.ts
+function createInstrumentation(config) {
+  return {
+    register: async () => {
+      if (process.env.NEXT_RUNTIME === "edge") return;
+      await config.onNodeServer();
+    }
+  };
+}
+export {
+  createInstrumentation
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@mohasinac/instrumentation",
+  "version": "1.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src"
+  },
+  "peerDependencies": {
+    "next": ">=14"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "eslint": "^9.37.0"
+  }
+}