react-single-instance 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Itay Merchav
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# react-single-instance
+
+![npm version](https://img.shields.io/npm/v/react-single-instance?logo=npm&logoColor=white) ![bundle size](https://img.shields.io/bundlephobia/minzip/react-single-instance?logo=javascript&logoColor=white) ![License](https://img.shields.io/npm/l/react-single-instance?logo=open-source-initiative)
+
+Render something at most once for a given `id`, app-wide - a component, a hook, and a HOC, all sharing one registry. Useful for a modal root, a toast host, or any other element that must exist exactly once even if it gets mounted from more than one place by mistake.
+
+Started as a small helper inside [faintlines](https://github.com/itaym/faintlines); this is the standalone, tested, rewritten version.
+
+```bash
+npm i react-single-instance
+```
+
+```tsx
+import { initSingleInstance, SingleInstance, useSingleInstance, withSingleInstance } from 'react-single-instance';
+
+// once, at app startup, before anything below renders
+initSingleInstance();
+```
+
+## `<SingleInstance>`
+
+```tsx
+<SingleInstance id="modal-root">
+  <ModalHost />
+</SingleInstance>
+```
+
+If a second `<SingleInstance id="modal-root">` mounts anywhere else in the tree, it renders nothing.
+
+## `useSingleInstance`
+
+```tsx
+function ModalHost() {
+  const granted = useSingleInstance('modal-root');
+  return granted ? <div className="modal-host" /> : null;
+}
+```
+
+## `withSingleInstance`
+
+```tsx
+const GuardedModalHost = withSingleInstance(ModalHost, 'modal-root');
+```
+
+## Why this needs `initSingleInstance()`
+
+`React.StrictMode` invokes a function component's render body twice, back to back, in development only. There's no purity-safe way, from inside render, to tell "this is my own StrictMode replay" apart from "this is a genuinely different caller" - so the registry allows exactly two claims per id before rejecting the rest, which absorbs StrictMode's double-invoke without ever risking a real mount silently rendering nothing.
+
+`initSingleInstance()` resets the registry. Call it once, synchronously, before your app renders anything that uses an id you care about - a hot reload, a new test, or a route remount that should be allowed to claim an id again all need this. Skipping it doesn't break anything by itself, but you'll get a console warning the first time an id is claimed, since un-reset ids never free up.
+
+**Known limitation:** two genuinely different call sites that both mount with the same `id` in the same commit, *outside* of StrictMode, will both be granted - the two-slot slack that makes StrictMode safe is indistinguishable, from inside render, from two real callers. Run under StrictMode (React's development default) and a real duplicate's own two extra invocations get caught immediately; without it, a duplicate that stays mounted is still caught the moment a third claimant shows up, or after the next `initSingleInstance()` cycle.
+
+## Playground
+
+A live demo of all three APIs, including the re-render and reset behavior:
+
+```bash
+npm run playground
+```
+
+## Development
+
+```bash
+npm install
+npm run build          # tsup: ESM + CJS + d.ts
+npm test               # Vitest (happy-dom)
+npm run test:coverage
+npm run playground     # http://localhost:4174
+```
+
+## Have a good productive day :)
+
+If you like this package please consider donation <a href="https://paypal.me/ItayMerchav?locale.x=en_US" target="_blank">Click Here</a>
+
+## License
+
+MIT © 2026 Itay Merchav

package/dist/index.cjs

@@ -0,0 +1,86 @@
+"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, {
+  SingleInstance: () => SingleInstance,
+  default: () => SingleInstance_default,
+  initSingleInstance: () => initSingleInstance,
+  useSingleInstance: () => useSingleInstance,
+  withSingleInstance: () => withSingleInstance
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/useSingleInstance.ts
+var import_react = require("react");
+
+// src/registry.ts
+var STRICT_MODE_SLACK = 2;
+var counts = /* @__PURE__ */ new Map();
+var initialized = false;
+function initSingleInstance() {
+  initialized = true;
+  counts.clear();
+}
+function claimSingleInstance(id) {
+  var _a;
+  if (!initialized && process.env.NODE_ENV !== "production") {
+    console.warn(
+      `[react-single-instance] "${id}" rendered before initSingleInstance() ran. Call initSingleInstance() once at app startup - otherwise ids never reset between test runs, hot reloads, or route remounts.`
+    );
+  }
+  const count = (_a = counts.get(id)) != null ? _a : 0;
+  if (count >= STRICT_MODE_SLACK) return false;
+  counts.set(id, count + 1);
+  return true;
+}
+
+// src/useSingleInstance.ts
+function useSingleInstance(id) {
+  const settled = (0, import_react.useRef)(void 0);
+  if (settled.current === void 0) {
+    settled.current = claimSingleInstance(id);
+  }
+  return settled.current;
+}
+
+// src/SingleInstance.tsx
+function SingleInstance({ id, children }) {
+  return useSingleInstance(id) ? children : null;
+}
+var SingleInstance_default = SingleInstance;
+
+// src/withSingleInstance.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+function withSingleInstance(Component, id) {
+  function WithSingleInstance(props) {
+    return useSingleInstance(id) ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Component, { ...props }) : null;
+  }
+  WithSingleInstance.displayName = `withSingleInstance(${Component.displayName || Component.name || "Component"})`;
+  return WithSingleInstance;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SingleInstance,
+  initSingleInstance,
+  useSingleInstance,
+  withSingleInstance
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/useSingleInstance.ts","../src/registry.ts","../src/SingleInstance.tsx","../src/withSingleInstance.tsx"],"sourcesContent":["export { SingleInstance, default } from './SingleInstance';\nexport type { SingleInstanceProps } from './SingleInstance';\nexport { useSingleInstance } from './useSingleInstance';\nexport { withSingleInstance } from './withSingleInstance';\nexport { initSingleInstance } from './registry';\n","import { useRef } from 'react';\nimport { claimSingleInstance } from './registry';\n\n// Memoized so a settled instance never re-consults the registry on later re-renders (see README).\nexport function useSingleInstance(id: string): boolean {\n  const settled = useRef<boolean | undefined>(undefined);\n  if (settled.current === undefined) {\n    settled.current = claimSingleInstance(id);\n  }\n  return settled.current;\n}\n","// React.StrictMode double-invokes render in dev; both calls must succeed since we can't tell which gets committed (see README).\nconst STRICT_MODE_SLACK = 2;\n\nconst counts = new Map<string, number>();\nlet initialized = false;\n\nexport function initSingleInstance(): void {\n  initialized = true;\n  counts.clear();\n}\n\n/** @internal exposed for tests only */\nexport function __resetSingleInstanceForTests(): void {\n  counts.clear();\n  initialized = false;\n}\n\nexport function claimSingleInstance(id: string): boolean {\n  if (!initialized && process.env.NODE_ENV !== 'production') {\n    console.warn(\n      `[react-single-instance] \"${id}\" rendered before initSingleInstance() ran. ` +\n        'Call initSingleInstance() once at app startup - otherwise ids never reset ' +\n        'between test runs, hot reloads, or route remounts.',\n    );\n  }\n\n  const count = counts.get(id) ?? 0;\n  if (count >= STRICT_MODE_SLACK) return false;\n\n  counts.set(id, count + 1);\n  return true;\n}\n","import type { ReactNode } from 'react';\nimport { useSingleInstance } from './useSingleInstance';\n\nexport interface SingleInstanceProps {\n  id: string;\n  children: ReactNode;\n}\n\nexport function SingleInstance({ id, children }: SingleInstanceProps): ReactNode {\n  return useSingleInstance(id) ? children : null;\n}\n\nexport default SingleInstance;\n","import type { ComponentType } from 'react';\nimport { useSingleInstance } from './useSingleInstance';\n\nexport function withSingleInstance<P extends object>(Component: ComponentType<P>, id: string): ComponentType<P> {\n  function WithSingleInstance(props: P) {\n    return useSingleInstance(id) ? <Component {...props} /> : null;\n  }\n\n  WithSingleInstance.displayName = `withSingleInstance(${Component.displayName || Component.name || 'Component'})`;\n\n  return WithSingleInstance;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,mBAAuB;;;ACCvB,IAAM,oBAAoB;AAE1B,IAAM,SAAS,oBAAI,IAAoB;AACvC,IAAI,cAAc;AAEX,SAAS,qBAA2B;AACzC,gBAAc;AACd,SAAO,MAAM;AACf;AAQO,SAAS,oBAAoB,IAAqB;AAjBzD;AAkBE,MAAI,CAAC,eAAe,QAAQ,IAAI,aAAa,cAAc;AACzD,YAAQ;AAAA,MACN,4BAA4B,EAAE;AAAA,IAGhC;AAAA,EACF;AAEA,QAAM,SAAQ,YAAO,IAAI,EAAE,MAAb,YAAkB;AAChC,MAAI,SAAS,kBAAmB,QAAO;AAEvC,SAAO,IAAI,IAAI,QAAQ,CAAC;AACxB,SAAO;AACT;;;AD3BO,SAAS,kBAAkB,IAAqB;AACrD,QAAM,cAAU,qBAA4B,MAAS;AACrD,MAAI,QAAQ,YAAY,QAAW;AACjC,YAAQ,UAAU,oBAAoB,EAAE;AAAA,EAC1C;AACA,SAAO,QAAQ;AACjB;;;AEFO,SAAS,eAAe,EAAE,IAAI,SAAS,GAAmC;AAC/E,SAAO,kBAAkB,EAAE,IAAI,WAAW;AAC5C;AAEA,IAAO,yBAAQ;;;ACPoB;AAF5B,SAAS,mBAAqC,WAA6B,IAA8B;AAC9G,WAAS,mBAAmB,OAAU;AACpC,WAAO,kBAAkB,EAAE,IAAI,4CAAC,aAAW,GAAG,OAAO,IAAK;AAAA,EAC5D;AAEA,qBAAmB,cAAc,sBAAsB,UAAU,eAAe,UAAU,QAAQ,WAAW;AAE7G,SAAO;AACT;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,15 @@
+import { ReactNode, ComponentType } from 'react';
+
+interface SingleInstanceProps {
+    id: string;
+    children: ReactNode;
+}
+declare function SingleInstance({ id, children }: SingleInstanceProps): ReactNode;
+
+declare function useSingleInstance(id: string): boolean;
+
+declare function withSingleInstance<P extends object>(Component: ComponentType<P>, id: string): ComponentType<P>;
+
+declare function initSingleInstance(): void;
+
+export { SingleInstance, type SingleInstanceProps, SingleInstance as default, initSingleInstance, useSingleInstance, withSingleInstance };

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import { ReactNode, ComponentType } from 'react';
+
+interface SingleInstanceProps {
+    id: string;
+    children: ReactNode;
+}
+declare function SingleInstance({ id, children }: SingleInstanceProps): ReactNode;
+
+declare function useSingleInstance(id: string): boolean;
+
+declare function withSingleInstance<P extends object>(Component: ComponentType<P>, id: string): ComponentType<P>;
+
+declare function initSingleInstance(): void;
+
+export { SingleInstance, type SingleInstanceProps, SingleInstance as default, initSingleInstance, useSingleInstance, withSingleInstance };

package/dist/index.js

@@ -0,0 +1,56 @@
+// src/useSingleInstance.ts
+import { useRef } from "react";
+
+// src/registry.ts
+var STRICT_MODE_SLACK = 2;
+var counts = /* @__PURE__ */ new Map();
+var initialized = false;
+function initSingleInstance() {
+  initialized = true;
+  counts.clear();
+}
+function claimSingleInstance(id) {
+  var _a;
+  if (!initialized && process.env.NODE_ENV !== "production") {
+    console.warn(
+      `[react-single-instance] "${id}" rendered before initSingleInstance() ran. Call initSingleInstance() once at app startup - otherwise ids never reset between test runs, hot reloads, or route remounts.`
+    );
+  }
+  const count = (_a = counts.get(id)) != null ? _a : 0;
+  if (count >= STRICT_MODE_SLACK) return false;
+  counts.set(id, count + 1);
+  return true;
+}
+
+// src/useSingleInstance.ts
+function useSingleInstance(id) {
+  const settled = useRef(void 0);
+  if (settled.current === void 0) {
+    settled.current = claimSingleInstance(id);
+  }
+  return settled.current;
+}
+
+// src/SingleInstance.tsx
+function SingleInstance({ id, children }) {
+  return useSingleInstance(id) ? children : null;
+}
+var SingleInstance_default = SingleInstance;
+
+// src/withSingleInstance.tsx
+import { jsx } from "react/jsx-runtime";
+function withSingleInstance(Component, id) {
+  function WithSingleInstance(props) {
+    return useSingleInstance(id) ? /* @__PURE__ */ jsx(Component, { ...props }) : null;
+  }
+  WithSingleInstance.displayName = `withSingleInstance(${Component.displayName || Component.name || "Component"})`;
+  return WithSingleInstance;
+}
+export {
+  SingleInstance,
+  SingleInstance_default as default,
+  initSingleInstance,
+  useSingleInstance,
+  withSingleInstance
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/useSingleInstance.ts","../src/registry.ts","../src/SingleInstance.tsx","../src/withSingleInstance.tsx"],"sourcesContent":["import { useRef } from 'react';\nimport { claimSingleInstance } from './registry';\n\n// Memoized so a settled instance never re-consults the registry on later re-renders (see README).\nexport function useSingleInstance(id: string): boolean {\n  const settled = useRef<boolean | undefined>(undefined);\n  if (settled.current === undefined) {\n    settled.current = claimSingleInstance(id);\n  }\n  return settled.current;\n}\n","// React.StrictMode double-invokes render in dev; both calls must succeed since we can't tell which gets committed (see README).\nconst STRICT_MODE_SLACK = 2;\n\nconst counts = new Map<string, number>();\nlet initialized = false;\n\nexport function initSingleInstance(): void {\n  initialized = true;\n  counts.clear();\n}\n\n/** @internal exposed for tests only */\nexport function __resetSingleInstanceForTests(): void {\n  counts.clear();\n  initialized = false;\n}\n\nexport function claimSingleInstance(id: string): boolean {\n  if (!initialized && process.env.NODE_ENV !== 'production') {\n    console.warn(\n      `[react-single-instance] \"${id}\" rendered before initSingleInstance() ran. ` +\n        'Call initSingleInstance() once at app startup - otherwise ids never reset ' +\n        'between test runs, hot reloads, or route remounts.',\n    );\n  }\n\n  const count = counts.get(id) ?? 0;\n  if (count >= STRICT_MODE_SLACK) return false;\n\n  counts.set(id, count + 1);\n  return true;\n}\n","import type { ReactNode } from 'react';\nimport { useSingleInstance } from './useSingleInstance';\n\nexport interface SingleInstanceProps {\n  id: string;\n  children: ReactNode;\n}\n\nexport function SingleInstance({ id, children }: SingleInstanceProps): ReactNode {\n  return useSingleInstance(id) ? children : null;\n}\n\nexport default SingleInstance;\n","import type { ComponentType } from 'react';\nimport { useSingleInstance } from './useSingleInstance';\n\nexport function withSingleInstance<P extends object>(Component: ComponentType<P>, id: string): ComponentType<P> {\n  function WithSingleInstance(props: P) {\n    return useSingleInstance(id) ? <Component {...props} /> : null;\n  }\n\n  WithSingleInstance.displayName = `withSingleInstance(${Component.displayName || Component.name || 'Component'})`;\n\n  return WithSingleInstance;\n}\n"],"mappings":";AAAA,SAAS,cAAc;;;ACCvB,IAAM,oBAAoB;AAE1B,IAAM,SAAS,oBAAI,IAAoB;AACvC,IAAI,cAAc;AAEX,SAAS,qBAA2B;AACzC,gBAAc;AACd,SAAO,MAAM;AACf;AAQO,SAAS,oBAAoB,IAAqB;AAjBzD;AAkBE,MAAI,CAAC,eAAe,QAAQ,IAAI,aAAa,cAAc;AACzD,YAAQ;AAAA,MACN,4BAA4B,EAAE;AAAA,IAGhC;AAAA,EACF;AAEA,QAAM,SAAQ,YAAO,IAAI,EAAE,MAAb,YAAkB;AAChC,MAAI,SAAS,kBAAmB,QAAO;AAEvC,SAAO,IAAI,IAAI,QAAQ,CAAC;AACxB,SAAO;AACT;;;AD3BO,SAAS,kBAAkB,IAAqB;AACrD,QAAM,UAAU,OAA4B,MAAS;AACrD,MAAI,QAAQ,YAAY,QAAW;AACjC,YAAQ,UAAU,oBAAoB,EAAE;AAAA,EAC1C;AACA,SAAO,QAAQ;AACjB;;;AEFO,SAAS,eAAe,EAAE,IAAI,SAAS,GAAmC;AAC/E,SAAO,kBAAkB,EAAE,IAAI,WAAW;AAC5C;AAEA,IAAO,yBAAQ;;;ACPoB;AAF5B,SAAS,mBAAqC,WAA6B,IAA8B;AAC9G,WAAS,mBAAmB,OAAU;AACpC,WAAO,kBAAkB,EAAE,IAAI,oBAAC,aAAW,GAAG,OAAO,IAAK;AAAA,EAC5D;AAEA,qBAAmB,cAAc,sBAAsB,UAAU,eAAe,UAAU,QAAQ,WAAW;AAE7G,SAAO;AACT;","names":[]}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "react-single-instance",
+  "version": "0.1.0",
+  "description": "Render a component at most once for a given id, app-wide - safely absorbs React.StrictMode's dev double-invoke",
+  "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"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit -p . && tsc --noEmit -p playground",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "playground": "npm --prefix playground run dev",
+    "playground:build": "npm run build && npm --prefix playground install && npm --prefix playground run build",
+    "playground:preview": "npm --prefix playground run preview",
+    "format": "prettier --write \"src/**/*.{ts,tsx}\" \"playground/src/**/*.{ts,tsx}\"",
+    "format:check": "prettier --check \"src/**/*.{ts,tsx}\" \"playground/src/**/*.{ts,tsx}\""
+  },
+  "keywords": [
+    "react",
+    "strict-mode",
+    "singleton",
+    "idempotent",
+    "hook",
+    "hoc",
+    "modal",
+    "guard"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/itaym/react-single-instance.git"
+  },
+  "author": "Itay Merchav",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/itaym/react-single-instance/issues"
+  },
+  "homepage": "https://github.com/itaym/react-single-instance#readme",
+  "peerDependencies": {
+    "react": ">=17"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/jest-dom": "^6.5.0",
+    "@testing-library/react": "^16.0.1",
+    "@types/node": "^20.14.15",
+    "@types/react": "^18.3.5",
+    "@types/react-dom": "^18.3.0",
+    "@vitest/coverage-v8": "^4.1.11",
+    "happy-dom": "^20.14.0",
+    "prettier": "^3.3.3",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "tsup": "^8.2.4",
+    "typescript": "^5.5.4",
+    "vitest": "^4.1.11"
+  }
+}