Decouple Obsidian from React

packages/react-obsidian/package.json

@@ -21,7 +21,12 @@
     "hoist-non-react-statics": "3.x.x"
   },
   "peerDependencies": {
-    "react": "*"
+    "react": ">=16.8.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@babel/core": "7.26.10",

packages/react-obsidian/src/index.ts

@@ -6,6 +6,7 @@ import { lifecycleBound } from './decorators/LifecycleBound';
 import { provides } from './decorators/provides/Provides';
 import { singleton } from './decorators/singleton/Singleton';
 import _Obsidian from './Obsidian';
+import { isReactAvailable, createReactRequiredError, createReactRequiredClass } from './utils/reactAvailability';
 
 export * from './types';
 
@@ -50,19 +51,57 @@ export const LateInject = lateInject;
  */
 export const LifecycleBound = lifecycleBound;
 
-
 export const Obsidian = new _Obsidian();
 
-export { injectComponent } from './injectors/components/InjectComponent';
-export { injectHook, injectHookWithArguments } from './injectors/hooks/InjectHook';
-
-export { useObserver } from './observable/useObserver';
-export { useObservers } from './observable/useObservers';
 export { Observable } from './observable/Observable';
 export { MediatorObservable } from './observable/mediator/MediatorObservable';
 export { OnNext, Unsubscribe } from './observable/types';
 
-export { Model } from './model/Model';
+export { mockGraphs } from '../testkit/mockGraphs';
+
+// ============================================================================
+// React-dependent exports (conditionally loaded)
+// ============================================================================
+const reactAvailable = isReactAvailable();
+
+import type { injectComponent as injectComponentType } from './injectors/components/InjectComponent';
+import type {
+  injectHook as injectHookType,
+  injectHookWithArguments as injectHookWithArgumentsType,
+} from './injectors/hooks/InjectHook';
+import type { useObserver as useObserverType } from './observable/useObserver';
+import type { useObservers as useObserversType } from './observable/useObservers';
+import type { Model as ModelType } from './model/Model';
+import type { mockModel as mockModelType } from '../testkit/index';
+
+export const injectComponent: typeof injectComponentType = reactAvailable
+  ? require('./injectors/components/InjectComponent').injectComponent
+  : createReactRequiredError('injectComponent');
+
+export const injectHook: typeof injectHookType = reactAvailable
+  ? require('./injectors/hooks/InjectHook').injectHook
+  : createReactRequiredError('injectHook');
+
+export const injectHookWithArguments: typeof injectHookWithArgumentsType = reactAvailable
+? require('./injectors/hooks/InjectHook').injectHookWithArguments
+  : createReactRequiredError('injectHookWithArguments');
+
+export const useObserver: typeof useObserverType = reactAvailable
+  ? require('./observable/useObserver').useObserver
+  : createReactRequiredError('useObserver');
+
+export const useObservers: typeof useObserversType = reactAvailable
+  ? require('./observable/useObservers').useObservers
+  : createReactRequiredError('useObservers');
+
+export const Model: typeof ModelType = reactAvailable
+  ? require('./model/Model').Model
+  : createReactRequiredClass('Model');
+
+export const testKit = reactAvailable
+  ? require('../testkit/index').testKit
+  : createReactRequiredError('testKit');
 
-export { testKit } from '../testkit';
-export { mockModel, mockGraphs } from '../testkit/index';
+export const mockModel: typeof mockModelType = reactAvailable
+  ? require('../testkit/index').mockModel
+  : createReactRequiredError('mockModel');

packages/react-obsidian/src/utils/reactAvailability.ts

@@ -0,0 +1,45 @@
+let reactAvailableCache: boolean | undefined;
+
+export function isReactAvailable(): boolean {
+  if (reactAvailableCache !== undefined) {
+    return reactAvailableCache;
+  }
+
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, global-require
+    require('react');
+    reactAvailableCache = true;
+  } catch {
+    reactAvailableCache = false;
+  }
+
+  return reactAvailableCache;
+}
+
+/**
+ * Creates a function that throws an error when called if React is not available.
+ * Used to provide helpful error messages for React-dependent features.
+ */
+export function createReactRequiredError<T = any>(featureName: string): T {
+  return function reactRequiredStub(..._args: any[]) {
+    throw new Error(
+      `${featureName} requires React to be installed. `
+      + `Please install React: npm install react`,
+    );
+  } as T;
+}
+
+/**
+ * Creates a class constructor that throws an error when instantiated if React is not available.
+ * Used for features like Model that need to be constructable.
+ */
+export function createReactRequiredClass<T = any>(className: string): T {
+  return class ReactRequiredStub {
+    constructor() {
+      throw new Error(
+        `${className} requires React to be installed. `
+        + `Please install React: npm install react`,
+      );
+    }
+  } as T;
+}

packages/react-obsidian/test/integration/noReact.test.ts

@@ -0,0 +1,151 @@
+/**
+ * Integration test to verify Obsidian works without React.
+ */
+describe('Obsidian without React (Jest)', () => {
+  beforeEach(() => {
+    // Clear module cache before each test
+    jest.resetModules();
+
+    // Mock React to throw an error as if it's not installed
+    jest.mock('react', () => {
+      throw new Error("Cannot find module 'react'");
+    });
+  });
+
+  afterEach(() => {
+    jest.unmock('react');
+  });
+
+  it('exports core DI functionality without React', () => {
+    jest.isolateModules(() => {
+      // Import in isolation to get a fresh instance without React
+      const {
+        Obsidian,
+        ObjectGraph,
+        Observable,
+        graph,
+        injectable,
+        inject,
+        singleton,
+        mockGraphs,
+      } = require('../../src/index');
+
+      // Core exports should work
+      expect(Obsidian).toBeDefined();
+      expect(typeof Obsidian.registerGraph).toBe('function');
+      expect(typeof Obsidian.obtain).toBe('function');
+
+      expect(ObjectGraph).toBeDefined();
+      expect(Observable).toBeDefined();
+
+      expect(typeof graph).toBe('function');
+      expect(typeof injectable).toBe('function');
+      expect(typeof inject).toBe('function');
+      expect(typeof singleton).toBe('function');
+
+      expect(typeof mockGraphs).toBe('function');
+    });
+  });
+
+  it('Observable works without React', () => {
+    jest.isolateModules(() => {
+      const { Observable } = require('../../src/index');
+
+      const obs = new Observable(42);
+      expect(obs.value).toBe(42);
+
+      let notifiedValue: number | undefined;
+      const unsubscribe = obs.subscribe((value: number) => {
+        notifiedValue = value;
+      });
+
+      obs.value = 100;
+      expect(notifiedValue).toBe(100);
+
+      unsubscribe();
+    });
+  });
+
+  it('can create and use dependency graphs without React', () => {
+    jest.isolateModules(() => {
+      const { Obsidian, ObjectGraph } = require('../../src/index');
+
+      class TestService {
+        getValue() {
+          return 'test-value';
+        }
+      }
+
+      class TestGraph extends ObjectGraph {
+        testService = new TestService();
+      }
+
+      Obsidian.registerGraph('test-no-react', () => TestGraph);
+      const serviceLocator = Obsidian.obtain('test-no-react');
+
+      expect(serviceLocator).toBeDefined();
+      expect(serviceLocator.testService).toBeDefined();
+    });
+  });
+
+  it('mockGraphs is available without React', () => {
+    jest.isolateModules(() => {
+      const { ObjectGraph, mockGraphs } = require('../../src/index');
+
+      class MockedGraph extends ObjectGraph {}
+
+      // Should be able to call mockGraphs without errors
+      expect(() => {
+        mockGraphs({ TestGraph: MockedGraph });
+      }).not.toThrow();
+    });
+  });
+
+  it('React-dependent features throw helpful errors without React', () => {
+    jest.isolateModules(() => {
+      const {
+        injectComponent,
+        injectHook,
+        injectHookWithArguments,
+        useObserver,
+        useObservers,
+        Model,
+      } = require('../../src/index');
+
+      // All React-dependent features should throw clear errors
+      expect(() => injectComponent(() => null, 'test'))
+        .toThrow('injectComponent requires React to be installed');
+
+      expect(() => injectHook(() => ({}), 'test'))
+        .toThrow('injectHook requires React to be installed');
+
+      expect(() => injectHookWithArguments(() => ({}), 'test'))
+        .toThrow('injectHookWithArguments requires React to be installed');
+
+      expect(() => {
+        const { Observable } = require('../../src/index');
+        useObserver(new Observable(1));
+      }).toThrow('useObserver requires React to be installed');
+
+      expect(() => useObservers({}))
+        .toThrow('useObservers requires React to be installed');
+
+      expect(() => new Model())
+        .toThrow('Model requires React to be installed');
+    });
+  });
+
+  it('testKit is undefined without React', () => {
+    jest.isolateModules(() => {
+      const { testKit } = require('../../src/index');
+      expect(() => testKit({})).toThrow('testKit requires React to be installed');
+    });
+  });
+
+  it('mockModel is undefined without React', () => {
+    jest.isolateModules(() => {
+      const { mockModel } = require('../../src/index');
+      expect(() => mockModel({})).toThrow('mockModel requires React to be installed');
+    });
+  });
+});

yarn.lock

@@ -16529,7 +16529,10 @@ __metadata:
     setimmediate: ^1.0.5
     typescript: ^5.7.3
   peerDependencies:
-    react: "*"
+    react: ">=16.8.0"
+  peerDependenciesMeta:
+    react:
+      optional: true
   languageName: unknown
   linkType: soft