draekien-ui v2.19.0

Draekien-UI

• Introduction
• Storybook
• Getting Started
  • Install and Consume
  • Custom Themes
  • Using a component
• Contributing
  • Overview
  • Tech Stack
  • Dev tools
  • Component Folder Structure
  • Committing changes
  • Structure
  • Examples
    • Commit message with description and breaking change in body
    • Commit message with optional ! to draw attention to breaking change
    • Commit message with no body
    • Commit message with scope
    • Commit message for a fix using an (optional) issue number.
• Available Scripts
  • npm start
  • npm run start-storybook
  • npm test
  • npm run test-update
  • npm run test-watch
  • npm build
  • npm run build-storybook
  • npm run build-all
  • npm release
  • npm run release-chromatic
  • npm run lint

Introduction

This is just a personal project to create a UI library based on Theme-UI and to learn about CI/CD and eventually deploying to NPM, kindly supported by JetBrains

Storybook

This project deploys a storybook to Chromatic. Click here to view the latest.

The above link will take you away from Github

Getting Started

Check out this example repository that uses Draekien-UI: draekien-ui-sample

Install and Consume

In your react app, run npm install --save draekien-ui

To consume DraekienUi, you must import the DraekienUi component and wrap your code in this component.

in your index.tsx

// ... other imports
import { BrowserRouter as Router } from 'react-router-dom';
import { DraekienUi } from 'draekien-ui';

function Main() {
  return (
    <DraekienUi>
      <Router>
        <App />
      </Router>
    </DraekienUi>
  );
}

ReactDOM.render(<Main />, document.getElementById('root'));

As of v2.0.0 if you want to use the Button component with relative paths, you will need to install react-router-dom using npm install --save react-router-dom

Custom Themes

All it takes to use your own theme is to pass in a theme object to the DraekienUi theme prop. The theme passed in must be of type ThemeType, which is importable from the draekien-ui library. The theme that is passed in with be merged with the default draekien-ui theme.

the following example will override the p-400 color and set it to purple, while the rest of the theme will use the DraekienUi default theme.

// ... other imports
import { BrowserRouter as Router } from 'react-router-dom';
import { DraekienUi } from 'draekien-ui';

function Main() {
  return (
    <DraekienUi theme={{ colors: { 'p-400': 'purple' } }}>
      <Router>
        <App />
      </Router>
    </DraekienUi>
  );
}

ReactDOM.render(<Main />, document.getElementById('root'));

Using a component

All components are centralized in the main module. This means you can do the below to import a component from the main module

import React from 'react';
import { Button } from 'draekien-ui';

const Element: React.FC = () => {
  return <Button onClick={() => {}}>Click me!</Button>;
};

export default Element;

Contributing

Overview

Clone the repository

git clone https://github.com/draekien/draekien-ui.git cd draekien-ui

Install dependencies

npm i

Checkout a new feature branch

# replace <YOUR_BRANCH_NAME> with the name of the branch you want to checkout
git checkout -b feature/<YOUR_BRANCH_NAME>

typey typey, then commit your changes using git-cz or npm run commit and push your branch to remote

Take a look at Committing changes to find out why we use git-cz

# replace <YOUR_BRANCH_NAME> with the name of the branch you want to checkout
git push --set-upstream origin feature/<YOUR_BRANCH_NAME>

make a PR to merge your changes into master and wait for a review.

# if you have the Github CLI
gh pr create --web

Tech Stack

• Storybook: Used to render component examples in isolation
• Typescript: A typed superset of JavaScript that compiles to plain JavaScript
• Jest: JavaScript testing framework
• React testing libary: For testing react components alongside Jest

Dev tools

Please install the following dev tools to make your development experience better when working on draekien-ui

• EditorConfig: this is just a file placed in our project's root folder, which defines the code style for the project, If you are using VS Code, just paste the following: publisher:"EditorConfig" in the extensions searchbar and install the EditorConfig for VS Code

• Prettier: A formatter for JS/TS code. Is highly recommended to install the Prettier - Code formatter extension by Esben Petersen to set Prettier as your formatter in VS Code, it will take the configuration defined in the .prettier.config.js file in the root folder.

• ESLint: A linter for our TS code. Get the ESLint plugin by Dirk_Baeumer to integrate ESLint with VS Code.

Component Folder Structure

Example of a component folder

components
  ├── ... other components
  ├── button                          # or your component name
  │     ├── tests
  │     │   ├── __snapshots__
  │     │   ├── index.styles.test.ts  # style unit tests, if applicable
  │     │   └── index.test.tsx        # component unit tests
  │     ├── index.stories.tsx         # this renders the component for storybook
  │     ├── index.styles.ts           # css-in-js styles
  │     └── index.tsx                 # component code
  └── index.ts

Committing changes

This repo follows the conventional git format and this rule is enforced by a git hook.

We use Commitizen to guide you through Git commit wizard and gives commit messages a proper structure, which is essential for semantic-release step. Easiest way to generate a compliant commit message is to run npm run commit.

Structure

The commit contains the following structural elements, to communicate intent to the consumers of your library:

1. fix: a commit of the type fix patches a bug in your codebase (this correlates with PATCH in semantic versioning).
2. feat: a commit of the type feat introduces a new feature to the codebase (this correlates with MINOR in semantic versioning).
3. BREAKING CHANGE: a commit that has the text BREAKING CHANGE: at the beginning of its optional body or footer section introduces a breaking API change (correlating with MAJOR in semantic versioning). A BREAKING CHANGE can be part of commits of any type.
4. Others: commit types other than fix: and feat: are allowed, for example @commitlint/config-conventional (based on the Angular convention) recommends chore:, docs:, style:, refactor:, perf:, test:, and others. A scope may be provided to a commit’s type, to provide additional contextual information and is contained within parenthesis, e.g., feat(parser): add ability to parse arrays.

Examples

Commit message with description and breaking change in body

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

Commit message with optional ! to draw attention to breaking change

chore!: drop Node 6 from testing matrix

BREAKING CHANGE: dropping Node 6 which hits end of life in April

Commit message with no body

docs: correct spelling of CHANGELOG

Commit message with scope

feat(lang): add polish language

Commit message for a fix using an (optional) issue number.

fix: correct minor typos in code

see the issue for details on the typos fixed

closes issue #12

Available Scripts

npm start

Starts the storybook locally

npm run start-storybook

Starts the storybook locally with static file support

npm test

Run tests with coverage

npm run test-update

Run tests and update snapshots

npm run test-watch

Run tests in watch mode (usefull for testing during development)

npm build

Runs linter and tests, then builds typescript

npm run build-storybook

Builds the storybook

npm run build-all

Runs the build and build-storybook scripts concurrently

npm release

Runs semantic release

npm run release-chromatic

Releases storybook to chromatic

npm run lint

Runs the linter