Skip to content

feat: add keyFor for global symbol support#188

Merged
Gnuk merged 1 commit intoGnuk:mainfrom
marc-gavanier:main
Apr 1, 2026
Merged

feat: add keyFor for global symbol support#188
Gnuk merged 1 commit intoGnuk:mainfrom
marc-gavanier:main

Conversation

@marc-gavanier
Copy link
Copy Markdown
Contributor

@marc-gavanier marc-gavanier commented Mar 25, 2026

This enables compatibility with React Server Components, which require global symbols for serialization between server and client boundaries.

📖 Context

When using piqure with Next.js App Router (React Server Components), injection keys created with key() cannot be passed from Server Components to Client Components.

⚠️ Problem

React Server Components can only serialize global symbols. Local symbols created with Symbol() fail with:

Error: Only global symbols received from Symbol.for(...) can be passed to Client Components. The symbol Symbol(my-key) cannot be found among global symbols.

This happens because key() uses Symbol(description), which creates a unique local symbol on each call.

✅ Solution

Add keyFor() function that uses Symbol.for() to create global symbols. These symbols are registered in a global registry and can be serialized across server/client boundaries.

// Before (fails with RSC)
const MY_KEY = key<MyService>('my-service'):
// After (works with RSC)
const MY_KEY = keyFor<MyService>('my-service');

🤔 Why not change key() directly?

Symbol.for() uses a global registry, which means any code knowing the description can access the same symbol. This reduces isolation compared to Symbol(). Keeping both functions lets users choose based on their environment:

  • key() : strict isolation, for non-RSC environments
  • keyFor() : global symbols, required for RSC compatibility

📸 Screenshot

image

@murdos murdos requested a review from Gnuk March 25, 2026 23:31
Copy link
Copy Markdown
Collaborator

@murdos murdos left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It makes sense.
@Gnuk : please take a look if you can :)

This enables compatibility with React Server Components, which require global symbols for serialization between server and client boundaries.
@Gnuk Gnuk merged commit d849096 into Gnuk:main Apr 1, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants