The gel-next's intro from ryanmills

Getting Started

This section describes how to get started with Westpac GEL.

What is GEL?

The Global Experience Language is our single source of truth, providing everything you need to deliver our brand promises and create consistent, coherent customer experiences across our entire digital landscape faster, and with less effort.

You can read more about GEL in https://gel.westpacgroup.com.au/articles/what-is-GEL

Pre-requisites

All GEL components have a couple of dependencies so please ensure the following are installed:

npm i react@^18.2.0
npm i -D tailwindcss postcss autoprefixer

GEL is using Tailwind for styling. Visit the Tailwind docs to learn more about installation and usage.

Installation

GEL can be installed using a package manager like npm, yarn or pnpm.

npm i @westpac/ui

Update tailwind.config.js to use the withGEL helper exported by @westpac/ui as follows.

import { withGEL } from '@westpac/ui/tailwind';

/** @type {import('tailwindcss').Config} */
const config = withGEL({
  relative: true,
  content: ['./src/**/*.{js,ts,jsx,tsx,mdx}', './node_modules/@westpac/ui/src/**/*.{js,ts,jsx,tsx,mdx}'],
  safelist: [],
});

export default config;

For applications using brand fonts add the following options config to the withGEL helper.

const config = withGEL({
  relative: true,
  content: ['./src/**/*.{js,ts,jsx,tsx,mdx}', './node_modules/@westpac/ui/src/**/*.{js,ts,jsx,tsx,mdx}'],
  safelist: [],
  options: {
    brandFonts: {
      src: '/fonts', // path to font files
      brands: ['wbc', 'stg'], // takes a single brand string e.g. 'wbc' or an array of brands. If no brands are specified will import all brands by default
    },
  },
});

Usage

Using brands

Add a custom attribute tag data-theme="brand_name" to html tag. Note that instead of adding the custom attribute to html tag, you can add it to the parent tag of your application as well.

Following example shows adding wbc theme. You can add other valid brand names such as stg, bom, bsa, rams, wbg etc. as the value.

<!doctype html>
<html lang="en" data-theme="wbc">
  ...
</html>

NOTE: There are some components that use portals Modal, BottomSheet, AutoComplete. These components will default their portal to where you add your data-theme attribute tag so these components can make use of branding. This can be overridden using their portalContainer props if you require the portal to be located elsewhere.

Now you can start using the GEL components in your React.js application. The following examples show how to use the Button component.

For detailed documentation refer to https://gel.westpacgroup.com.au/design-system.

Individual package import

We recommended the individual package import approach if you have issues with Tree shaking.

import { Button } from '@westpac/ui/button';

export default function SampleApp() {
  return (
    <section>
      <div className="space-x-4 mb-2">
        <Button look="primary">Pay here</Button>
      </div>
    </section>
  );
}

Mono package import

Modern bundlers like Vite will automatically detect the individual components and only bundle the components you use.

However, use this approach with caution as it may cause issues with Tree shaking since not all bundlers have this advanced capability.

import { Button } from '@westpac/ui';

export default function SampleApp() {
  return (
    <section>
      <div className="space-x-4 mb-2">
        <Button look="primary">Pay here</Button>
      </div>
    </section>
  );
}

Unit testing

We recommend Vitest for unit testing since Vitest natively supports ES modules.

If you are using Jest for unit testing, you might encounter some issues since Jest does not support ES modules by default. Therefore, you will need to make following configuration changes to the Jest configuration file.

// jest.config.ts
const customJestConfig = {
  transform: {},
  extensionsToTreatAsEsm: ['.ts', '.tsx'],
};

Add the below to package.json

{
  "scripts": {
    "test": "NODE_OPTIONS=--experimental-vm-modules jest"
  }
}

Documentation

Visit https://gel.westpacgroup.com.au/design-system to view the full documentation.

Contributing to GEL

Developing

The development branch is develop.
All pull requests should be opened against develop.
The changes on the develop branch are published to the preview environment.

To develop locally (common for all the packages and apps)

Install Node.js 18.x or above. We recommend https://github.com/nvm-sh/nvm to install Node.js.

Clone the Next.js repository:

git clone --single-branch --branch develop [email protected]:WestpacGEL/GEL-next.git

Create a new branch:

git checkout -b MY_BRANCH_NAME origin/develop

Enable pnpm:
```
corepack enable pnpm
```
Install the dependencies with:
```
pnpm install
```
Start developing and watch for code changes:
```
pnpm dev
```
Run the unit tests with:
```
pnpm test
```
Fix formatting and linting with:
```
pnpm format:fix && pnpm lint:fix
```
Check formatting and linting with:
```
pnpm format && pnpm lint
```
Check TypeScript compatibility with:

pnpm check-types

You can build packages and apps with:

pnpm build

You can add a changeset with:

pnpm changeset

To develop a GEL UI component locally

Change the working directory with:
```
cd packages/ui
```
Create a new GEL component with:
```
cd packages/ui
pnpm generate:component
```
Start storybook with:
```
pnpm build && pnpm storybook
```
Run the unit tests in watch mode with:
```
pnpm test:watch
```
When your changes are finished, commit them to the branch and push it to origin.

ryanmills / gel-next Goto Github PK

gel-next's Introduction

Getting Started

What is GEL?

Pre-requisites

Installation

Usage

Using brands

Individual package import

Mono package import

Unit testing

Documentation

Contributing to GEL

Developing

To develop locally (common for all the packages and apps)

To develop a GEL UI component locally

Recommend Projects

React

Vue.js

Typescript

TensorFlow

Django

Laravel

D3

Recommend Topics

javascript

web

server

Machine learning

Visualization

Game

Recommend Org

Facebook

Microsoft

Google

Alibaba

D3

Tencent