Allow customizing unique ID generation

[theop-luma]

This let's app customize the algorithm that sets IDs, could be used to align ID generation between shapes & artifacts

---

Note

Introduces setUniqueIdGenerator to override ID generation globally and adds detailed docs/examples for createShapeId.

• Utilities (@tldraw/utils):
  • ID Generation: Add setUniqueIdGenerator to override the global unique ID generator; keep uniqueId delegating to the pluggable impl.
  • Restore: Document and expose restoreUniqueId as public for reverting to the default generator.
  • Exports: Re-export setUniqueIdGenerator from packages/utils/src/index.ts.
• Schema (tlschema):
  • Shape IDs: Expand JSDoc for createShapeId with examples and note about customizing via setUniqueIdGenerator.

^{Written by Cursor Bugbot for commit 5cb9cd0. This will update automatically on new commits. Configure here.}

[cursor]

PR Summary

Medium Risk
Changing the global ID generator can affect uniqueness/collision behavior across all records if misused, though the default behavior is unchanged unless an app opts in.

Overview
Adds a new public API setUniqueIdGenerator in @tldraw/utils to let apps override the internal uniqueId() implementation, with restoreUniqueId() now documented/public for resetting back to the default generator.

Updates exports to expose the new setter, and refreshes createShapeId docs to reference this customization hook (plus minor doc/example tweaks).

^{Written by Cursor Bugbot for commit 054367a. This will update automatically on new commits. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is ON. A Cloud Agent has been kicked off to fix the reported issue.}

[cursor]

Bugbot Autofix prepared fixes for 1 of the 1 bugs found in the latest run.

• ✅ Fixed: setUniqueIdGenerator duplicates mockUniqueId implementation exactly
  • Changed mockUniqueId to delegate to setUniqueIdGenerator(fn) instead of directly assigning impl = fn, eliminating the code duplication.

Or push these changes by commenting:

@cursor push e484e66c7a

Preview (e484e66c7a)

diff --git a/packages/utils/api-report.api.md b/packages/utils/api-report.api.md
--- a/packages/utils/api-report.api.md
+++ b/packages/utils/api-report.api.md
@@ -408,7 +408,7 @@
 }>;
 export { Required_2 as Required }
 
-// @internal
+// @public
 export function restoreUniqueId(): void;
 
 // @public
@@ -448,6 +448,9 @@
 // @internal
 export function setInSessionStorage(key: string, value: string): void;
 
+// @public
+export function setUniqueIdGenerator(fn: (size?: number) => string): void;
+
 // @internal
 export function sleep(ms: number): Promise<void>;
 

diff --git a/packages/utils/src/lib/id.ts b/packages/utils/src/lib/id.ts
--- a/packages/utils/src/lib/id.ts
+++ b/packages/utils/src/lib/id.ts
@@ -105,7 +105,7 @@
  * @internal
  */
 export function mockUniqueId(fn: (size?: number) => string) {
-	impl = fn
+	setUniqueIdGenerator(fn)
 }
 
 /**

[kaznaan]

oops, this has a build error. I'll revert my change and please fix build error.