README
Draekien-UI
- Introduction
- Storybook
- Getting Started
- Contributing
- Available Scripts
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:
- fix: a commit of the type
fix
patches a bug in your codebase (this correlates withPATCH
in semantic versioning). - feat: a commit of the type
feat
introduces a new feature to the codebase (this correlates withMINOR
in semantic versioning). - 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 withMAJOR
in semantic versioning). A BREAKING CHANGE can be part of commits of any type. - Others: commit types other than
fix
: andfeat
: are allowed, for example @commitlint/config-conventional (based on the Angular convention) recommendschore:
,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
!
to draw attention to breaking change
Commit message with optional 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