or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

create-instance.mdextract-critical.mdindex.mdrender-to-stream.mdrender-to-string.md
tile.json

tessl/npm-emotion--server

Extract and inline critical css with emotion for server side rendering

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@emotion/server@11.0.x

To install, run

npx @tessl/cli install tessl/npm-emotion--server@11.0.0

index.mddocs/

@emotion/server

@emotion/server provides server-side rendering capabilities for Emotion CSS-in-JS library, offering three main APIs for extracting and inlining critical CSS: extractCritical for extracting critical CSS from rendered components, renderStylesToString for inlining critical CSS into HTML strings, and renderStylesToNodeStream for streaming critical CSS inline with HTML.

Package Information

  • Package Name: @emotion/server
  • Package Type: npm
  • Language: JavaScript with Flow types and TypeScript definitions
  • Installation: npm install @emotion/server @emotion/css (Note: @emotion/css is a peer dependency)

Core Imports

import { extractCritical, renderStylesToString, renderStylesToNodeStream } from "@emotion/server";

For custom cache instances:

import createEmotionServer from "@emotion/server/create-instance";

CommonJS:

const { extractCritical, renderStylesToString, renderStylesToNodeStream } = require("@emotion/server");
const createEmotionServer = require("@emotion/server/create-instance").default;

Basic Usage

import React from "react";
import { renderToString } from "react-dom/server";
import { extractCritical, renderStylesToString } from "@emotion/server";

// Extract critical CSS
const { html, css, ids } = extractCritical(renderToString(<App />));

// Inline critical CSS into HTML
const htmlWithStyles = renderStylesToString(renderToString(<App />));

// Use with streaming (Node.js)
const stream = renderStylesToNodeStream();

Architecture

@emotion/server is built around several key components:

  • Default Exports: Pre-configured functions using @emotion/css cache for immediate use
  • Factory Pattern: createEmotionServer for custom cache instances and advanced configurations
  • Critical CSS Extraction: Parse rendered HTML to identify which Emotion styles are actually used
  • Inlining Strategies: String-based and stream-based approaches for injecting critical CSS
  • Cache Integration: Deep integration with Emotion's caching system for optimal performance

Capabilities

Critical CSS Extraction

Extract critical CSS from server-rendered HTML to identify which styles are actually used on the page.

function extractCritical(html: string): EmotionCritical;

interface EmotionCritical {
  html: string;        // Original HTML string
  ids: Array<string>;  // Array of emotion class IDs found
  css: string;         // Critical CSS styles
}

Critical CSS Extraction

String-based CSS Inlining

Inline critical CSS directly into HTML strings for immediate server-side rendering.

function renderStylesToString(html: string): string;

String-based Inlining

Stream-based CSS Inlining

Create Node.js streams for inlining critical CSS with HTML streaming, ideal for large pages and improved performance.

function renderStylesToNodeStream(): NodeJS.ReadWriteStream;

Stream-based Inlining

Custom Instance Creation

Create custom emotion server instances with specific cache configurations for advanced use cases.

function createEmotionServer(cache: EmotionCache): EmotionServer;

interface EmotionServer {
  extractCritical(html: string): EmotionCritical;
  renderStylesToString(html: string): string;
  renderStylesToNodeStream(): NodeJS.ReadWriteStream;
}

Custom Instance Creation

Types

interface EmotionCritical {
  html: string;        // Original HTML string
  ids: Array<string>;  // Array of emotion class IDs found  
  css: string;         // Critical CSS styles
}

interface EmotionServer {
  extractCritical(html: string): EmotionCritical;
  renderStylesToString(html: string): string;
  renderStylesToNodeStream(): NodeJS.ReadWriteStream;
}

// From @emotion/utils
interface EmotionCache {
  key: string;
  inserted: Record<string, string | true>;
  registered: Record<string, string>;
  sheet: StyleSheet;
  nonce?: string;
  compat?: true;
  insert(
    selector: string,
    serialized: SerializedStyles,
    sheet: StyleSheet,
    shouldCache: boolean
  ): string | void;
}

interface StyleSheet {
  container: HTMLElement;
  nonce?: string;
  key: string;
  insert(rule: string): void;
  flush(): void;
  tags: Array<HTMLStyleElement>;
}

interface SerializedStyles {
  name: string;
  styles: string;
  map?: string;
  next?: SerializedStyles;
}