---
title: "Installation"
description: "Configure GitHub Packages, install the package, and import the theme once."
section: guides
slug: installation
url: /docs/installation
---

# Installation

Configure GitHub Packages, install the package, and import the theme once.

## Registry

iv-ui is published to GitHub Packages. Add the scoped registry to `.npmrc` and authenticate with a token that has `read:packages`.

**.npmrc**

```ini
@elluzion:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
```

> **CI** — Export `GITHUB_TOKEN` in CI. Locally, `gh auth token` works if the GitHub CLI is signed in.

## Install

```sh
bun add @elluzion/iv-ui @tabler/icons-svelte
```

`@tabler/icons-svelte` is a peer dependency and must be installed alongside the library.

## Theme

Import the full theme once, in the root layout. It bundles tokens, base styles, and the prose typeset.

**src/routes/+layout.svelte**

```svelte
<script lang="ts">
	import '@elluzion/iv-ui/theme.css';
	let { children } = $props();
</script>

{@render children()}
```

CSS can also be imported piecemeal: `tokens.css` (variables only), `base.css` (reset and base elements), `typeset.css` (prose styles).

## Mount the globals

`Toast` and `AlertDialog` listen to their stores, so each app mounts them once. Everything else is rendered where you use it.

**src/routes/+layout.svelte**

```svelte
<script lang="ts">
	import { AlertDialog, Toast } from '@elluzion/iv-ui';
	import '@elluzion/iv-ui/theme.css';
	let { children } = $props();
</script>

{@render children()}
<Toast />
<AlertDialog />
```

## Requirements

- **Svelte 5.20 or newer** — Components are authored with runes.
- **Node 18 or newer** — For the package build and SSR.
- **@tabler/icons-svelte** — Peer dependency used by menus, selects, and overlays.

## Related

- [Quickstart](/docs/quickstart.md)
- [Theming](/docs/theming.md)
- [For agents](/docs/for-agents.md)