Swedbank Pay Design Guide

Installing / Getting started

The following guides are for further development of the Design Guide, and are not necessary if you only plan to use the Design Guide in your project.

Prerequisites

Design Guide requires Node.js (includes npm).

Installing

Open a terminal and navigate to repo root
npm ci
npm start
Go to http://localhost:3000
Works? If not, contact us on Slack (#design-guide-general – only available to Swedbank Pay and PayEx employees).
Get to work.

Set up Git Hooks

Open a terminal and navigate to repo root
Run git config core.hooksPath .githooks

Developing

It is important to note that as a developer, this project supports two brands: Swedbank Pay and PayEx. Webpack is configured to accept a brand flag which is used to collect different sets of theme variables. Swedbank Pay is default flag. E.g. npm start sets the theme to Swedbank Pay, while npm run start:payex sets the theme to … you guessed it, PayEx. Check out the package.json file for additional scripts.

Built with

React
Less

Setting up Dev

Running the command npm start starts the Webpack dev server, (which is configured in ~/webpack.config.js). If any changes is made to this file, or any files directly influencing this file (i.e. any loaders or plugins) you need to restart the server.
The script npm start will start the dev server in development mode. If you wish to run the dev server in production-like environment run the command npm run start:prod.

Importing components

When importing different components in the files you create, you can use shortcuts for common paths. The shortcuts are as following:

Shortcut	Description
`~`	root of the project (example `import package from "~/package";`)
`$`	`~/src`-folder (example `import dg from "$/scripts";`)
`@`	`~/src/App/components`-folder (example `import Alert from "@components/Alert";`)
`#`	`~/src/App/Documentation/utils`-folder (example `import { DocToc } from "@docutils";`)

The shortcuts are specified in the ~/.babelrc-file. Specifying the prefix-shortcuts in the ~/jsconfig.json-file enables path intellisense for the shortcuts (at least in VSCode).

Building

To start building, run the command npm run build to start in dev-mode, or npm run build:prod for production-mode. This will make webpack start bundling everything and make static files in the ~/dist/-folder. Also make sure all tests pass, or make changes to them accordingly.

Note: Running the command npm run build:prod will delete all files already located in ~/dist.

Versioning

Design Guide uses semantic versioning. This means that internally, Design Guide will use a major.minor.patch version number to signal what the changes in each release surmount to. This also means both CSS and JavaScript files are versioned in lockstep, so whenever a new version of the CSS is released, a new version of the JavaScript will be as well.

Tests

Open a terminal and navigate to repo root
Run the command npm test
- Many of the tests are snapshot based, and runs against already created snapshots. If you need to update the snapshots due to changes run the command npm run test:update.
- A test coverage report is generated after running the tests. This can be found in ~/coverage.

Note: Snapshot testing is pretty unforgiving, so if you make ANY changes to how a component, which already has a snapshot, is rendered, the tests WILL crash! So make sure to run npm run test:update before committing.

Code style

Coding style rules are set in ~/.eslintrc & ~/.stylelintrc.

Make sure to follow the syntax rules enforced by ESLint & Stylelint.

Contributing

Bug reports: File bugs as Github issues.
Feature suggestions: File as Github issue or discuss the feature on Slack (#design-guide-general).
Code contributions: Code contributions are highly encouraged, but discuss the feature/bugfix in an issue or on Slack before you start coding.

Creating a release

Before merging to master to create a release, make sure you follow these steps:

Make sure the linting (npm run lint) and unit tests pass (npm test).
Update the version in ~/package.json.
Make sure the changelog is correct (date and version) and only contains changes for the current release.
Update the version in the URL of the version-badge and version-tag at the bottom of this README.md file.
Commit the changes and create a pull request from your branch to develop.
When approved and merged, create a new pull request from develop to master.
When approved, rename the merge commit to Release x.x.x and merge.
Change branch to master.
Create and push a new tag with the new release commit.

AppVeyor will now create and deploy a release on both github and design.swedbankpay.com.

After pushing to master, create a pull request to develop that deletes the changelog content but keeps the headers.

Core development team

Contents of this project

Folder	Description
`~/coverage`	Test coverage report for the project (not commited to the repository).
`~/dist`	Static files generated by Webpack (not commited to the repository).
`~/src`	All the source files.
`~/build`	Config files for AppVeyor, and other files required for the AppVeyor build process.
`~/tools`	Various tools, mostly related to the build/deploy process.

Notable files

File	Description
`.babelrc`	Babel configuration.
`.eslintignore`	List of files/directories ESLint will ignore (similar to `.gitignore`)
`.eslintrc`	Eslint configuration.
`.sentryclirc`	Sentry configuration used by Webpack to configure a new release on sentry. (Do not* change the line `token = <token>`, as this placeholder is used by AppVeyor to insert the sentry api key.)*
`.stylelintrc`	Stylelint configuration.
`CHANGELOG.md`	Collection of changes made to the project. Insert your changes here.
`jest.config.js`	jest configuration.
`jest.setup.js`	Script file that will run before jest executes the tests, this includes enzyme setup, polyfills and other useful snippets.
`webpack.config.js`	Webpack configuration.

Copyright, license and credits

Inspired by Bootstrap and Materialize.

NullableInt/design.swedbankpay.com