Skip to main content

Contributing

Before submitting a pull request, take a moment to review these guidelines.

Reporting issues​

Found a problem? Want a new feature?

Project installation​

The project is utilizing yarn workspaces containing reusable packages and a documentation website.

  • Clone the repository
  • Run yarn install from the root
  • Run yarn husky install from the root.

Husky provides the ability to format the code pre-commit. Non formatted PRs will be rejected.

Developing a component​

  • Create a file called App.tsx in /packages/frontend-ui/dev
  • Export a named React component called App:
import React from 'react';

export function App() {
  return <></>
}

  • This is your working file. The reason you need to create this is because App.tsx is your personal development file and it's gitignored.
  • When building a component, place it in the same top level folder (Atoms/molecules/etc...) as the Design System.
  • Sometimes multiple components (atoms) need to be composed into one bigger (molecule/organism). Previous point stands for this. Put atoms in atoms, molecules in molecules.

Naming conventions​

  • When a component is made up of a single React component, it is exported just by its name.
// Atoms/AtomicComponent/index.tsx
export function AtomicComponent() {...}
// Atoms/index.ts
export * from './AtomicComponent';
  • When a component is of a more complex nature (has sub components), it must have a Root component and must be exported as:
// Atoms/AtomicComponent/index.tsx
export function Root() {...}
export function SubComponent() {...}
// Atoms/index.ts
export * as Component from './AtomicComponent';

// Consumer file
import { Component } from '@streamelements/frontend-ui';
...
<Component.Root>
  <Component.SubComponent />
</Component.Root>

Documenting the component​

Documentation is provided under /packages/frontend-ui-docs/docs. This is not a part of the yarn workspace, just lives in the same repository.

  • The documentation website is structured in a way that is identical to the DS Figma file.
  • There are directories for all types of components.
  • Each component gets its own directory in the appropriate directory that it belongs to
  • Each component exports an index.mdx file with clear examples.
  • If a component has multiple states (see Switch or Checkbox), those states are displayed.
  • Each page for a component should be laid out in the same way as it is in the Figma document.
  • Each component should display a Props table
  • If a component is based on Radix, then the props that are commonly used are put in a props table, and a link to the radix docs for that particular component is also provided.

To add a page​

  • Create a directory with the component name in CamelCase under the proper component type directory (atoms/foundations/molecules...)
  • Create a fileName.md for your page
  • Example file declaration:
---
id: myFirstAtom
title: My First Atom
sidebar_label: My First Atom
slug: /atoms/myFirstAtom
---

Read more about this on the Docusaurus documentation website

  • Add your file to packages/frontend-ui-docs/sidebar.js under the appropriate category.
  • Run yarn build && yarn serve to confirm that the docs are building and everything looks and works well
    • You can run yarn start to run it in watch and non SSR mode

Check out the Routing docs to see how routing works in Docusaurus.

Submitting Pull Requests​

The way to add new features/components to the codebase is through pull requests.

To begin:​

Branch off of the development branch for your feature or fix

// make sure you are on development branch / checkout to development
git checkout development

// create your feature branch
git checkout -b feature/thingy

// create your bug fix branch
git checkout -b fix/thingy

Composable components​

Make sure your components are composable. This means no flags to enable/disable things, but rather you pick the things you need and combine them into something you want to have. Take a look at the Radix UI/Dropdown for a very nice and clear example.

Formatting​

We use ESLint in combination with Husky to run a linter pre-commit. Make sure your files are linted before submitting the PR.

Versioning​

Before releasing a stable version (x.y.z), changes are pushed onto a canary version. This canary version starts off as
next version + canary.x.
For example:

  • Current: 0.4.0
  • Next (assuming bumping patch): 0.4.1
  • During development, it will start off as 0.4.1-canary.0
  • During the development of 0.4.1, only the canary version is bumped: 0.4.1-canary.1
  • Each version bump is done in a separate commit named Release [version] @ [project]
    • For example Release 0.4.1-canary.1 @ frontend-ui

Take a look at the commit history and make a note of the Release X @ Y commits, to get a better picture of what the points mean.

You shouldn't increment the version with every commit, instead use the yarn link feature from yarn to test your work in the docs or a project where you might be using the library. Check out the yarn docs for this.

We're following the Semantic versioning spec (major.minor.patch), however the canary suffix is here to stay.