LeafyGreen UI
A library of React components, CSS patterns, and CLI tools for MongoDB's LeafyGreen Design System.
Getting Started
With LeafyGreen CLI
- 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';Without CLI
- 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';Packages
Developer Setup
-
Node >= 16.20.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
Use yarn build to rebuild all packages.
Pass in a specific package name to rebuild select packages:
yarn build button icon
Additionally, pass in the --watch flag to rebuild packages on change.
Development
-
Start up storybook to see all UI components that exist.
yarn start
Development within an Application
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.
create-leafygreen-app
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-onlyCreating New Component
Getting Started
To 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
Formatting and linting
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
Typechecking
To run typechecking without compiling the code, run the following:
yarn ts
Testing
To run the unit tests for our components, run the following:
yarn test
Committing
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.
Publishing
-
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
Publishing Pre-releases
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
Deploy gh-pages
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
To deploy to your own mirror of leafygreen-ui
- 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.
License
The source files in this repository are made available under the terms of the Apache License, version 2.0.