What is the difference between `Symbol('app.id')` and `Symbol.for('app.id')` in JavaScript?

## Two opposite goals The plain `Symbol()` call exists to guarantee that *nobody else can have this value*. The registry exists to guarantee the opposite: that *everybody who asks by the same name gets the same value*. Both are useful; they answer different questions. ```js Symbol('a') === Symbol('a'); // false — uniqueness Symbol.for('a') === Symbol.for('a'); // true — shared identity ``` ## How the registry works `Symbol.for(key)` takes a string, coerces it to a string if it is not one, and looks it up in a single process-wide table the spec calls the **GlobalSymbolRegistry**. If an entry exists, the stored symbol is returned. If not, a new symbol is created with that string as both its registry key and its description, stored, and returned. There is no removal API — an entry lives for the life of the agent. `Symbol.keyFor` runs the lookup backwards: ```js const shared = Symbol.for('app.id'); const local = Symbol('app.id'); Symbol.keyFor(shared); // 'app.id' Symbol.keyFor(local); // undefined — not in the registry shared === local; // false — different values entirely shared.description; // 'app.id' ``` Note that `keyFor` returning `undefined` is the reliable way to tell a registered symbol from an unregistered one; the description alone tells you nothing, since a plain symbol can carry any description you like. ## Cross-realm is the point The registry is shared across **realms** — separate global environments that would otherwise each have their own copies of the built-ins. A page and a same-origin iframe are two realms; each has its own `Array`, its own `Object.prototype`, its own everything. Values created in one and passed to the other are still distinguishable (`arr instanceof Array` famously fails across an iframe boundary for exactly this reason). The symbol registry deliberately spans them: ```js // in the top page window.marker = Symbol.for('myapp.marker'); // in a same-origin iframe, independently Symbol.for('myapp.marker') === parent.marker; // true ``` The other everyday case has nothing to do with iframes: **two copies of the same library** ending up in one bundle, or a library loaded once as ESM and once as CommonJS. Two module instances each evaluate `const KEY = Symbol('lib.state')` and get *different* keys, so instance A cannot see the state instance B attached. `Symbol.for('lib.state')` makes them agree without either needing a reference to the other. Several real libraries use exactly this trick for singleton detection. ## What you give up A registry key is a **global string namespace**, with all the problems that implies: - Anyone in the process can call `Symbol.for('lib.state')` and get your key, read your property, and overwrite it. The collision-proofing that plain symbols give you is gone by design. - Two unrelated libraries can pick the same string, which is why the convention is to namespace: `'myapp.id'`, `'react.element'`-style prefixes. - Entries are never garbage-collected. That is a bounded leak (one symbol per distinct string) but a real one if you ever generate registry keys dynamically — never call `Symbol.for(userInput)` in a loop. ## Choosing between them Ask one question: *does some other code, which cannot receive this symbol as a value, need to name the same key?* - **No** — use `Symbol()`. This covers almost everything: private-ish metadata, per-module bookkeeping, keys you export from your own module so consumers import the value itself. - **Yes** — use `Symbol.for()` with a namespaced string. Cross-realm protocols, duplicate-instance detection, and conventions meant to be implemented by code you have never seen. A useful contrast: the *well-known* symbols such as `Symbol.iterator` are a third category. They are neither freshly minted nor in the registry — they are fixed properties of the `Symbol` constructor that the specification itself defines, and they are shared across realms because every realm's `Symbol.iterator` is the same value. `Symbol.keyFor(Symbol.iterator)` returns `undefined`, confirming they are not registry entries. ## Small details worth knowing - `Symbol.for(1)` works — the argument is converted to the string `'1'`. - The registry string becomes the description, so `Symbol.for('a').description === 'a'`. - There is no `Symbol.delete` or way to enumerate the registry from JavaScript.