@thegetty/getty-ui

Getty UI Components Library

Installation

1. Clone the getty-ui repository

git clone [e-mail]:thegetty/getty-ui.git

1. Install the project dependencies

Run npm ci to do a clean install of the dependencies listed in the package-lock.json

cd getty-ui && npm ci

1. Configure local environment variables

From the repository root run

cp .env.example .env

Current .env values can be found in Vault at /dev/getty-ui

1. (Optional) To automatically load a .env file when changing into a project directory

• Install direnv and follow the instructions to hook into your shell.
• In each project directory you want the .env file to load automatically, run

echo "dotenv" > .envrc
direnv allow .

Local Development

To build the getty-ui package and watch for changes

npm run dev

To run the UI Storybook component explorer at http://localhost:6006

npm run storybook

Build the package

npm run build

Unit tests

npm run test:generate-output

Linting

npm run lint

Using a local version of getty-ui

1. Create a global symlink to your local getty-ui repository

npm link

1. From the root of each repository that will use getty-ui as a local dependency run

npm link @thegetty/getty-ui

To unlink from the local version of getty-ui run from the root of the repository using getty-ui as a dependency

npm uninstall --no-save @thegetty/getty-ui && npm install

(Running npm uninstall from the root of your local getty-ui repository will remove the global symlink.)

Components Storybook and Chromatic library

Published Storybook

A published version of the Getty UI Storybook is built and deployed automatically as part of the continuous integration workflow to https://tools.getty.edu/getty-ui/storybook with additional paths for /builds, /library, and /pullrequests.

Branch deploys

A build of the Getty UI Storybook for any branch with an open pull request is also deployed to

https://<branch>--5d9637d3d0f20b0020bdbea1.chromatic.com

Branch builds of the Chromatic library can be viewed by appending branch=<branch> to the url query string as follows

https://tools.getty.edu/getty-ui/storybook/library?branch=<branch>

Server Side Rendering Support

The utils/isSsr method can be used to determine when the execution environment is server side. Components should use the isSsr method to conditionally execute code that calls browser APIs only when on the client.

Dependencies that call browser APIs are registered as Webpack externals in vue.config.js and will be included in the bundle for an application using Getty UI.

Static assets

Static assets (such as fonts, favicons, icon images, etc.) are located in an AWS S3 storage bucket accessible at static.getty.edu.

The Getty UI build contains an index.html "template" file with preconnect links to static.getty.edu, media.getty.edu, and prefetch links for .woff2 font assets.

Nuxt.js

In Nuxt.js applications, you can use the Nuxt.js module by adding it in your nuxt.config.js.

buildModules: [
  `@thegetty/getty-ui/nuxt/module`
],

This will import the global CSS (see Styles section below), register a plugin with Nuxt that will register the Vue plugin GettyUICore.

Options

Options can be passed in buildModules:

buildModules: [['@thegetty/getty-ui/nuxt/module', { namespace: 'gradoo' }]];

Key	Type	Default	Description
namespace	String	gui	Set namespace
xray	Boolean	false	Enable X-Ray

X-Ray debug tool

X-Ray highlights the component directly under the mouse cursor and displays the component name in the lower right corner of the viewport.

When the xray option is set to true, the tool will be bundled and ready to be activated in the browser.

To toggle its visibility and active state, while browsing the site, you can press Command ⌘+Shift+X (Mac) or Ctrl+Shift+X (Windows).

Suggested usage in Nuxt apps to bundle it in every environment except production:

buildModules: [
  ['@thegetty/getty-ui/nuxt/module', { xray: process.env.DEPLOY_ENV !== 'production' }]
]

Importing components

The getty-ui/nuxt/module/plugin only registers GettyUICore, components should be imported individually so that only those used are included in the final application bundle, for example:

import { GettyPage, Hero, Ribbon } from '@gui';

SSR

Getty UI supports server side rendering, which can be enabled by updating environment variables and the application config as follows:

nuxt.config.js

 export default {
+  ssr: process.env.NUXT_ENABLE_SSR === 'true',
+  target: process.env.NUXT_TARGET || 'server',
   head: {

...

   publicRuntimeConfig: {
+    nuxtPreviewMode: process.env.NUXT_ENABLE_PREVIEW === 'true',

.env

NUXT_ENABLE_SSR=true
NUXT_ENABLE_PREVIEW=false
NUXT_TARGET=server

Styles

The styles are bundled in a few different ways in getty-ui.

Global CSS

When importing the package in your projects, if you are not using the Nuxt.js module, you should import the global CSS file:

@use '@thegetty/getty-ui';

It includes:

• a browser reset
• the @font-face declarations
• utility classes (f-body-1, l-thirds, s-bg--black, visually-hidden, ...)

Components CSS

Styles for each component are inline with the bundled components and will be imported along the component itself when using them in your app.

import { Accordion } from '@gui';

export default {
  ...
  components: [Accordion],
}

In the example above, the styles for the Accordion will be imported along the component itself.

Design system (SCSS mixins, variables, etc.)

To use the variables (colors, spacing, etc.), mixins and functions from the design system, you can import the 'base' SCSS with the @use statement and import those in the current namespace with ... as *.

<script>
export default {
  ...
}
</script>

<style lang="scss">
@use '@thegetty/getty-ui/src/scss/base' as *;

.my-component {
  color: $color__blue;
  font-size: $global-font-size;

  @include breakpoint('medium+') {
    color: $color__bronze;
  }
}
</style>