🔱 Atlantis

What is Atlantis?

Design systems enable teams to build better products faster by making design reusable—reusability makes scale possible. This is the heart and primary value of design systems. A design system is a collection of reusable components, guided by clear standards, that can be assembled together to build any number of applications.

Atlantis is a design system for Jobber. The primary objective for Atlantis is to provide a system of reusable components to help developers to quickly build beautiful and consistent interfaces for our users.

Development

Prerequisites

node@18
npm@10

To install Atlantis locally for development:

git clone git@github.com:GetJobber/atlantis.git
cd atlantis
npm install

To start the Storybook development server:

npm start

Monorepo notes

Installing dependencies

When installing dependencies, unless they are required for the documentation viewer, they should be within the package you are working within.

Cross-linking

Within Atlantis, in order for one package to depend on another all that is required is for it to be listed in the appropriate package.json file. Lerna will automatically take care of managing the versions for you.

When working on some packages (for example design) locally, you'll need to run

 npm run bootstrap

and then

  npm start

to view and test your changes.

Installing packages

Atlantis packages are installed and updated using npm. This following list has installation links for each package:

Design system

These are the core packages you'll need to build with Atlantis:

Installing specific versions

Once a package is installed, update that package to the latest version by running:

npm install @jobber/{package}@latest

or if you want a specific version:

npm install @jobber/{package}@{version}

Tooling and configuration

If you're looking to build documentation and tooling using Atlantis' development standards, these packages will be useful:

Generating a component

Running the following command will prompt you for a component name and generate a starting point consisting of a component, tests, styling, etc to help you get started.

You should name your component in PascalCase.

npm run generate

You will be able to select the platform you want to create the component.

Example

❯❯❯ npm run generate

> atlantis@0.0.1 generate /path/to/atlantis
> plop

? Component Name: ExampleComponent
? Generate for:
> Web
> React Native
> Both

✔  +! 5 files added
 -> /packages/components/src/ExampleComponent/index.ts
 -> /packages/components/src/ExampleComponent/ExampleComponent.css
 -> /packages/components/src/ExampleComponent/ExampleComponent.stories.mdx
 -> /packages/components/src/ExampleComponent/ExampleComponent.test.tsx
 -> /packages/components/src/ExampleComponent/ExampleComponent.tsx
✔  +! 2 files added
 -> /docs/components/ExampleComponent/Web.stories.tsx
 -> /docs/components/ExampleComponent/ExampleComponent.stories.mdx

Testing

To run tests:

npm test

Linting

To ensure your code passes our linters run:

npm run lint

You can also auto fix many linting errors by running:

npm run lint:fix

You can run the linters separately with:

npm run lint:css
npm run lint:ts

If you want to troubleshoot linting errors in CI, try running locally first to find the error. If that doesn't work you can open the artifacts for the linting step. To find the errors causing the failure, search for Error - .

Repo structure

The atlantis repo is a monorepo consisting of a few different packages all living in the ./packages/ directory.

The primary packages in here are:

packages/
- components/
  - The primary home for components. Each component lives in its own folder in the ./src directory within here.
- design/
  - A home for shareable css variables.

When installing dependencies be sure to install them relative to the appropriate sub package. For example if you want to use package foo in the components package, you would run npm install foo -w @jobber/components.

For more information on how the packages are bootstrapped, check out NPM workspaces.

Contributing

Everyone is a friend of Atlantis and we welcome pull requests. See the contribution guidelines to learn how.

Publishing

Atlantis uses Lerna and will automatically publish whenever a pull request is merged.

Manual Release Instructions

Follow semver when choosing versions.

npm run release-the-kraken

Publishing a failed release to NPM

In some cases, the automatic release may successfully bump the version and add a changelog but fail to publish to NPM. If this happens and you're one of the Atlantis NPM collaborators, run the code below to send unpublished versions to NPM.

npm run release:unpublished-package

Pre-release

Releasing manually (Team Atlantis Only)

npm run publish:prerelease

Releasing with dependency changes

Lerna automatically determines which package changed and can be released. However, if you've only changed/added/updated an NPM package, Lerna won't count that as a releasable "change". The script below should allow you to create a prerelease for package changes.

npm run publish:prerelease:force @jobber/components

NOTE: You can replace @jobber/components with the package you want to prerelease or remove it to prerelease all of them.

Using Github Actions to Publish a Pre-release

It is possible to generate Pre-releases through GitHub Actions.

To do this create a Pull Request for your branch.
Navigate to the Actions tab.
Navigate to the Trigger Pre-release Build Action
Run click Run Workflow, select your branch and use the Publish Pre-release (Recommended) option
If you only have dependency changes run the Force Publish <package> to get those changes published. This is only needed if the only file modified is the package.json or package-lock.json
When the Action is finished your PR will have a comment with the new release versions

NOTE: You can only do 1 pre-release per commit. If you trigger another pre-release on a previously published commit, it will fail. This also happens on forced pre-release.

Local testing

If you're not sharing your changes with your peers yet and want a quicker way to check your changes, you can run npm run pack {{scope}} from the root folder against one of the workspaces.

npm run pack @jobber/components

That will create a jobber-components-{{version}}.tgz file on the root. You can then install it on your project.

npm i your/path/to/atlantis/repo/jobber-components-{{version}}.tgz

You can replace @jobber/components with @jobber/design, @jobber/hooks or the package you want to be packed up.

NOTE: Use a pre-release if you want to share your changes with someone else instead of sending them the file.

What has changed

lerna changed