react-native-config-ultimate 0.0.1

package/src/load-env.spec.ts

@@ -0,0 +1,163 @@
+const mockReadFileSync = jest.fn();
+jest.doMock('fs', () => ({ readFileSync: mockReadFileSync }));
+
+const mockParse = jest.fn();
+jest.doMock('dotenv', () => ({ parse: mockParse }));
+
+const mockExpand = jest.fn();
+jest.doMock('dotenv-expand', () => ({ expand: mockExpand }));
+
+const mockYaml = jest.fn();
+jest.doMock('js-yaml', () => ({ load: mockYaml }));
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const load_env: (paths: string | string[]) => Record<string, unknown> =
+  require('./load-env').default;
+
+describe('load-env', () => {
+  beforeEach(() => {
+    mockReadFileSync.mockReset();
+    mockParse.mockReset();
+    mockExpand.mockReset();
+    mockYaml.mockReset();
+    // Default expand: return parsed as-is (no expansion side effects)
+    mockExpand.mockImplementation(
+      (input: { parsed: Record<string, string> }) => input
+    );
+  });
+
+  describe('dotenv format', () => {
+    it('reads a single dotenv file (backward-compatible string arg)', () => {
+      mockReadFileSync.mockReturnValueOnce('hello=world');
+      mockParse.mockReturnValueOnce({ hello: 'world' });
+      const result = load_env('hello');
+      expect(mockReadFileSync).toHaveBeenCalledWith('hello', 'utf8');
+      expect(mockParse).toHaveBeenCalledWith('hello=world');
+      expect(result).toEqual({ hello: 'world' });
+    });
+
+    it('reads a single dotenv file when passed as an array', () => {
+      mockReadFileSync.mockReturnValueOnce('hello=world');
+      mockParse.mockReturnValueOnce({ hello: 'world' });
+      const result = load_env(['hello']);
+      expect(mockReadFileSync).toHaveBeenCalledWith('hello', 'utf8');
+      expect(result).toEqual({ hello: 'world' });
+    });
+
+    it('merges multiple dotenv files, last file wins for conflicts', () => {
+      mockReadFileSync
+        .mockReturnValueOnce('A=base\nB=base')
+        .mockReturnValueOnce('B=override\nC=new');
+      mockParse
+        .mockReturnValueOnce({ A: 'base', B: 'base' })
+        .mockReturnValueOnce({ B: 'override', C: 'new' });
+      const result = load_env(['.env.base', '.env.staging']);
+      expect(mockReadFileSync).toHaveBeenCalledTimes(2);
+      // expand is called once with the merged raw object
+      expect(mockExpand).toHaveBeenCalledWith({
+        parsed: { A: 'base', B: 'override', C: 'new' },
+      });
+      expect(result).toEqual({ A: 'base', B: 'override', C: 'new' });
+    });
+
+    it('expands $VAR references using dotenv-expand', () => {
+      mockReadFileSync.mockReturnValueOnce('BASE=https://api.com\nURL=$BASE/v1');
+      mockParse.mockReturnValueOnce({ BASE: 'https://api.com', URL: '$BASE/v1' });
+      mockExpand.mockReturnValueOnce({
+        parsed: { BASE: 'https://api.com', URL: 'https://api.com/v1' },
+      });
+      const result = load_env('.env');
+      expect(result).toEqual({
+        BASE: 'https://api.com',
+        URL: 'https://api.com/v1',
+      });
+    });
+
+    it('expands cross-file $VAR references when merging multiple files', () => {
+      mockReadFileSync
+        .mockReturnValueOnce('BASE_URL=https://api.com')
+        .mockReturnValueOnce('API_URL=$BASE_URL/v1');
+      mockParse
+        .mockReturnValueOnce({ BASE_URL: 'https://api.com' })
+        .mockReturnValueOnce({ API_URL: '$BASE_URL/v1' });
+      // Expand is called with merged raw — so cross-file reference resolves
+      mockExpand.mockReturnValueOnce({
+        parsed: {
+          BASE_URL: 'https://api.com',
+          API_URL: 'https://api.com/v1',
+        },
+      });
+      const result = load_env(['.env.base', '.env.staging']);
+      expect(mockExpand).toHaveBeenCalledWith({
+        parsed: { BASE_URL: 'https://api.com', API_URL: '$BASE_URL/v1' },
+      });
+      expect(result).toEqual({
+        BASE_URL: 'https://api.com',
+        API_URL: 'https://api.com/v1',
+      });
+    });
+  });
+
+  describe('yaml format', () => {
+    it.each`
+      extension
+      ${'yml'}
+      ${'yaml'}
+    `(
+      "reads yaml when extension is '.$extension'",
+      ({ extension }: { extension: string }) => {
+        mockReadFileSync.mockReturnValueOnce(Buffer.from('data'));
+        mockYaml.mockReturnValueOnce({ hello: 'world' });
+        const result = load_env(`hello.${extension}`);
+        expect(mockReadFileSync).toHaveBeenCalledWith(`hello.${extension}`);
+        expect(mockYaml).toHaveBeenCalledWith('data');
+        expect(result).toEqual({ hello: 'world' });
+      }
+    );
+
+    it('merges multiple yaml files, last file wins for conflicts', () => {
+      mockReadFileSync
+        .mockReturnValueOnce(Buffer.from('A: base\nB: base'))
+        .mockReturnValueOnce(Buffer.from('B: override\nC: new'));
+      mockYaml
+        .mockReturnValueOnce({ A: 'base', B: 'base' })
+        .mockReturnValueOnce({ B: 'override', C: 'new' });
+      const result = load_env(['base.yaml', 'staging.yaml']);
+      expect(mockReadFileSync).toHaveBeenCalledTimes(2);
+      expect(result).toEqual({ A: 'base', B: 'override', C: 'new' });
+    });
+
+    describe.each`
+      extension
+      ${'yml'}
+      ${'yaml'}
+    `(
+      "throws when yaml is not an object with extension '.$extension'",
+      ({ extension }: { extension: string }) => {
+        it.each`
+          content
+          ${'abc:def'}
+          ${false}
+          ${true}
+          ${42}
+          ${null}
+          ${undefined}
+        `("when content is '$content'", ({ content }: { content: unknown }) => {
+          mockReadFileSync.mockReturnValueOnce(Buffer.from('data'));
+          mockYaml.mockReturnValueOnce(content);
+          expect(() => {
+            load_env(`hello.${extension}`);
+          }).toThrow();
+        });
+      }
+    );
+  });
+
+  describe('edge cases', () => {
+    it('throws when no files are provided', () => {
+      expect(() => load_env([])).toThrow(
+        'No env file specified'
+      );
+    });
+  });
+});

package/src/load-env.ts

@@ -0,0 +1,84 @@
+import * as dotenv from 'dotenv';
+import { expand } from 'dotenv-expand';
+import * as yaml from 'js-yaml';
+import * as path from 'path';
+import * as fs from 'fs';
+
+import type { EnvData } from './resolve-env';
+
+type FileFormat = 'dotenv' | 'yaml';
+
+function detect_format(config_path: string): FileFormat {
+  const { ext } = path.parse(config_path);
+  return ext === '.yml' || ext === '.yaml' ? 'yaml' : 'dotenv';
+}
+
+function read_yaml(config_path: string): EnvData {
+  const data = yaml.load(fs.readFileSync(config_path).toString());
+  if (typeof data === 'undefined' || data === null || typeof data !== 'object') {
+    throw new Error(
+      `Expected to read object from ${config_path}, but got '${data}'`
+    );
+  }
+  return data as EnvData;
+}
+
+/**
+ * Load one or more env files and merge them (last file wins for conflicting keys).
+ *
+ * Dotenv files (.env, .env.staging, etc.):
+ *   - All files are merged first, then variable expansion runs once.
+ *   - This means cross-file `$VAR` references work:
+ *     .env.base:    BASE_URL=https://api.example.com
+ *     .env.staging: API_URL=$BASE_URL/v1  →  https://api.example.com/v1
+ *
+ * YAML files (.yml, .yaml):
+ *   - Each file is loaded and shallow-merged (last wins for top-level keys).
+ *   - No variable expansion is applied (use YAML anchors instead).
+ *
+ * @example
+ * // Single file (backward-compatible):
+ * load_env('.env')
+ *
+ * // Multi-file merge:
+ * load_env(['.env.base', '.env.staging'])
+ */
+export default function load_env(config_paths: string | string[]): EnvData {
+  const paths = Array.isArray(config_paths) ? config_paths : [config_paths];
+
+  if (paths.length === 0) {
+    throw new Error(
+      'No env file specified. Usage: rncu <env-file> [env-file2 ...]'
+    );
+  }
+
+  const formats = paths.map(detect_format);
+  const allDotenv = formats.every((f) => f === 'dotenv');
+
+  if (allDotenv) {
+    // Merge raw parsed content first, then expand once —
+    // so cross-file $VAR references resolve correctly.
+    const raw: Record<string, string> = {};
+    for (const p of paths) {
+      const content = fs.readFileSync(p, 'utf8');
+      Object.assign(raw, dotenv.parse(content));
+    }
+    const result = expand({ parsed: raw });
+    return (result.parsed ?? raw) as EnvData;
+  }
+
+  // YAML or mixed: load each file individually and shallow-merge.
+  const merged: EnvData = {};
+  for (let i = 0; i < paths.length; i++) {
+    const p = paths[i];
+    if (formats[i] === 'yaml') {
+      Object.assign(merged, read_yaml(p));
+    } else {
+      const content = fs.readFileSync(p, 'utf8');
+      const parsed = dotenv.parse(content);
+      const expanded = expand({ parsed });
+      Object.assign(merged, expanded.parsed ?? parsed);
+    }
+  }
+  return merged;
+}

package/src/main.js

@@ -0,0 +1,34 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = main;
+const load_env_1 = __importDefault(require("./load-env"));
+const render_env_1 = __importDefault(require("./render-env"));
+const write_env_1 = __importDefault(require("./write-env"));
+const flatten_1 = __importDefault(require("./flatten"));
+const resolve_env_1 = __importDefault(require("./resolve-env"));
+const validate_env_1 = require("./validate-env");
+/**
+ * Main build-time pipeline:
+ *   load → resolve (on_env hook) → validate (schema) → flatten → render → write
+ *
+ * @param project_root  Root of the React Native project
+ * @param lib_root      Root of the react-native-config-ultimate install
+ * @param env_file      Path(s) to env file(s). Multiple files are merged (last wins).
+ * @param rc            Optional RC config from `.rncurc.js`
+ */
+async function main(project_root, lib_root, env_file, rc) {
+    const env = await (0, resolve_env_1.default)((0, load_env_1.default)(env_file), rc);
+    if (rc === null || rc === void 0 ? void 0 : rc.schema) {
+        (0, validate_env_1.validate_env)(env, rc.schema);
+    }
+    const flat = {
+        ios: (0, flatten_1.default)(env, 'ios'),
+        android: (0, flatten_1.default)(env, 'android'),
+        web: (0, flatten_1.default)(env, 'web'),
+    };
+    const files_to_write = (0, render_env_1.default)(project_root, lib_root, flat, rc);
+    (0, write_env_1.default)(files_to_write);
+}

package/src/main.spec.ts

@@ -0,0 +1,171 @@
+const mock_load_env = jest.fn();
+jest.doMock('./load-env', () => ({ __esModule: true, default: mock_load_env }));
+const mock_render_env = jest.fn();
+jest.doMock('./render-env', () => ({ __esModule: true, default: mock_render_env }));
+const mock_write_env = jest.fn();
+jest.doMock('./write-env', () => ({ __esModule: true, default: mock_write_env }));
+const mock_flatten = jest.fn();
+jest.doMock('./flatten', () => ({ __esModule: true, default: mock_flatten }));
+const mock_validate_env = jest.fn();
+jest.doMock('./validate-env', () => ({ validate_env: mock_validate_env }));
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const main: (...args: unknown[]) => Promise<void> = require('./main').default;
+
+
+export const files_to_assert = [
+  'ios/rncu.xcconfig',
+  'node_modules/react-native-config-ultimate/ios/ConfigValues.h',
+  'node_modules/react-native-config-ultimate/android/rncu.yaml',
+  'node_modules/react-native-config-ultimate/index.d.ts',
+  'node_modules/react-native-config-ultimate/index.web.js',
+  'node_modules/react-native-config-ultimate/override.js',
+];
+
+describe('main', () => {
+  beforeEach(() => {
+    mock_load_env.mockReset();
+    mock_render_env.mockReset();
+    mock_write_env.mockReset();
+    mock_flatten.mockReset();
+    mock_validate_env.mockReset();
+  });
+
+  it('execute render with paths (string arg — backward-compatible)', async () => {
+    mock_load_env.mockReturnValueOnce({ data: true });
+    mock_flatten.mockReturnValueOnce({ data: true, ios: true });
+    mock_flatten.mockReturnValueOnce({ data: true, android: true });
+    mock_flatten.mockReturnValueOnce({ data: true, web: true });
+    mock_render_env.mockReturnValueOnce({ hello: 'world' });
+    await main(
+      'project',
+      'project/node_modules/react-native-config-ultimate',
+      'file'
+    );
+    expect(mock_load_env).toHaveBeenCalledWith('file');
+    expect(mock_flatten).toHaveBeenCalledWith({ data: true }, 'ios');
+    expect(mock_flatten).toHaveBeenCalledWith({ data: true }, 'android');
+    expect(mock_flatten).toHaveBeenCalledWith({ data: true }, 'web');
+    expect(mock_render_env).toHaveBeenCalledWith(
+      'project',
+      'project/node_modules/react-native-config-ultimate',
+      {
+        ios: { data: true, ios: true },
+        android: { data: true, android: true },
+        web: { data: true, web: true },
+      },
+      undefined
+    );
+    expect(mock_write_env).toHaveBeenCalledWith({ hello: 'world' });
+  });
+
+  it('passes array of env files to load_env (multi-file merge)', async () => {
+    mock_load_env.mockReturnValueOnce({ data: true });
+    mock_flatten.mockReturnValue({});
+    mock_render_env.mockReturnValueOnce({});
+    await main(
+      'project',
+      'project/node_modules/react-native-config-ultimate',
+      ['.env.base', '.env.staging']
+    );
+    expect(mock_load_env).toHaveBeenCalledWith(['.env.base', '.env.staging']);
+  });
+  describe('rc.on_env', () => {
+    it('invoke rc hook with config before flattening', async () => {
+      const on_env = jest.fn();
+      mock_load_env.mockReturnValueOnce({ data: true });
+      await main(
+        'project',
+        'project/node_modules/react-native-config-ultimate',
+        'file',
+        { on_env }
+      );
+      expect(on_env).toHaveBeenCalledWith({ data: true });
+      expect(mock_flatten).toHaveBeenCalledWith({ data: true }, 'ios');
+      expect(mock_flatten).toHaveBeenCalledWith({ data: true }, 'android');
+      expect(mock_flatten).toHaveBeenCalledWith({ data: true }, 'web');
+    });
+    it('hook can add or remove values', async () => {
+      const on_env = jest.fn();
+      on_env.mockImplementation((env: Record<string, unknown>) => {
+        const { key1, ...rest } = env;
+        void key1;
+        return { ...rest, key2: 'hello' };
+      });
+      mock_load_env.mockReturnValueOnce({ data: true, key1: 'bye' });
+      await main(
+        'project',
+        'project/node_modules/react-native-config-ultimate',
+        'file',
+        { on_env }
+      );
+      expect(on_env).toHaveBeenCalledWith({ data: true, key1: 'bye' });
+      expect(mock_flatten).toHaveBeenCalledWith({ data: true, key2: 'hello' }, 'ios');
+      expect(mock_flatten).toHaveBeenCalledWith({ data: true, key2: 'hello' }, 'android');
+      expect(mock_flatten).toHaveBeenCalledWith({ data: true, key2: 'hello' }, 'web');
+    });
+  });
+
+  describe('rc.schema', () => {
+    it('calls validate_env when schema is provided', async () => {
+      const schema = { API_KEY: { type: 'string' as const, required: true } };
+      mock_load_env.mockReturnValueOnce({ API_KEY: 'secret' });
+      mock_flatten.mockReturnValue({});
+      mock_render_env.mockReturnValueOnce({});
+      await main(
+        'project',
+        'project/node_modules/react-native-config-ultimate',
+        'file',
+        { schema }
+      );
+      expect(mock_validate_env).toHaveBeenCalledWith({ API_KEY: 'secret' }, schema);
+    });
+
+    it('does not call validate_env when no schema is provided', async () => {
+      mock_load_env.mockReturnValueOnce({ data: true });
+      mock_flatten.mockReturnValue({});
+      mock_render_env.mockReturnValueOnce({});
+      await main(
+        'project',
+        'project/node_modules/react-native-config-ultimate',
+        'file'
+      );
+      expect(mock_validate_env).not.toHaveBeenCalled();
+    });
+
+    it('validates env AFTER on_env hook runs (hook output is validated)', async () => {
+      const schema = { INJECTED_KEY: { type: 'string' as const, required: true } };
+      const on_env = jest.fn().mockReturnValue({ INJECTED_KEY: 'from-hook' });
+      mock_load_env.mockReturnValueOnce({});
+      mock_flatten.mockReturnValue({});
+      mock_render_env.mockReturnValueOnce({});
+      await main(
+        'project',
+        'project/node_modules/react-native-config-ultimate',
+        'file',
+        { on_env, schema }
+      );
+      // validate_env receives the HOOK output, not the raw env
+      expect(mock_validate_env).toHaveBeenCalledWith(
+        { INJECTED_KEY: 'from-hook' },
+        schema
+      );
+    });
+
+    it('propagates validation error thrown by validate_env', async () => {
+      const schema = { API_KEY: { type: 'string' as const, required: true } };
+      mock_load_env.mockReturnValueOnce({});
+      mock_validate_env.mockImplementation(() => {
+        throw new Error('❌ validation failed: Missing required env var: API_KEY');
+      });
+      await expect(
+        main(
+          'project',
+          'project/node_modules/react-native-config-ultimate',
+          'file',
+          { schema }
+        )
+      ).rejects.toThrow('Missing required env var: API_KEY');
+    });
+  });
+});

package/src/main.ts

@@ -0,0 +1,39 @@
+import load_env from './load-env';
+import render_env from './render-env';
+import write_env from './write-env';
+import flatten from './flatten';
+import resolve_env from './resolve-env';
+import { validate_env } from './validate-env';
+
+import type { RC, EnvData } from './resolve-env';
+import type { EnvConfig } from './flatten';
+
+/**
+ * Main build-time pipeline:
+ *   load → resolve (on_env hook) → validate (schema) → flatten → render → write
+ *
+ * @param project_root  Root of the React Native project
+ * @param lib_root      Root of the react-native-config-ultimate install
+ * @param env_file      Path(s) to env file(s). Multiple files are merged (last wins).
+ * @param rc            Optional RC config from `.rncurc.js`
+ */
+export default async function main(
+  project_root: string,
+  lib_root: string,
+  env_file: string | string[],
+  rc?: RC
+): Promise<void> {
+  const env: EnvData = await resolve_env(load_env(env_file), rc);
+
+  if (rc?.schema) {
+    validate_env(env, rc.schema);
+  }
+
+  const flat = {
+    ios: flatten(env as EnvConfig, 'ios'),
+    android: flatten(env as EnvConfig, 'android'),
+    web: flatten(env as EnvConfig, 'web'),
+  };
+  const files_to_write = render_env(project_root, lib_root, flat, rc);
+  write_env(files_to_write);
+}

package/src/render-env.js

@@ -0,0 +1,110 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = render_env;
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const handlebars_1 = __importDefault(require("handlebars"));
+const code_file_name = 'ConfigValues';
+const config_file_name = 'rncu';
+// ─── Handlebars helpers (registered once at module load, not per-call) ────────
+function is_string(value) {
+    return typeof value === 'string';
+}
+function is_number(value) {
+    return typeof value === 'number';
+}
+function is_boolean(value) {
+    return typeof value === 'boolean';
+}
+function escape(value) {
+    if (is_string(value)) {
+        return value.replace(/"/gm, '\\"');
+    }
+    return value;
+}
+function xcconfig_format(value) {
+    if (is_string(value)) {
+        return value.replace(/\/\//gm, '/$()/');
+    }
+    return value;
+}
+function to_json(value) {
+    return JSON.stringify(value, null, 2);
+}
+handlebars_1.default.registerHelper('isBoolean', is_boolean);
+handlebars_1.default.registerHelper('isString', is_string);
+handlebars_1.default.registerHelper('isNumber', is_number);
+handlebars_1.default.registerHelper('escape', escape);
+handlebars_1.default.registerHelper('xcconfigFormat', xcconfig_format);
+handlebars_1.default.registerHelper('toJSON', to_json);
+// ─── Template cache (compiled once per template name, not per build) ──────────
+const template_cache = new Map();
+function get_compiled_template(template_name) {
+    const cached = template_cache.get(template_name);
+    if (cached)
+        return cached;
+    const template_path = path.join(__dirname, 'templates', `${template_name}.handlebars`);
+    const compiled = handlebars_1.default.compile(fs.readFileSync(template_path, 'utf8'));
+    template_cache.set(template_name, compiled);
+    return compiled;
+}
+function render_template(template_name, data) {
+    return get_compiled_template(template_name)(data);
+}
+function render_env(project_root, lib_root, env, rc) {
+    const { ios, android, web } = env;
+    const map = {
+        [path.join(lib_root, 'index.d.ts')]: render_template('index.d.ts', ios),
+        [path.join(lib_root, 'index.web.js')]: render_template('index.web.js', web),
+        [path.join(lib_root, 'ios', `${code_file_name}.h`)]: render_template('ConfigValues.h', ios),
+        [path.join(lib_root, 'android', 'rncu.yaml')]: render_template('rncu.yaml', android),
+    };
+    // Only write xcconfig if the project has an ios folder.
+    // All RN apps have it; some react-native-web apps may not.
+    if (fs.existsSync(path.join(project_root, 'ios'))) {
+        map[path.join(project_root, 'ios', `${config_file_name}.xcconfig`)] =
+            render_template('rncu.xcconfig', ios);
+    }
+    const js_override = rc && typeof rc.js_override === 'boolean' && rc.js_override;
+    map[path.join(lib_root, 'override.js')] = render_template('override.js', {
+        ios: js_override ? ios : {},
+        android: js_override ? android : {},
+    });
+    return map;
+}