Skip to content

How to set up the Design System Repo

Jump to bottom
Tom Tschiller edited this page Nov 14, 2024 · 8 revisions

How to set up the Design System Repository on your local device

No matter if you just joined the team or you only need to set up a new computer, the following instructions should guide you trough step by step.

First things first... We assume that you work as a developer in Swiss Post's IT department and that you have received a Windows device with local administrator privileges. If this is not the case, you must first order these privileges (and join the Swiss Post 📯). You can order them trough the Swiss Post's internal IT-Shop. The Link to the shop can be found in the Post-Web (intranet).

To make sure, you can work with our code and access the Swiss Post Design System repository, you need to prepare your local device. Follow the steps below, to set up everything...

If you need help with any of the following steps, ask one of the Design System core team developers for help.
You can find their names in the footer section on our Design System Documentation page.

Set up the Swiss Post proxy server

At Swiss Post we use a proxy server, which needs to be configured before you can start setting up your system.

  1. Go to the Swiss Post internal IT-wiki site.
  2. Click into the search field in the header.
  3. Enter the term proxy install and configuration and set the filter Space to Development Platform.
    The wanted link should now be displayed as first search result.
  4. Follow the steps on the page.

Set up your IDE

  1. Install a coding client
    ⭐ We recommend Visual Studio Code

    You are free to install any other coding client, as long as it can follow our contributing guidelines.
    Important tools it must support: editorconfig, prettier, eslint, etc.

  2. Install a git client
    ⭐ We recommend Github Desktop or Fork

Access the Swiss Post Design System repository

The Swiss Post Design System repository lives on Github, under the Swiss Post Open Source space. It's a public repository, so anybody can see it, fork it, open pull-requests, etc.

To get write access to the repository, you need a Github account. You can either use your private account or create a Swiss Post specific account (using your work e-mail address). Just keep in mind that everyone can see your comments, your commits, how you act and what you do within the repository.

  1. Create or update your Github Account
    ⭐ We recommend to use a private account, as you might want to use your post specific account for the Swiss Post Enterprise space (for example to access copilot) and you'll keep your commit history if you move on.
    ⭐ We recommend to use your full name in your profile (instead of a nickname nobody associates with you) and an appropriate profile picture

  2. As soon as your account exists, let one of your co-workers know about it, so she/he can give you access to the repository.

  3. When your account has been granted access to the repository, you can set up your git client:

    Set up Github Desktop
    1. Open Github Desktop
    2. Just follow the instructions to login to Github with your account.
    3. Click on «Clone a repository form the Internet...» on the right.
    Github Desktop - Let's get started!

    1. Define the «Local path» so it points to C:\work\swisspost\design-system.
      You may need to create those folders first.

    2. Choose swisspost/design-system within the «GitHub.com» tab.

    Github Desktop - Clone a repository
    1. You should now have a local copy of the repository on your hard drive and can start working with it.
    Set up Fork

    1. Open Fork

    2. Go to «File» -> «Preferences»

    3. Go to tab «General» and set everything like in the image below.

      Fork - Preferences General

    4. Go to tab «Git» and enter your account data.

      Fork - Preferences Git

    5. Go to Swiss Post Design System repository.

    6. Open the «Code» dropdown and copy the «HTTPS» git url.

      Github - Swiss Post Design System repository

    7. Go back to Fork

    8. Go to «File» -> «Clone» and set up everything like in the image below and click on «Clone»

    Fork - Clone
    1. You should now have a local copy of the repository on your hard drive and can start working with it.

Install and configure NodeJS and Package Managers

At Swiss Post, we often have to switch between projects that depend on different NodeJs versions and Package Managers. For this reason, it is important that we install NodeJs in such a way that we can switch from one version to another at any time. That's why we need a Node Version Manager.
⭐ We recommend NVM-Windows

First, however, we need to make sure to clean up your system from existing NodeJs installations and you also need to uninstall all existing Package Managers.

  1. Uninstall all your local NodeJS installations and custom Package Managers (pnpm, yarn).
  2. Make sure all shells (cmd, bash, powershell, etc.) are closed
  3. Go to NVM Releases and download the latest nvm-setup.zip file.
  4. Open the Zip file and execute the installer.
  5. Open a shell, navigate to the Design System repository root folder (e.g. C:\work\swisspost\design-system)
    run: nvm
    You should see the installed version and a «how to use it» message.
  6. run: nvm list
    You should see a message like «No installations recognised».
  7. run: nvm install lts to install the latest long-time-support version of NodeJS.
  8. run: nvm use lts to activate the before installed NodeJS version.
  9. run: node -v
    You should see the node version.
  10. Now we need to enable the experimental tool called Corepack, which is shipped together with NodeJS since version 16 (and was also backported to NodeJS v14). It allows us to install the wanted Package Manager specified within the field packageManager in a «package.json» file.
    run: corepack enable
  11. Now you can start installing the dependencies in our repository using pnpm.
    Notice: We have not installed pnpm so far, but thanks to Corepack, this is not necessary.
    run: pnpm bootstrap
    You should see a message like:
    «! Corepack is about to download https://registry.npmjs.org/pnpm/-/pnpm-9.3.0.tgz
    ? Do you want to continue? [Y/n]»    .
  12. enter: y and hit enter
    This will install all dependencies and build all the packages of the repository once.
  13. You're done, congrats!
    You can now start your work on our repository...

.env files

Some packages need secrets to run, for example the icons pacakge. These secrets are not checked into the repository (otherwise the whole world could see them) but are stored in .env files. There is a .template.env file that holds infos about what secrets are necessary. To get the values for these variables, ask a Design System Maintainer.

Helpful knowledge

Working with NVM

Action command
Get current NodeJS version nvm current
List installed NodeJS versions nvm list or nvm ls
Install a new NodeJS version nvm install <version>
(e.g. nvm install 20, nvm install lts, nvm install latest or nvm install 20.3)
Activate a different NodeJS verion nvm use <version>
Uninstall a specific NodeJS verion nvm uninstall <version>

Visit nvm-windows for more information.

Working with NodeJS

Action command
Get installed version node --version or node -v
Run script file node path/to/script.js

Visit nodejs.org for more information.

Working with pnpm

Action command
Get installed version pnpm --version or pnpm -v
Install all dependencies pnpm install or pnpm i

Visit pnpm.io for more information.

Clone this wiki locally