monorepo-config 0.0.1

package/README.md

@@ -0,0 +1,71 @@
+# monorepo-config
+
+Javascript package to help with managing configs, primarily for monorepos. Uses zod to validate.
+
+## Basic usage
+
+```ts
+import { makeConfig, setConfig } from "monorepo-config";
+
+export const CONFIG = makeConfig(z.object({
+  foobar: z.string(),
+}));
+
+setConfig(CONFIG, { foobar: 'test' });
+
+CONFIG.foobar // --> 'test';
+```
+
+Basic functionality is not much more than running `.parse` on your schema, some error reporting and being a bit smart regarding defaults. You can only `setConfig` once, otherwise use `forceOverrideConfig`.
+
+
+## File-based usage
+
+This is more interesting, and allows you to replace the mess of untyped, unchecked env vars across packages with something more manageable (inspired by [Django](https://docs.djangoproject.com/en/6.0/topics/settings/)).
+
+Create a directory `src/configs`. Then create a file `src/configs/schema.ts`:
+
+```ts
+import { makeFileConfig } from "monorepo-config";
+
+export const FOO_CONFIG = makeFileConfig({
+  envVar: 'FOO_CONFIG',
+  directory: import.meta.dirname,
+  schema: z.object({
+    foo: z.string()
+  })
+});
+```
+
+For simplicity, the name of the environment variable and the config object are the same. Now you can define "profiles" in the same directory, like `src/configs/production.ts`:
+
+```ts
+import { setConfig } from "monorepo-config";
+import { FOO_CONFIG } from "./schema.js";
+
+setConfig(FOO_CONFIG, {
+  foo: 'bar'
+});
+```
+
+Lastly, load the config file based on the environment variable `FOO_CONFIG` in a file `src/configs/config.ts` (or some other file that initializes global variables):
+
+```ts
+import { loadFileIntoConfig } from "monorepo-config";
+import { FOO_CONFIG } from "./schema.js";
+
+await loadFileIntoConfig(FOO_CONFIG);
+```
+
+The idea is to use the same environment variable for all packages in your monorepo (this mirrors `DJANGO_SETTINGS_MODULE`).
+
+
+## Which to use?
+
+You can mix both in your monorepo! Packages representing reusable libraries probably want to stick with the basic usage. Packages that represent apps probably want to define their own config in a file-based manner. In such cases, you are expected to do multiple `setConfig` calls in a "profile": one for the app itself and then multiple `setConfig` calls for the internal libraries the app uses.
+
+
+## TODO
+
+- [ ] Vite plugin
+- [ ] Explore usage in tests

package/__test__/foo.js

@@ -0,0 +1,11 @@
+import { setConfig } from "../dist/index.js";
+import { FOO_CONFIG } from "./schema.js";
+import { BAR_CONFIG } from "./schema2.js";
+
+setConfig(FOO_CONFIG, {
+  foo: 'foooo'
+});
+
+setConfig(BAR_CONFIG, {
+  bar: 'baaaar'
+});

package/__test__/schema.js

@@ -0,0 +1,12 @@
+
+import z from "zod";
+import { makeFileConfig } from "../dist/filebased.js";
+
+export const FOO_CONFIG = makeFileConfig({
+  envVar: 'FOO_CONFIG',
+  directory: import.meta.dirname,
+  schema: z.object({
+    foo: z.string()
+  })
+});
+

package/__test__/schema2.js

@@ -0,0 +1,11 @@
+
+import z from "zod";
+import { makeConfig } from "../dist/index.js";
+
+export const BAR_CONFIG = makeConfig(z.object({
+  bar: z.string().default('this is default'),
+  optionalBar: z.string().optional(),
+}));
+
+console.assert(BAR_CONFIG.bar === 'this is default', 'bar default');
+console.assert(BAR_CONFIG.optionalBar === undefined, 'bar optional');

package/__test__/test.js

@@ -0,0 +1,23 @@
+
+import { loadFileIntoConfig } from "../dist/filebased.js";
+import { ConfigError, setConfig } from "../dist/index.js";
+import { FOO_CONFIG } from "./schema.js";
+import { BAR_CONFIG } from "./schema2.js";
+
+await loadFileIntoConfig(FOO_CONFIG);
+
+console.assert(FOO_CONFIG.foo === 'foooo', 'foo');
+console.assert(BAR_CONFIG.bar === 'baaaar', 'bar');
+
+let hadError = false;
+try {
+  setConfig(FOO_CONFIG, {
+    foo: 'boo'
+  });
+} catch (e) {
+  hadError = true;
+  console.assert(e instanceof ConfigError, `error correct type: ${e}`);
+}
+console.assert(hadError, 'had error');
+
+console.log("no failures? everything is ok!");

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "monorepo-config",
+  "version": "0.0.1",
+  "description": "Managed and validated configs across packages (no deps, but bring your own zod)",
+  "main": "./dist/index.js",
+  "type": "module",
+  "keywords": [],
+  "author": "Evert Heylen",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "typescript": "^5.9.3",
+    "zod": "^4.3.5"
+  },
+  "exports": {
+    "./*": "./dist/*"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "test": "vitest run"
+  }
+}

package/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+onlyBuiltDependencies:
+  - esbuild

package/src/basic.ts

@@ -0,0 +1,67 @@
+import type { ZodObject, input, output } from "zod";
+
+export class ConfigError extends Error { }
+
+export type Config<ConfigSchema extends ZodObject> = {
+  _meta: {
+    isUsable: boolean,
+    canSet: boolean,
+    schema: ConfigSchema,
+  }
+} & output<ConfigSchema>;
+
+function wrapInProxy<ConfigSchema extends ZodObject>(obj: Config<ConfigSchema>) {
+  return new Proxy(obj, {
+    get(target, prop, receiver) {
+      if (prop === '_meta') {
+        return target._meta;
+      }
+      if (!target._meta.isUsable) {
+        throw new Error("Tried to access config but it is not usable yet. Did you forget to set or load the config?");
+      }
+      return (target as any)[prop];
+    }
+  });
+}
+
+export function makeConfig<ConfigSchema extends ZodObject>(schema: ConfigSchema): Config<ConfigSchema> {
+  const zodDefaults = schema.safeParse({});
+
+  if (zodDefaults.success) {
+    // all attributes had defaults
+    return wrapInProxy({
+      _meta: {
+        schema: schema,
+        isUsable: true,
+        canSet: true,
+      },
+      ...zodDefaults.data
+    });
+  } else {
+    // zod couldn't handle an empty object
+    // @ts-expect-error for simplicity, the types assume that config is always defined.
+    return wrapInProxy({
+      _meta: {
+        schema: schema,
+        isUsable: false,
+        canSet: true,
+      }
+    });
+  }
+}
+
+export function forceOverrideConfig<ConfigSchema extends ZodObject>(config: Config<ConfigSchema>, inputData: input<ConfigSchema>) {
+  const outputData = config._meta.schema.parse(inputData);
+  Object.assign(config, outputData);
+  config._meta.isUsable = true;
+  config._meta.canSet = false;
+}
+
+export function setConfig<ConfigSchema extends ZodObject>(config: Config<ConfigSchema>, inputData: input<ConfigSchema>) {
+  if (config._meta.canSet) {
+    forceOverrideConfig(config, inputData);
+  } else {
+    throw new ConfigError("Can't override config as it is already set");
+  }
+}
+

package/src/filebased.ts

@@ -0,0 +1,45 @@
+import type { ZodObject } from "zod";
+import { Config, ConfigError, makeConfig } from "./basic.js";
+import { join } from "path";
+
+export type FileConfig<ConfigSchema extends ZodObject> = Config<ConfigSchema> & {
+  _meta: {
+    configDir: string;
+    envVar: string;
+  }
+};
+
+export function makeFileConfig<ConfigSchema extends ZodObject>(opts: {
+  envVar: string, directory: string, schema: ConfigSchema, preventAutoLoad?: boolean
+}): FileConfig<ConfigSchema> {
+  const cfg = makeConfig(opts.schema) as FileConfig<ConfigSchema>;
+  // imperative overrides here to not lose the Proxy
+  cfg._meta.configDir = opts.directory;
+  cfg._meta.envVar = opts.envVar;
+
+  if (!opts.preventAutoLoad) {
+    queueMicrotask(async () => {
+      try {
+        await loadFileIntoConfig(cfg);
+      } catch (e) {
+        console.error(e);
+        process.exit(1);
+      }
+    });
+  }
+
+  return cfg;
+}
+
+export async function loadFileIntoConfig<ConfigSchema extends ZodObject>(config: FileConfig<ConfigSchema>) {
+  const config_name = process.env[config._meta.envVar];
+  if (config_name === undefined) {
+    throw new ConfigError(`Please set the environment variable ${config._meta.envVar}`);
+  }
+  const path = join(config._meta.configDir, `${config_name}.js`);
+  await import(path);
+  if (!config._meta.isUsable) {
+    console.warn(`Imported ${path} but config was still not marked as usable`);
+  }
+}
+

package/src/index.ts

@@ -0,0 +1,2 @@
+export { makeConfig, forceOverrideConfig, setConfig } from "./basic.js";
+export { makeFileConfig, loadFileIntoConfig } from "./filebased.js";

package/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "lib": [
+      "es2024",
+      "ESNext.Array",
+      "ESNext.Collection",
+      "ESNext.Iterator",
+      "ESNext.Promise"
+    ],
+    "module": "nodenext",
+    "target": "es2024",
+
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "moduleResolution": "node16",
+
+    "declaration": true,
+    "sourceMap": true,
+    "declarationMap": true,
+    
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*", "__test__"],
+  "exclude": ["node_modules", "dist"]
+}