Emotion Server-Side Rendering Utilities

11.0.0 · active · verified Sun Apr 19

@emotion/server is a critical package within the Emotion CSS-in-JS ecosystem, primarily designed to facilitate efficient server-side rendering (SSR) of styled React applications. Its core functionality involves extracting and inlining only the 'critical CSS' required for the initial page load, thereby preventing flashes of unstyled content (FOUC) and improving perceived performance. The package is part of the Emotion v11 stable release, which introduced significant TypeScript improvements and internal shifts to React Hooks. Emotion maintains a consistent, modular release cadence across its packages, with frequent patch updates and coordinated minor/major versions. A key differentiator is its deep integration with the `@emotion/react` and `@emotion/cache` packages, providing robust and performant solutions for complex SSR setups, including support for React's streaming APIs, though this often requires more advanced configurations.

Common errors

```
Error: Hydration failed because the initial UI does not match what was rendered on the server.
```
cause Client-side React is trying to hydrate a DOM tree that differs from the server-rendered HTML, often due to mismatched Emotion styles, incorrect cache setup, or missing `hydrate` call.

fix Ensure the same Emotion cache key and configuration are used on both server and client. Verify that `CacheProvider` wraps your application during SSR. If using `extractCritical`, ensure the extracted `ids` are passed to the client and `hydrate(ids)` is called.
```
ReferenceError: navigator is not defined
```
cause This typically occurs when `createCache` from `@emotion/cache` is invoked directly in a Node.js (server) environment without providing a suitable `container` or `stylisPlugins` option if browser-specific APIs are implicitly accessed.

fix Ensure `createCache` is called with the `key` option and potentially a custom `container` or `stylisPlugins` if non-browser defaults are an issue. Creating a cache per request on the server also helps isolate styles.
```
TypeError: Cannot read properties of undefined (reading 'sheet')
```
cause This error often indicates that the Emotion cache instance or the `CacheProvider` is not correctly set up or accessible within the React component tree during SSR.

fix Double-check that `createCache` is correctly called, and the resulting `cache` object is passed to `<CacheProvider value={cache}>` wrapping your application on the server. Verify that all Emotion-related packages are compatible versions.
```
Error: @emotion/react's CacheProvider was not found.
```
cause The Emotion context, provided by `CacheProvider`, is missing from the component tree, preventing Emotion components from accessing the necessary cache.

fix Ensure that your entire application, especially the root component being rendered server-side, is wrapped within `<CacheProvider value={cache}>` where `cache` is an instance created by `createCache`.

Warnings

breaking Migrating from Emotion v10 to v11 involves significant breaking changes, including package renames (e.g., `@emotion/core` to `@emotion/react`), and a mandatory `key` option when initializing Emotion's cache via `createCache`. Ensure all Emotion-related packages are upgraded to compatible v11 versions.
Fix: Review Emotion's v11 migration guide. Update package names and ensure `createCache({ key: 'your-app-key' })` is used. Use the Emotion ESLint plugin with codemods to automate some renames.
gotcha Incorrect or missing `CacheProvider` setup on the server or a mismatch between server and client-side generated styles can lead to hydration errors (e.g., UI differences or style re-insertion). Each server render should typically use a new `EmotionCache` instance.
Fix: Always wrap your top-level component with `<CacheProvider value={cache}>` during SSR. Ensure a unique cache instance is created for each request on the server. On the client, ensure proper hydration logic is in place, often by calling `hydrate(ids)` if using `extractCritical`.
gotcha Emotion's 'default approach' for SSR (without explicit critical extraction) can interfere with `:nth-child` or similar selectors due to style tags being inserted directly into the markup. The advanced approach using `extractCritical` or `createEmotionServer` avoids this.
Fix: If experiencing issues with complex selectors, switch to the 'advanced approach' using `extractCritical` with `CacheProvider` on the server and ensure the extracted styles are correctly injected into the `<head>` of your HTML document.
deprecated The `renderStylesToString` function from `@emotion/server` is largely superseded by `extractCritical` for comprehensive critical CSS extraction and `renderStylesToNodeStream` for React 18 streaming. While it still works, `extractCritical` provides more control over the extracted CSS and IDs.
Fix: Prefer `extractCritical` for most SSR scenarios where you render to a string and need to inject styles. For React 18 streaming, use `renderStylesToNodeStream` in conjunction with React's streaming APIs.
gotcha Integrating Emotion with React 18's streaming SSR (`renderToPipeableStream`) is significantly more complex than traditional `renderToString`. `emotion-server` provides `renderStylesToNodeStream`, but advanced setups often require custom transform streams or specific framework integrations.
Fix: Consult detailed documentation or framework-specific guides (e.g., Next.js, Gatsby) for React 18 streaming SSR with Emotion. The `renderStylesToNodeStream` should be piped after React's stream.

Install

npm install emotion-server npm
yarn add emotion-server yarn
pnpm add emotion-server pnpm

Imports

extractCritical
wrong:
```
const { extractCritical } = require('@emotion/server');
```
correct:
```
import { extractCritical } from '@emotion/server';
```
This is the primary function for extracting critical CSS from a rendered React string. While CommonJS `require` can sometimes work via transpilation, direct ESM `import` is the standard for modern Node.js and bundled environments.
renderStylesToNodeStream
wrong:
```
const { renderStylesToNodeStream } = require('@emotion/server');
```
correct:
```
import { renderStylesToNodeStream } from '@emotion/server';
```
Used for React 18+ streaming SSR to inject styles into a Node.js stream. Requires careful integration with `ReactDOMServer.renderToNodeStream` or `renderToPipeableStream`.
CacheProvider
wrong:
```
import { CacheProvider } from '@emotion/core';
```
correct:
```
import { CacheProvider } from '@emotion/react';
```
Essential for providing an Emotion cache to your React tree during SSR. Emotion v11 renamed `@emotion/core` to `@emotion/react`. Incorrect package or missing `CacheProvider` leads to errors.
createCache
wrong:
```
import { createCache } from '@emotion/cache'; // If default export
const createCache = require('@emotion/cache'); // Missing .default for default export
```
correct:
```
import createCache from '@emotion/cache';
```
`createCache` is a default export from `@emotion/cache` and is used to instantiate a new Emotion cache for each server request. Since Emotion v11, the `key` option is mandatory when creating a custom cache.

Quickstart

Demonstrates how to use `emotion-server`'s `extractCritical` function with React's `renderToString` to extract and inline critical CSS during server-side rendering, ensuring proper `CacheProvider` setup for Emotion v11.

import ReactDOMServer from 'react-dom/server';
import { CacheProvider } from '@emotion/react';
import createCache from '@emotion/cache';
import { extractCritical } from '@emotion/server';
import { css } from '@emotion/react';

// A simple Emotion-styled React component
const MyStyledComponent = () => (
  <div
    css={css`
      color: hotpink;
      background-color: lightblue;
      padding: 1rem;
      border-radius: 8px;
      &:hover {
        color: white;
      }
    `}
  >
    Hello from Emotion SSR!
  </div>
);

// Create a new Emotion cache for the server request
// The 'key' option is mandatory since Emotion v11
const cache = createCache({ key: 'my-app' });

// Render the component to a string and extract critical CSS
const { html, css: criticalCss, ids } = extractCritical(
  ReactDOMServer.renderToString(
    <CacheProvider value={cache}>
      <MyStyledComponent />
    </CacheProvider>
  )
);

console.log('--- Critical CSS ---');
console.log(criticalCss);
console.log('\n--- Rendered HTML ---');
console.log(`<style data-emotion="${cache.key}-${ids.join(' ')}">${criticalCss}</style>${html}`);

// In a real application, 'criticalCss' would be injected into the <head> of the HTML document.
// The 'ids' should also be passed to the client for proper hydration.
// Example of how to integrate into a full HTML document (simplified):
const fullHtml = `
  <!DOCTYPE html>
  <html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Emotion SSR Example</title>
    <style data-emotion="${cache.key}-${ids.join(' ')}">${criticalCss}</style>
  </head>
  <body>
    <div id="root">${html}</div>
    <script>
      // On the client, hydrate with the same cache key and potentially call emotion/css hydrate function
      // import { hydrate } from '@emotion/css';
      // import createCache from '@emotion/cache';
      // const cache = createCache({ key: 'my-app' });
      // hydrate(${JSON.stringify(ids)});
      // ReactDOMClient.hydrateRoot(document.getElementById('root'), <CacheProvider value={cache}><MyStyledComponent /></CacheProvider>);
    </script>
  </body>
  </html>
`;
console.log('\n--- Full HTML Structure (simplified) ---');
console.log(fullHtml);

view raw JSON →