Porsche Design System

Next.js

Table of Contents

Quick start
Integration

Quick start#

To build a Next.js application using the Porsche Design System, follow these steps. This guide is based on the following dependencies:

next@16

react@19

tailwindcss@4

@porsche-design-system/components-react@4

# Create a new application by executing:
npx create-next-app@latest

# Follow the installation wizard to set everything up:
✔ What is your project named? "my-app"
✔ Would you like to use TypeScript? "Yes"
✔ Would you like to use ESLint? "Yes"
✔ Would you like to use Tailwind CSS? "Yes"
✔ Would you like your code inside a `src/` directory? "No"
✔ Would you like to use App Router? (recommended) "Yes"
✔ Would you like to use Turbopack for `next dev`?  "No"
✔ Would you like to customize the import alias (`@/*` by default)? "No"

You're all set! Start building your own application now.

Integration#

Step 1

Install the Porsche Design System within your project directory.

npm install @porsche-design-system/components-react

Step 2

Wrap your app with the <PorscheDesignSystemProvider />.

// app/layout.tsx

+ import { PorscheDesignSystemProvider } from '@porsche-design-system/components-react/ssr'; // ensure to import from ssr subpackage!

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

Step 3

Add the PDS Stylesheet to your main CSS file — this single import covers all required and recommended global styles (for websites primarily targeting users in China, use the /cn import instead, see China CDN).

/* app/globals.css */
+ @import '@porsche-design-system/components-react';

Disable the lightningcss polyfill for the light-dark() CSS function since it's broken. Learn more

// next.config.ts

const nextConfig: NextConfig = {
+  experimental: {
+    useLightningcss: true,
+    // disables light-dark() polyfill of lightningcss which is broken https://github.com/porsche-design-system/porsche-design-system/issues/4257
+    lightningCssFeatures: {
+      exclude: ['light-dark'],
+    },
+  },
};

To prevent FOUC, hide elements until they are either registered (:defined) or fully rendered by Stencil (.hydrated). If you run into issues with the :defined pseudo-class, scope the style to specific tags instead (e.g., :is(p-button, p-accordion, …):not(:defined,[data-ssr])). See Initialization for more details.

/* app/globals.css */
@import '@porsche-design-system/components-react';

+ :not(:defined,[data-ssr]) {
+   visibility: hidden;
+ }

Step 4 (recommended)

To improve your web application's loading performance, integrate Partials from the Porsche Design System into the <head> section of your HTML to preload fonts, icons, and component chunks.

// app/layout.tsx

import { PorscheDesignSystemProvider } from '@porsche-design-system/components-react/ssr'; // ensure to import from ssr subpackage!
+ import {
+   getComponentChunkLinks,
+   getFontLinks,
+   getIconLinks,
+   getMetaTagsAndIconLinks,
+ } from '@porsche-design-system/components-react/partials';

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <head>
+       {/* preloads fonts */}
+       {getFontLinks({ format: 'jsx' })}
+       {/* preloads icons */}
+       {getIconLinks({ format: 'jsx' })}
+       {/* preloads components */}
+       {getComponentChunkLinks({ format: 'jsx' })}
+       {/* injects favicon, apple touch icons, android touch icons, etc. */}
+       {getMetaTagsAndIconLinks({ appTitle: 'Porsche', format: 'jsx' })}
      </head>
      <body>
        <PorscheDesignSystemProvider>{children}</PorscheDesignSystemProvider>
      </body>
    </html>
  );
}

Step 5 (recommended)

Import Tailwind CSS and the PDS Tailwind CSS Theme — a utility-first setup that ensures seamless styling consistency with Porsche's design principles.

/* app/globals.css */
@import '@porsche-design-system/components-react';

+ @import 'tailwindcss';
+ @import '@porsche-design-system/components-react/tailwindcss';

Step 6

Add a Porsche Design System component (e.g., <PWordmark />) with some Tailwind CSS styles. Then, run npm run dev and verify that the component and styles display correctly.

// app/page.tsx

import { PWordmark } from '@porsche-design-system/components-react/ssr'; // ensure to import from ssr subpackage!

export default function Home() {
  return (
    <>
      <div className="grid justify-items-center gap-fluid-md m-static-lg p-fluid-lg bg-surface rounded-lg">
        <PWordmark />
        <h1 className="prose-heading-4xl">Porsche Design System</h1>
      </div>
      <div className="…">…</div>
    </>
  );
}