npm package: @international-energy-agency/vue-ui
Description: Reusable Vue UI components that match IEA.org design system and behaviors.
Latest version: 2.0.5

# 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:

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

### Including UI components in your project

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

### Including map components in your project

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

(Requires mapbox-gl as peer dependency)

### Including Highcharts components in your porject

```javascript
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](https://github.com/nodenv/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](./.node-version)

If it doesn't match, run:

```sh
nodenv update
nodenv install
nodenv version
```

### Project setup

```sh
npm install
```

### View storybook locally

```sh
npm run storybook
```

### View demo locally

```sh
npm run demo
```

Go to http://localhost:5173

### To use the local version of `vue-ui` in a project using the [data browser boilerplate](https://gitlab.com/international-energy-agency/iea-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:
   ```json
   "@international-energy-agency/vue-ui": "file:../vue-ui",
   ```
2. In the data project, reinstall dependencies
   ```bash
   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
   ```bash
   npm run build-watch
   ```
5. In the data project, run the dev server with `--force` so that vite ignores its cache
   ```bash
   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](https://semver.org/).
2. Reinstall npm packages
   ```bash
   npm install
   ```
3. Update the [changelog](./CHANGELOG.md).
4. Commit and push your changes.
5. Make an MR and merge to `main`