NextJS - Sample integration with Porsche Design System

Introduction

This is project shows the example usage of the Porsche Design System Components in NextJS. See also the project documentation and the deployed project.

For further documentation regarding designing websites and the correct usage of the components, you can visit our website https://designsystem.porsche.com/.

---

Get the project up and running

yarn

• Install dependencies via yarn install
• Build the application via yarn build
• Run tests via yarn test
• Run the application via yarn start

---

Setup

Requirements

• Node.js
• Yarn
• Docker (see below)

Getting started

1. Clone sample-integration-nextjs repository
2. Switch to project root directory
3. Execute command npm login --registry=https://porscheui.jfrog.io/porscheui/api/npm/npm/
4. Enter username, password (Artifactory API Key, not Artifactory password!) and e-mail address when asked in terminal
5. Execute cat ~/.npmrc, find following line //porscheui.jfrog.io/porscheui/api/npm/npm/:_authToken= and copy the generated npm registry token from the file to your clipboard
6. Create an .env file within project root directory (never push this file to Git because it will contain secrets – by default it's ignored by .gitignore)
7. Add npm registry token in following format PORSCHE_NPM_REGISTRY_TOKEN=YOUR_TOKEN_GOES_HERE
8. Make sure that Docker app is running
9. Run ./docker.sh run-install - this may take up to several minutes at first start depending on your internet connection

Note: ./docker.sh run-install should be executed after every pull.

Setup prettier

1. Go to Webstorm Preferences
2. Click on the Plugins tab and search for prettier
3. Install prettier
4. In Preferences go to Languages and Frameworks -> Javascript -> Prettier
5. Set Prettier Package to {PATH_TO_YOUR_DIRECTORY}/node_modules/prettier
6. Change Run for files to {**/*,*}.{js,ts,jsx,tsx,vue,scss,json,css,html}
7. Click checkbox on save and apply
8. You should be good to go.

Docker installation steps

1. Register your Docker account on Hub-Docker
2. Download Docker app locally on your machine and login
3. Start Docker

Start

1. Switch to project root directory
2. Run ./docker.sh run-start (starts test server for sample-integration-nextjs itself)

Build

1. Switch to project root directory
2. Run ./docker.sh run-build (builds releasable sample-integration-nextjs npm package)

Test

1. Switch to project root directory
2. Run ./docker.sh run-test (executes test for sample-integration-nextjs)

Test the application

It is yet not possible to render our web components in jsdom.

To ensure your tests don't fail, we provide mocks for every Porsche Design System component. They are distributed in the @porsche-design-system/components-react npm package.

We consume the Mocks in the setupTest.js file in the root folder.

// setupTest.js

jest.mock('@porsche-design-system/components-react/ssr', () => {
    return require('@porsche-design-system/components-react/mocks');
});

You have to access the mocks in the Mock-Factory of the jest.mock() function. We have to use require because the mock factory doesn't allow otherwise.

Use this solution until there is an upgrades to a newer jsdom version which provides support for Web Components. In the meantime we keep providing mocks.

You find detailed information on how to use mock functions in Jest here.