Porsche Design System

Astro

Table of Contents

Quick start
Integration
Astro + Vue (optional)

Quick start#

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

astro@6

vue@3

tailwindcss@4

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

# Create a new application by executing:
npm create astro@latest

# Follow the installation wizard to set everything up:
✔ Where should we create your new project?: "./my-app"
✔ How would you like to start your new project?: "A basic, helpful starter project"
✔ Install dependencies?: "Yes"
✔ Initialize a new git repository?: "Yes"

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-js

Step 2

Integrate the Porsche Design System Loader into the <body> section of your HTML.

// src/layouts/Layout.astro

---
+ import { getLoaderScript } from '@porsche-design-system/components-js/partials';
---
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width" />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
    <meta name="generator" content={Astro.generator} />
    <title>Astro Basics</title>
  </head>
  <body>
    <slot />
+   <Fragment set:html={getLoaderScript()} />
  </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).

/* src/styles/global.css */

+ @import '@porsche-design-system/components-js';

Import the CSS file in your project.

// src/pages/index.astro

---
+ import '../styles/global.css';
---

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

// astro.config.mjs

// @ts-check
import { defineConfig } from "astro/config";
+ import { Features } from 'lightningcss';

// https://astro.build/config
export default defineConfig({
+  vite: {
+    css: {
+      transformer: 'lightningcss',
+      lightningcss: {
+        exclude: Features.LightDark,
+      },
+    },
+  },
});

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)). See Initialization for more details.

/* src/styles/global.css */
@import '@porsche-design-system/components-js';

+ :not(:defined) {
+   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.

// src/layouts/Layout.astro

---
+ import { getComponentChunkLinks, getFontLinks, getIconLinks, getLoaderScript, getMetaTagsAndIconLinks } from '@porsche-design-system/components-js/partials';
---
<!doctype html>
  <html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width" />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
    <meta name="generator" content={Astro.generator} />
    <title>Astro Basics</title>
+   <!-- preloads fonts -->
+   <Fragment set:html={getFontLinks()} />
+   <!-- preloads icons -->
+   <Fragment set:html={getIconLinks()} />
+   <!-- preloads components -->
+   <Fragment set:html={getComponentChunkLinks()} />
+   <!-- injects favicon, apple touch icons, android touch icons, etc. -->
+   <Fragment set:html={getMetaTagsAndIconLinks({ appTitle: 'Porsche' })} />
  </head>
  <body>
    <slot />
    <Fragment set:html={getLoaderScript()} />
  </body>
</html>

Step 5 (recommended)

Setting up Tailwind CSS with the Porsche Design System Tailwind CSS Theme allows you to use a utility-first CSS framework that guarantees seamless styling consistency with Porsche's design principles.

Install Tailwind CSS within your project directory.

npm install tailwindcss @tailwindcss/vite

Configure the Vite plugin.

// astro.config.mjs

// @ts-check
import { defineConfig } from "astro/config";
+ import tailwindcss from "@tailwindcss/vite";

// https://astro.build/config
export default defineConfig({
+ vite: {
+   plugins: [tailwindcss()],
+ },
  …
});

Import Tailwind CSS and the Porsche Design System Tailwind CSS Theme.

/* src/style.css */
@import '@porsche-design-system/components-js';

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

Step 6

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

// src/components/Welcome.astro

---
import astroLogo from '../assets/astro.svg';
import background from '../assets/background.svg';
---
<div class="grid justify-items-center gap-fluid-md m-static-lg p-fluid-lg bg-surface rounded-lg">
  <p-wordmark></p-wordmark>
  <h1 class="prose-heading-4xl">Porsche Design System</h1>
</div>
<div id="container">…</div>

Astro + Vue (optional)#

To add Vue to your Astro project, install the official integration and configure your project. You should have already completed the steps in the Quick Start and Integration sections.

# Install the official Astro integration for Vue:
npx astro add vue

# Follow the installation wizard to set everything up:
✔ Astro will make the following changes to your config file: "Yes"
✔ Astro will make the following changes to your tsconfig.json: "Yes"

Step 1

Configuring astro.config.mjs to support Porsche Design System components in Vue requires adding a specific configuration to your Vue integration.

// astro.config.mjs

import vue from '@astrojs/vue';
import { defineConfig } from 'astro/config';
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
+ integrations: [
+   vue({
+     template: {
+       compilerOptions: {
+         isCustomElement: (tag) => tag.startsWith('p-'),
+       },
+     },
+   }),
+ ],
  vite: {
    …
  },
});

Step 2

Create a new Vue component file, for example, Welcome.vue with a Porsche Design System component (e.g. <p-wordmark></p-wordmark>) and some Tailwind CSS styles.

// src/components/Welcome.vue

<template>
  <div class="grid justify-items-center gap-fluid-md m-static-lg p-fluid-lg bg-surface rounded-lg">
    <p-wordmark></p-wordmark>
    <h1 class="prose-heading-4xl">Porsche Design System</h1>
    <p class="prose-text-sm">Astro + Vue</p>
  </div>
</template>

Step 3

Next, include this new Vue component in one of your Astro pages (e.g. src/pages/index.astro). Then, run npm run dev and verify that the component and styles display correctly.

// src/pages/index.astro

---
import Welcome from '../components/Welcome.astro';
+ import WelcomeVue from '../components/Welcome.vue';
import Layout from '../layouts/Layout.astro';
---

<Layout>
+ <WelcomeVue />
  <Welcome />
</Layout>