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@5

vue@3

tailwindcss@4

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

# 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 (recommended)

To boost your web application's performance and minimize issues like FOUC (Flash of Unstyled Content) and FOUT (Flash of Unstyled Text), you can integrate Partials from the Porsche Design System into the <head> section of your HTML.

// src/layouts/Layout.astro

---
+ import { getComponentChunkLinks, getFontFaceStyles, getFontLinks, getIconLinks, getInitialStyles, 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>
    <!-- injects stylesheet which defines visibility of pre-hydrated PDS components -->
+   <Fragment set:html={getInitialStyles()} />
    <!-- injects stylesheet which defines Porsche Next CSS font-face definition (=> minimize FOUT) -->
+   <Fragment set:html={getFontFaceStyles()} />
    <!-- preloads Porsche Next font (=> minimize FOUT) -->
+   <Fragment set:html={getFontLinks()} />
    <!-- preloads PDS component core chunk from CDN for PDS component hydration (=> improve loading performance) -->
+   <Fragment set:html={getComponentChunkLinks()} />
    <!-- preloads Porsche icons (=> minimize FOUC) -->
+   <Fragment set:html={getIconLinks()} />
    <!-- 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 4 (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.

The Key Advantage: Universal Code Sharing & Scalability

Using Tailwind CSS with the Porsche Design System Theme provides a powerful benefit: Your styles are truly framework-agnostic. Since Tailwind generates atomic utility classes, you eliminate cascading style issues, promoting long-term scalability and maintainability for large projects. The patterns and components you build are easily portable. You can copy and paste the same styling code between projects, teams, and different technology stacks (React, Angular, Vue, plain HTML, etc.), ensuring 100% visual uniformity across the organization. You can now use and customize the provided Patterns and Templates, which are all written in Tailwind CSS, to build applications quickly and efficiently.

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: {
+   // @ts-expect-error: The types are currently mismatched due to conflicting Vite versions (Astro and the Tailwind CSS Vite plugin are using different versions of Vite)
+   plugins: [tailwindcss()],
+ },
});

Create global.css file, import Tailwind CSS and the Porsche Design System Tailwind CSS Theme.

/* src/styles/global.css */

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

Start using Tailwind CSS in your project.

// src/pages/index.astro

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

Step 5

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-display-md">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: {
    // @ts-expect-error: The types are currently mismatched due to conflicting Vite versions (Astro and the Tailwind CSS Vite plugin are using different versions of Vite)
    plugins: [tailwindcss()],
  },
});

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-display-md">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>