IEA Vue UI Components

[[TOC]]

Using the component library

Installation from GitLab

To install the library from the GitLab NPM registry you first need to set up NPM locally to use it. First set the registry with

npm config set @international-energy-agency:registry https://gitlab.com/api/v4/packages/npm/

Then set your auth token with

npm config set '//gitlab.com/api/v4/packages/npm/:_authToken' "<your_token>"

(Contact your GitLab admin or generate a token with read_registry permissions from Settings -> Repository on GitLab.)

You should now be able to:

npm install @international-energy-agency/vue-ui

Including UI components in your project

import { StyledButton } from "@international-energy-agency/vue-ui";

Including map components in your project

import { MapGetter } from "@international-energy-agency/vue-ui/maps";

(Requires mapbox-gl as peer dependency)

Including Highcharts components in your porject

import { options } from "@international-energy-agency/vue-ui/highcharts";

For now, no peer dependencies as it's just an options object. But in future may require Highcharts. Options can be used with higcharts-vue to provide sensible defaults. @iea/data-charts is now deprecated.

Development

Nodenv

We use nodenv to keep our node version consistent. When it is installed, it should automatically use the correct version. To verify this, you can run nodenv version and verify that it matches the contents of .node-version

If it doesn't match, run:

nodenv update
nodenv install
nodenv version

Project setup

npm install

View storybook locally

npm run storybook

View demo locally

npm run demo

Go to http://localhost:5173

To use the local version of vue-ui in a project using the data browser boilerplate

This can be helpful if you want to test local changes to a component in a project as well as in the storybook.

1. In the data project, change the vue-ui dependency to point to your local version of this repo. For example, if both repos are cloned into in the same directory:

   "@international-energy-agency/vue-ui": "file:../vue-ui",

2. In the data project, reinstall dependencies

   npm install

3. In the data project, in vite.config.js, add "@international-energy-agency/vue-ui" to the array build.rollupOptions.external.
4. In vue-ui (this project) build the package while watching for changes

   npm run build-watch

5. In the data project, run the dev server with --force so that vite ignores its cache

   npx vite --force

Note: do not commit these changes to dev or main, since they are only to help with local development.

Releases

On a new branch:

1. Increment the version number in package.json, following semver.
2. Reinstall npm packages

   npm install

3. Update the changelog.
4. Commit and push your changes.
5. Make an MR and merge to main