A library of React components, CSS patterns, and CLI tools for MongoDB's LeafyGreen Design System.
- Create or open a React project
- Install the LeafyGreen CLI
npm install -g @lg-tools/cli- Install all, or some LeafyGreen components
lg installlg install button combobox- Import LeafyGreen components into your project
import Button from '@leafygreen-ui/button';
import { Combobox, ComboboxOptions } from '@leafygreen-ui/combobox';- Create or open a React project
- Install individual LeafyGreen components using
npmoryarn
yarn add @leafygreen-ui/button- Import LeafyGreen components into your project
import Button from '@leafygreen-ui/button';
-
Node >= 18.0.0 required.
via homebrew with
brew install nodevia nodejs installer
-
Install Yarn >= 1.20.0.
-
Clone the repository.
# Navigate to the directory you'd like to clone the repository into $ cd ~/my/repositories # Clone the repository. # We recommend installing using the SSH address rather than the HTTPS one to make authentication easier for you. To set up SSH authentication with GitHub, see their guide: https://docs.github.com/en/github/authenticating-to-github/adding-a-new-ssh-key-to-your-github-account
-
Install dependencies and link packages.
yarn run init
Start up storybook to see all UI components that exist:
yarn startNote: Running storybook doesn't trigger changes in dependencies, only the main component's — e.g. If you're looking at Button, and make a change to Lib, you need to rebuild Lib for Storybook to see those changes in Button.
To rebuild all packages:
yarn buildTo rebuild select packages, filter using --filter:
yarn build --filter="[package]"
// ex. --filter="@leafygreen-ui/hooks"To actively develop leafygreen-ui components within an application, the following script will link all leafygreen-ui components within your application to the local leafygreen-ui repository.
This will allow you to make changes to your local repository of leafygreen-ui and see those changes immediately reflected within your running application. This allows you to develop both in isolation (within leafygreen-ui) and in the context of your application.
To do this, clone this repository and navigate to the root directory (where package.json is located), then run the following:
yarn run link -- ${PATH_TO_APPLICATION}
The script does several things in order:
-
This builds every
leafygreen-uicomponent so they are ready to be linked -
It scans your application for any installed
leafygreen-uicomponents in yournode_modules/@leafygreen-uifolder. NOTE: If the package is new and unpublished/not installed, you will need to create a directory for the new component within your application insidenode_modules/@leafygreen-uibefore running this command. -
If any
leafygreen-uicomponents are found then the script usesyarn linkto link everynode_modules/@leafygreen-uimodule to your localleafygreen-uirepository.
After the script completes, you can make changes directly to the component in your local leafygreen-ui repository. Once you do this, run yarn build in the root of the leafygreen-ui repository and the changes will be visible on your running application.
An externally maintained script to bootstrap a React app with all Leafygreen UI components.
Create a new React app with Leafygreen UI components pre-installed
npx create-leafygreen-app@latest <project-name>Create a new Next app
npx create-leafygreen-app@latest --next <project-name>Install all Leafygreen UI components to an existing project
npx create-leafygreen-app@latest --packages-onlyTo get started quickly and easily run yarn create-package my-new-package. When you run this command, we create a directory containing all of the boilerplate code that you'll need to start developing your new Component.
Note: it's important to follow the kebab-casing convention described above.
- Add the new component to
build.tsconfig.json - If you are using any
leafygreen-uidependencies in your new component, add the dependency to the component directory'stsconfig.json. - Run
yarn run initto link all packages before starting development
When you run yarn fix, we do the following:
- We run
yarn prettier:fixso that we have consistently formatted code. - We run
yarn eslint:fixto catch any syntax errors, unused variables, and any other easy-to-catch issues.
To fix all files in the repository, run the following:
yarn fix
To check if any files need formatting without automatically formatting them, run the following:
yarn prettier:check
To run linting without automatically fixing issues, run the following:
yarn eslint:check
To run typechecking without compiling the code, run the following:
yarn ts
To run the unit tests for our components, run the following:
yarn test
When making a PR that contains changes that should be included in a package's changelog, be sure to do so by running:
yarn changeset
This will generate a changes.json file, keeping track of version upgrades and update descriptions. We follow semver conventions for versioning, so each change will either be major, minor, or patch.
Make sure that the PR includes the changes made by running this command.
-
Merge the automatically generated
Version PackagesPR that will contain appropriate version bumps and changelog documentation. -
Push the tags from the release up to Github.
git push --follow-tags
Read more in-depth pre-release guides here
Pre-releases let you publish an alpha/beta/next version of a component, allowing developers to test a component before fully releasing a component.
Let's imagine we want to publish a beta release of some component. Our work is being done on a branch called new-feature
- Create a new branch off your component branch
git checkout -b pre-release- this makes sure your package updates stay independent
- Enter pre-release mode:
yarn changeset pre enter beta(name can benext,beta,alpha, or any other name) - Update package versions
yarn changeset version- This will update any packages with existing changeset files to version
X.Y.Z-beta.0(or whatever name you used)
- This will update any packages with existing changeset files to version
- Commit these updates
git commit -am "Prerelease version packages" - Build the component(s) you're pre-releasing
yarn build <...components> - Publish the prerelease with
yarn changeset publish
Any new work you do should be done in the original (new-feature) branch.
To publish a new pre-release version, pull the changes from new-feature into branch pre-release, and follow steps 3-5.
When new-feature is merged into main, you can safely delete the pre-release branch
You can deploy a static build of our Storybook site to gh-pages from the main branch.
- First be sure you've built a static version of Storybook with the script:
build-storybook - Then deploy to gh-pages:
yarn release:site
- Run
yarn demo:site [your_github_username]. - If you haven't built a static version of Storybook yet, you will be prompted to do so.
- You will be asked for confirmation before Storybook is published.
The source files in this repository are made available under the terms of the Apache License, version 2.0.
