Porsche Design System

Next.js

Table of Contents

Global Theme
SSR
Prefixing

Global Theme#

All system colors are controlled via the CSS color-scheme property and are included in our mandatory Global Styles. These styles also provide utility classes for selecting the active theme and a polyfill to ensure compatibility with browsers that do not yet support light-dark() (see browser support).

By default, color tokens use the light theme. To enable the dark theme or automatic theme switching based on system settings, add the .scheme-light, .scheme-dark or .scheme-light-dark CSS class to the <html> element or any HTML element. This applies the selected theme to all child elements.

Learn more in the Theme section.

SSR#

The sub-package @porsche-design-system/components-react/ssr is a specialized build of the Porsche Design System components that renders different markup on the server compared to the browser. While this deviates from traditional SSR/SSG rules (where browser and server markup should be identical), it's necessary to enable SSR/SSG with web components and Shadow DOM.

The two environments are detected via the process.browser flag, which is replaced with a boolean value at build time. In the browser, the components behave like the standard React components from @porsche-design-system/components-react.

On the server, the behavior differs: Relevant markup and styles are rendered into a Declarative Shadow DOM, which modern browsers convert to a real Shadow DOM without JavaScript. This handles the initial render efficiently. Once the client code loads and executes, the Porsche Design System components initialize as usual.

Important: Ensure dead code elimination is enabled for the client build to prevent server-side code from leaking into the browser bundle.

Prefixing#

In case of a micro-service architecture, multiple instances and versions of the Porsche Design System can be combined in a final application. This could cause conflicts due to the way how custom webcomponents are registered in the browser. During the bootstrap phase of the Porsche Design System, custom elements are defined. If a second application wants to register Porsche Design System again it will cause issues especially when different versions are used.

A way of preventing those conflicts is by using a unique custom prefix for the components. Simply pass your desired prefix to the prefix property of PorscheDesignSystemProvider.

// app/layout.tsx
import { PorscheDesignSystemProvider } from '@porsche-design-system/components-react/ssr';

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <head></head>
      <body>
        <PorscheDesignSystemProvider prefix="sample-prefix">{children}</PorscheDesignSystemProvider>
      </body>
    </html>
  );
}

In the following example the PHeading component will render as <sample-prefix-p-heading>.

// app/page.tsx
import { PHeading } from '@porsche-design-system/components-react/ssr';

export default function Home() {
  return <PHeading>Some heading</PHeading>;
}