@aesop-engineering/gel

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 type feat(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:

• Eslint
• Stylelint
• Prettier

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 @TODOs 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>

Source code

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’s forwardRef higher order function.
• withoutChildren - A functional component that does not accept a children prop.
• withChildren (default) - A functional component that does accept a children 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.