Getting started

Initial setup

Configure git to ignore some commits (containing large formatting changes) in git blame.

git config blame.ignoreRevsFile /path/to/terra-ui/.git-blame-ignore-revs

Running Terra UI

1. Install Node.js 20. See https://nodejs.org/en/download/ for options for installing Node.js.

   • Until we upgrade Yarn, 20.11 is the highest working Node version due to an incompatibility.

2. Enable corepack to use Yarn. See https://yarnpkg.com/getting-started/install.

   corepack enable

3. Install "unplugged" dependencies.

   yarn install

   Terra UI uses yarn's "Plug'n'Play", so most dependencies are checked into git in .yarn/cache. "Unplugged" dependencies are those with native components.

4. Start development server.

   yarn start

   This watches for changes and automatically rebuilds Terra UI application code in the src directory. It does not watch for changes to packages. After editing a package, it must be built with yarn workspace '@terra-ui-packages/<package>' run build. Or a package can be watched/automatically rebuilt with yarn workspace '@terra-ui-packages/<package>' run dev.

5. Open http://localhost:3000 in a browser.

Testing

Run Terra UI unit tests with:

yarn test

To run tests for a package, use yarn workspace '@terra-ui-packages/<package>' run test.

More information on unit tests

Code style and linting

ESLint is automatically run on commits via a pre-commit hook. To skip the pre-commit hook, use git commit --no-verify.

ESLint runs Prettier to format code. You may want to configure your editor to format on save.

To attempt to automatically resolve lint issues, run yarn lint from the repo's root directory. ESLint will fix whatever issues it can and report any that must be manually resolved. Consider configuring your editor to show lint warnings so they can be resolved during development.

Code organization

Terra UI is split into multiple packages (the packages directory) and the application itself (the src directory).

The application depends on packages via Yarn workspaces. See PR #3992 for more details.

Each package has its own set of scripts (test, etc).

Scripts at the workspace root generally refer to the Terra UI application. For example, to run tests for the application, run yarn test.

To run a script for a specific package, use yarn workspace. For example, to run tests for the core-utils package, run yarn workspace '@terra-ui-packages/core-utils' test.

To run a script for all packages, use yarn workspaces foreach. For example, to run unit tests for all packages and Terra UI, use yarn workspaces foreach --exclude terra-integration-tests run test.