#3394·emotion

Lack of documentation regarding the speedy option

Author: alshazaCreated Aug 1, 2026Updated Aug 1, 2026
Labelsneeds triagedocumentation

The speedy option (createCache({ speedy }), and @emotion/css's runtime sheet.speedy(...)) has no dedicated documentation anywhere on emotion.sh, even though it's a fairly consequential option - it's enabled by default in production and switches style insertion from text-node appends to CSSOM.insertRule. The only existing mention is a narrow aside in the SSR docs about disabling it for Puppeteer prerendering.

This makes it hard for users to discover speedy's tradeoffs, which shows up as several open issues that all stem from not knowing about speedy's behavior/caveats (e.g. https://github.com/emotion-js/emotion/issues/2404, https://github.com/emotion-js/emotion/issues/2508).

I'd like to add a dedicated "Speedy" docs page explaining what the option does, its default, how to configure it, and its known caveats (with links to the issues above), and bring packages/cache/README.md's options list up to date.

Documentation links: