NextStyleProvider

import { NextStyleProvider } from '@uhg-abyss/web/next';

The NextStyleProvider is a specialized component designed for advanced customization of Next.js server-side rendering (SSR).

Note: For most Next.js applications, the standard ThemeProvider already has built-in support for Next.js SSR and is sufficient. Use NextStyleProvider only when you need one or more of the advanced features listed below.

Custom Cache Configuration: When you need fine-grained control over the Emotion cache
Multiple Style Domains: When working with micro-frontends or multiple isolated style contexts
Custom Style Injection: When you need to control exactly where and how styles are injected
Advanced CSP Settings: When implementing strict Content Security Policies requiring nonce values

Using NextStyleProvider

ThemeProvider's built-in SSR support

The standard ThemeProvider already includes built-in support for Next.js server-side rendering. For most applications, using ThemeProvider alone is sufficient:

// Basic Next.js setup with built-in SSR support
import { ThemeProvider } from '@uhg-abyss/web/ui/ThemeProvider';
import { createTheme } from '@uhg-abyss/web/tools/theme';

const theme = createTheme('uhc');

export default function App({ children }) {
  return <ThemeProvider theme={theme}>{children}</ThemeProvider>;
}

Using NextStyleProvider with ThemeProvider

When you need the advanced features, you'll use NextStyleProvider as a wrapper around ThemeProvider:

// app/layout.js or _app.js
'use client';

import { NextStyleProvider } from '@uhg-abyss/web/next';
import { ThemeProvider } from '@uhg-abyss/web/ui/ThemeProvider';
import { createTheme } from '@uhg-abyss/web/tools/theme';

const theme = createTheme('uhc');

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <NextStyleProvider
          cacheOptions={{
            key: 'my-nextjs-app',
            nonce: process.env.CSP_NONCE, // Example of advanced usage
          }}
        >
          <ThemeProvider theme={theme}>{children}</ThemeProvider>
        </NextStyleProvider>
      </body>
    </html>
  );
}

Cache options

The cacheOptions prop accepts the following properties from @emotion/cache:

interface CacheOptions {
  // Unique identifier for the cache / defaults to 'abyss'
  key?: string;

  // DOM node to insert styles before
  insertionPoint?: HTMLElement;

  // Array of stylis plugins for custom CSS processing
  stylisPlugins?: any[];

  // Nonce security attribute for CSP (important for secure Next.js apps)
  nonce?: string;

  // Vendor-specific CSS property prefixing
  prefix?: boolean;

  // Speedy mode for faster insertions (default: true in production)
  speedy?: boolean;
}

Key cache options

key: A unique identifier for the cache. This is crucial for Next.js applications, especially when using multiple instances of NextStyleProvider or when integrating with other styling solutions. Defaults to 'abyss' if not specified.
nonce: Provides a Content Security Policy (CSP) nonce for style elements. This is important for secure Next.js applications that implement strict CSP rules.
speedy: Controls Emotion's performance optimization mode:
- When true: Faster style insertion using CSSOM APIs but less readable CSS (default in production)
- When false: More readable CSS with better debugging but slower performance (default in development)
insertionPoint: Controls where in the DOM styles are inserted, which can be important for style precedence in complex Next.js applications with multiple styling solutions.
stylisPlugins: Enables custom CSS processing with Stylis plugins, useful for adding vendor prefixes or custom CSS transformations.

For more details on these options, refer to the Emotion Cache Documentation.

Compatibility notes

Next.js Versions: Compatible with both Next.js 13+ (App Router) and earlier versions (Pages Router)
Abyss Parcels: Not compatible with Parcels (use StyleRootProvider instead)
Other Frameworks: Specifically designed for Next.js; for other frameworks, use StyleRootProvider

ThemeProvider - Basic theme provider for most applications
StyleRootProvider - Advanced provider with Shadow DOM support for non-Next.js applications