@aesop-engineering/gel
v5.78.0
Published
UI Component Library and Design System for Aēsop.com
Downloads
167
Maintainers
Keywords
Readme
Aesop Global Experience Language
Tooling Requirements
- Node https://nodejs.org/ (required version recorded in the .nvmrc file)
- TypeScript https://www.typescriptlang.org/
Tooling Suggestions
- Homebrew https://brew.sh/
- Node Version Manager https://github.com/nvm-sh/nvm
It is also recommended to install these plugins into your IDE / Code Editor of choice:
- TypeScript
- Base linter (atom only)
- Editor Config (atom)
- ESLint (atom) (vscode)
- Linter UI (atom only)
- Prettier (atom) (vscode)
- StyleLint (atom) (vscode)
Usage
Install in your application using the following command
# to use the most recent stable version
npm install @aesop-engineering/gel --save
# to use an in-development branch
npm install github:aesop/aesop-gel#feature/your-branch --save
Import the component/hook/etc that you need in your code
import { Heading } from 'aesop-gel/dist/components/Heading'; // or from '@aesop-engineering/gel/dist/components/Heading';
// example usage
const MyAppHeading = () => (
<Heading theme="dark" level="1" size="large">
This is a large H1
</Heading>
);
All exposed components, hooks, contexts, types and utilities can be reviewed here
Application Architecture
TBA
Development
nvm use && npm ci && npm start
While using a consuming application
You can use the npm link
command to actively develop on Aesop Gel and have the changes reflected in your consuming app.
# run inside aesop-gel to create a global link to be used
npm link
# run inside aesop-gel to get a link to the consumer's react
npm link ../aesop-web-ui/node_modules/react
# run inside aesop-web-ui to use your local aesop-gel build
npm link @aesop-engineering/gel
# finally run this to update the built files on changes
npm run build-watch
VS Code
Visual Studio code struggles to make sense of aliased imports which are being utilised in this project.
To address this you can use a jsconfig.json
with a sample shown below. More information can be found here
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"~/*": ["./src/*"]
}
},
"exclude": ["node_modules", "dist"]
}
Production
Rollup builds ES Modules for this project. The following command will also construct the Typescript declaration files.
npm run build
Git Workflow
This project adopts a simplified version of the Gitflow Workflow.
feature
(or update
, or bugfix
where appropriate) branches are branched from develop
, and are merged back into develop
after an approved Pull Request.
hotfix
branches can be merged into main
if they originate from main
.
main
is always the updated stable version that truthfully represent production code.
Releasing code
This project follows the Semantic Versioning standard or MAJOR.MINOR.PATCH
. The version number is automatically maintained by the semantic-release package.
Commits to the develop
branch will be released on the develop
channel. These will be tagged as follows v1.2.3-develop.4
. These can be thought of as 'beta' builds. The final number .4
in the example above will be incremented until the develop
branch is merged into main
.
When develop
is merged into main
a release will be created. These will be tagged as v1.2.3
.
These versions can be referenced in other projects by adding "aesop-gel": "github:aesop/aesop-gel#1.2.3",
to the package.json
file. Generally the main
releases should only be used. However during development and testing it may make sense to use the develop
or 'beta' builds.
Changes to the version number are calculated automatically via the CI flow. In short commits with a feat
type will increment the minor
version, commits with a fix
type will increment the patch
version.
See Commit messages below for more information.
Commit messages
Commit messages follow the Conventional commits. Details about each commit message type are explained in this article. The basis of this is built around type(scope?): subject
and is enforced by commitlint.
Examples
feat(AES-123): add XComponent section
fix: issue with XComponent CSS
style: clean up whitespace issues
Breaking changes
Breaking changes should generally avoid, however they can be made in two ways;
- by adding
!
after the commit typefeat(aes-123)!: change all the APIs!
- by adding
BREAKING CHANGE
in the commit body
feat(aes-123): change all the APIs!
BREAKING CHANGE: The APIs have all been rewritten because I felt like it
Valid commit types
build
ci
chore
docs
feat
fix
perf
refactor
revert
style
test
Testing
Real-time testing feedback
npm run test-watch
Component Snapshots
To run Jest snapshots on all component files with a .spec.js
file, run:
npm run test
To update existing snapshots for components where their markup changes, run:
npm run test -- -u
UI and Design Testing
Story Book is used to visually test and showcase components. Run the following to build the storybook files and serve them on http://localhost:6006/?path=/story/*
:
npm start
More on testing with the Testing Readme
Code Integrity
Commenting
It is encouraged to write code that is Self-documenting, where as through functional programming, intelligent naming, and clearly laid out code intuitively describes what the code does.
In the event of more complex code, @TODO
statements or tslint / eslint ignores, use double slash for single line comments that relate to a block of code. Slightly different for css:
// single line comment about the following code block
function add(a, b) {
return a + b;
}
/* single line comment about the following code block */
.base {
color: pink;
}
double slash for single line comments to the right of a single statement:
const add = (a, b) => a + b; // single line comment about this statement
.base {
/* single line comment about this statement */
color: pink;
}
and JSDoc format for multi line comments:
/**
* multi line comment
* about the following code block
*/
function add(a, b) {
return a + b;
}
/**
* multi line comment
* about the following code block
*/
.base {
color: pink;
}
Linting & Formatting
The repo uses the following libraries to enforce code quality:
To run the ESLint/Stylelint/Prettier task, use either:
# to check the code matches the set rules without fixing issues
npm run tool-check # where "tool" is one of eslint, stylelint, prettier, e.g. npm run eslint-check
# to fix fixable issues
npm run tool-fix
To run all of them with one script, use either:
npm run code-standard-check
npm run code-standard-fix
In regards to typing React components, use React+TypeScript Cheatsheets as a reference. (Thank you @kevin-ho87)
Pre Commit Hook
Husky is used to automatically run npm run format
as a pre-commit hook, ensuring changes to
source files follow the same formatting. The configurations of Husky is found in .huskyrc.
.huskyrc
{
"hooks": {
"pre-commit": "npm run pretty"
}
}
Issues
Code issues, update requests and development improvements that do not have a JIRA ticket should be made via an issue submission.
Any @TODO
s in the code base should have a corresponding issue submission.
Contributing
Component directory generator
Use the generate-component
script to generate the new files for a new component:
npm run generate-component $component-name <$component-type>
The $component-name
is required, where as the optional $component-type
will generate a component as one of the following options:
ref
- A functional component wrapped in React’sforwardRef
higher order function.withoutChildren
- A functional component that does not accept achildren
prop.withChildren
(default) - A functional component that does accept achildren
prop.
For example:
npm run generate-component Button
npm run generate-component Icon withoutChildren
npm run generate-component Map ref
Pull Requests for any new feature, bug fix or update need to be made with the PR template provided via a New Pull Request. Every PR needs to be Peer Reviewed before it can be merged.