PIE Web Components ‐ Vue Integration Guide

To install a PIE web component into a VueJS app we need to take the following steps:

1. Install the lit dependency
2. Install and set up @justeattakeaway/pie-css to get the design tokens and base CSS styles
3. Install PIE web components package @justeattakeaway/pie-webc
4. Configure Vite to recognise PIE components as custom elements

Step 1: Installing Lit

At the time of writing this guide, the version of Lit we use is 3.1.2. This is likely to change, however. As a general rule of thumb, please install the same version/major version as used in our components. You can find out the currently used version either here in the project root package.json or possibly in a component package.json file such as here in the future.

To install Lit, simply run:

yarn add [email protected]

Or

npm install [email protected]

Step 2: Installing and setting up @justeattakeaway/pie-css

We use pie-css to house some base application styles our Web Components require to look correct.

First, install the package using:

yarn add @justeattakeaway/pie-css

Or

npm install @justeattakeaway/pie-css

We then need to import the CSS file into our application. Generally speaking, this can be achieved by importing it directly into the root JS file in your application. Please ensure it is one of the first stylesheets imported into your application, as this package provides the design tokens that the rest of your application styles should be consuming.

For example:

// main.ts
import '@justeattakeaway/pie-css/dist/index.css'; // <- the file to import
import './assets/main.css'

import { createApp } from 'vue'
import App from './App.vue'

createApp(App).mount('#app')

Typography

You will also need to set up the JET font families. We have created a guide on how to do this here. The code just needs to be placed in a location appropriate for your chosen web technology.

Step 3: Installing and integrating a PIE web components

First, we need to install @justeattakeaway/pie-webc package, pie-webc is a wrapper package which contains all PIE web components.

This means that after installing this package as a dependency, you can use as many PIE web components as you like, without bloating your application with unused code, or slowing it down with unnecessary component registrations in the browser.

To install pie-webc in your application, run the following on your command line:

yarn add @justeattakeaway/pie-webc

Or

npm install @justeattakeaway/pie-webc

Next, we want to add the component(e.g. button) to a page in our application. If your application has a root component that is rendered on every view, we only need to import the component into this file, then it will be available to any other subcomponent in your app. Otherwise, you import it the same way, just in the individual components that need it.

For Native JS Applications, Vue, Angular, Svelte etc.:

// App.vue
<script setup lang="ts">
import { PieButton } from '@justeattakeaway/pie-webc/components/button.js';
</script>

<template>
  <main>
    <h1>Check these awesome PIE components!</h1>
    <pie-button variant="destructive" size="large" @click="console.log('Clicked!')">Click me!</pie-button>
  </main>
</template>

<style scoped>
</style>

To use the component, simply use it in your component templates like you would any normal HTML and pass any props you may want.

Step 4: Configure Vite to recognise PIE custom elements

This will differ if you do not use Vite. However generally speaking you may need to configure your app bundler to recognise tags beginning with pie- as custom elements. Otherwise, you will get a console warning similar to this:

App.vue:6 [Vue warn]: Failed to resolve component: pie-button
If this is a native custom element, make sure to exclude it from component resolution via compilerOptions.isCustomElement.

To fix this, simply set up the Vue plugin in Vite to recognise PIE elements like so:

import { fileURLToPath, URL } from 'node:url'

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          // Check if the tag starts with 'pie-'
          isCustomElement: (tag) => tag.startsWith('pie-'), // <- this is where we show vite how to recognise PIE elements
        }
      }
    }),
  ],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url))
    }
  }
})