or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-emotion-server

Server-side rendering utilities for emotion CSS-in-JS library that extract and inline critical CSS.

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

To install, run

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

index.mddocs/

emotion-server

emotion-server provides server-side rendering utilities for the emotion CSS-in-JS library, enabling developers to extract and inline critical CSS for improved performance and SEO. It offers three main APIs for extracting critical CSS, rendering styles as strings, and streaming styles during server-side rendering.

Package Information

  • Package Name: emotion-server
  • Package Type: npm
  • Language: JavaScript with Flow type annotations
  • Installation: npm install emotion emotion-server

Core Imports

import { extractCritical, renderStylesToString, renderStylesToNodeStream } from 'emotion-server';

For CommonJS:

const { extractCritical, renderStylesToString, renderStylesToNodeStream } = require('emotion-server');

Basic Usage

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

// Component with emotion styles
const StyledComponent = () => (
  <div className={css`
    color: blue;
    font-size: 16px;
  `}>
    Hello World
  </div>
);

// Extract critical CSS during server-side rendering
const { html, css: criticalCss, ids } = extractCritical(
  renderToString(<StyledComponent />)
);

// Or render styles inline in HTML
const htmlWithStyles = renderStylesToString(
  renderToString(<StyledComponent />)
);

Architecture

emotion-server works by leveraging emotion's cache system to identify and extract only the CSS that is actually used in rendered components. It uses regex pattern matching to find emotion class names in HTML and extracts corresponding styles from emotion's internal registry. The package serves as a lightweight wrapper around create-emotion-server, configured with emotion's default cache.

Capabilities

Critical CSS Extraction

Extracts critical CSS from rendered HTML and returns detailed information about used styles.

/**
 * Extracts critical CSS from rendered HTML string
 * @param html - The rendered HTML string containing emotion class names
 * @returns Object containing the original HTML, extracted CSS, and style IDs
 */
function extractCritical(html: string): EmotionCritical;

interface EmotionCritical {
  /** The original HTML string */
  html: string;
  /** Array of emotion style IDs found in the HTML */
  ids: Array<string>;
  /** The critical CSS styles as a string */
  css: string;
}

Usage Example:

import React from 'react';
import { renderToString } from 'react-dom/server';
import { extractCritical } from 'emotion-server';
import { css } from 'emotion';

const MyComponent = () => (
  <div className={css`background: red; padding: 10px;`}>
    Content
  </div>
);

const { html, css: criticalCss, ids } = extractCritical(
  renderToString(<MyComponent />)
);

// Use the extracted CSS for hydration or performance optimization
console.log('Critical CSS:', criticalCss);
console.log('Style IDs for hydration:', ids);

Inline Style Rendering

Renders emotion styles directly inline into HTML by injecting <style> tags with appropriate attributes.

/**
 * Renders emotion styles inline into HTML string by injecting style tags
 * @param html - The rendered HTML string containing emotion class names
 * @returns HTML string with inlined style tags containing emotion CSS
 */
function renderStylesToString(html: string): string;

Usage Example:

import React from 'react';
import { renderToString } from 'react-dom/server';
import { renderStylesToString } from 'emotion-server';
import { css } from 'emotion';

const MyComponent = () => (
  <div className={css`color: blue; margin: 20px;`}>
    Styled content
  </div>
);

const htmlWithStyles = renderStylesToString(
  renderToString(<MyComponent />)
);

// Send this HTML to the client - styles are already inline
res.send(`<!DOCTYPE html><html><body>${htmlWithStyles}</body></html>`);

Stream-Based Style Rendering

Creates a Node.js transform stream that automatically inlines emotion styles during streaming server-side rendering.

/// <reference types="node" />

/**
 * Creates a Node.js transform stream that inlines emotion styles on-the-fly
 * @returns A readable/writable stream that processes HTML and injects emotion styles
 */
function renderStylesToNodeStream(): NodeJS.ReadWriteStream;

Usage Example:

import React from 'react';
import { renderToNodeStream } from 'react-dom/server';
import { renderStylesToNodeStream } from 'emotion-server';
import { css } from 'emotion';

const MyComponent = () => (
  <div className={css`background: green; height: 100px;`}>
    Streaming content
  </div>
);

// Create the style injection stream
const styleStream = renderStylesToNodeStream();

// Pipe React's node stream through the emotion style stream
renderToNodeStream(<MyComponent />)
  .pipe(styleStream)
  .pipe(response);

Error Handling

emotion-server functions expect properly rendered HTML strings containing emotion class names. Common issues include:

  • Missing emotion classes: Functions will return empty CSS if no emotion styles are found
  • Invalid HTML: Malformed HTML may cause regex parsing issues
  • Cache mismatches: Ensure the same emotion cache is used for rendering and server-side processing

Platform Compatibility

  • Node.js: Primary target platform for server-side rendering
  • Browser: Limited browser support via browser-specific build (emotion-server.browser.cjs.js)

Dependencies

  • create-emotion-server: Core implementation providing server-side rendering functionality
  • emotion: Peer dependency providing the CSS-in-JS cache and styling system