@caregenix/dbconfigmanager

Load server environment variables from local .env, .env.json cache, or a remote config API — with the same behavior as the PyPI dbconfigmanager package.

Built for Node.js and Next.js App Router (server). Client-side NEXT_PUBLIC_* values use standard Next.js .env.local (not this package).

Install

npm install @caregenix/dbconfigmanager

Peer dependency (optional): next ≥ 13 — only required for @caregenix/dbconfigmanager/next.

What it does

| Step | Source | When | |------|--------|------| | 1 | .env in project root | If the file exists, remote fetch is skipped | | 2 | .env.json cache | If present and not forcing refresh | | 3 | Remote API | Fetches server settings, writes cache, sets process.env on the server |

NEXT_PUBLIC_* keys from the remote API are not applied to process.env — put those in .env.local so Next.js inlines them into the client bundle at build time.

Access server values: config.SUMO_HTTP_SOURCE (dot notation) or config.get("KEY").

Python → JavaScript API

| Python | JavaScript | |--------|------------| | init_service_env(name, root_path=..., url=...) | initServiceEnv(name, { rootPath, url }) — @caregenix/dbconfigmanager/node | | config.SUMO_HTTP_SOURCE | config.SUMO_HTTP_SOURCE | | config.all() | config.all() | | reset_service_settings_cache() | resetServiceSettingsCache() |

Next.js helpers (@caregenix/dbconfigmanager/next):

| Helper | Purpose | |--------|---------| | initNextServiceEnv(...) | Same as initServiceEnv, default rootPath = process.cwd() | | getServiceConfig() | Read config after init (server only) | | resetServiceSettingsCache() | Clear cache and refetch from API |

Note: initServiceEnv / initNextServiceEnv return a config Proxy (not a plain object). After init completes, read settings with getServiceConfig() or getConfig() in your app — do not depend on the Proxy as a Promise fulfillment value. The Proxy intentionally ignores then / catch / finally so await initNextServiceEnv(...) and initPromise.then(...) work correctly.

Quick start — Next.js

Server secrets → this package (remote API). Client public vars → .env.local + process.env.NEXT_PUBLIC_*.

1. .env.local

# Server — used by dbconfigmanager (never use NEXT_PUBLIC_ prefix for these)
SERVICE_NAME=AI_SUMMARIES
CONFIG_API_URL=https://your-api.example.com/api/ServiceParameter/service-parameter-by-service-name?ai_key=YOUR_KEY

# Client — inlined by Next.js at build time (do not fetch these via dbconfigmanager)
NEXT_PUBLIC_API_BASE=https://api.example.com

2. Enable instrumentation

next.config.ts:

const nextConfig = {
  experimental: { instrumentationHook: true },
};
export default nextConfig;

instrumentation.ts (project root):

export async function register() {
  const { ensureServiceConfig } = await import("./lib/config.server");
  await ensureServiceConfig();
}

3. Server-only config module

lib/config.server.ts:

import "server-only";
import { initNextServiceEnv, getServiceConfig } from "@caregenix/dbconfigmanager/next";

let initPromise: ReturnType<typeof initNextServiceEnv> | null = null;

function requireEnv(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`${name} is not set in .env.local`);
  return value;
}

export function ensureServiceConfig() {
  if (!initPromise) {
    initPromise = initNextServiceEnv(requireEnv("SERVICE_NAME"), {
      rootPath: process.cwd(),
      url: requireEnv("CONFIG_API_URL"),
    });
  }
  return initPromise;
}

export async function getConfig() {
  await ensureServiceConfig();
  return getServiceConfig();
}

4. Server — API routes & Server Components

// app/api/health/route.ts
import { getConfig } from "@/lib/config.server";

export async function GET() {
  const config = await getConfig();
  return Response.json({ sumoConfigured: Boolean(config.SUMO_HTTP_SOURCE) });
}

// app/page.tsx (Server Component)
import { getConfig } from "@/lib/config.server";
import { ClientApp } from "./client-app";

export default async function Page() {
  const config = await getConfig();
  return (
    <>
      <p>Server secret loaded: {String(Boolean(config.SUMO_HTTP_SOURCE))}</p>
      <ClientApp />
    </>
  );
}

5. Client — standard Next.js env (no dbconfigmanager)

// app/client-app.tsx
"use client";

export function ClientApp() {
  return <p>API base: {process.env.NEXT_PUBLIC_API_BASE}</p>;
}

Production build (next build)

| Concern | Approach | |---------|----------| | Server secrets (SUMO_HTTP_SOURCE, etc.) | dbconfigmanager + CONFIG_API_URL / SERVICE_NAME in deploy env | | Client public vars | NEXT_PUBLIC_* in .env.local or deploy env — baked in at build time | | Never | Import config.server or dbconfigmanager/next in Client Components | | Never | Put CONFIG_API_URL or ai_key in NEXT_PUBLIC_* |

flowchart LR
  subgraph server [Server]
    A[instrumentation.ts] --> B[initNextServiceEnv]
    B --> C[Remote API / cache]
    D[getConfig] --> E[SUMO_HTTP_SOURCE]
  end
  subgraph client [Client bundle]
    F["process.env.NEXT_PUBLIC_*"] --> G[.env.local at build]
  end

Plain Node.js

import { initServiceEnv, getServiceConfig } from "@caregenix/dbconfigmanager/node";

await initServiceEnv(process.env.SERVICE_NAME!, {
  rootPath: process.cwd(),
  url: process.env.CONFIG_API_URL,
});

const config = getServiceConfig();
console.log(config.SUMO_HTTP_SOURCE);

Options

| Option | Default | Description | |--------|---------|-------------| | rootPath | process.cwd() | Directory for .env and .env.json | | url | — | Remote config API URL (required if no .env) | | envFile | .env | Local env file name | | cacheFile | .env.json | Remote settings cache file | | forceRefresh | false | Skip cache and refetch |

Package exports

| Import path | Use in | |-------------|--------| | @caregenix/dbconfigmanager | Types and shared utilities | | @caregenix/dbconfigmanager/node | Node scripts, standalone servers | | @caregenix/dbconfigmanager/next | Next.js server only | | @caregenix/dbconfigmanager/client | Legacy — prefer process.env.NEXT_PUBLIC_* in Next.js |

Security checklist

• SERVICE_NAME, CONFIG_API_URL, and secrets → server env only (no NEXT_PUBLIC_ prefix).
• NEXT_PUBLIC_* → .env.local only; read with process.env in Client Components.
• Add import "server-only" to config.server.ts.

Example app

Ships inside the npm package at:

node_modules/@caregenix/dbconfigmanager/examples/nextjs-app

cd node_modules/@caregenix/dbconfigmanager/examples/nextjs-app
cp .env.example .env.local
# set SERVICE_NAME, CONFIG_API_URL, NEXT_PUBLIC_API_BASE
npm install
npm run dev

See examples/nextjs-app/README.md in the package.

Publish to npm

See PUBLISHING.md.

License

MIT — aligned with dbconfigmanager on PyPI.