# Installation

Install the experimental alpha from npm.

Use Node 22.22.3, pnpm 11.5.0 and a [WebGPU-capable browser](/docs/support/). This walkthrough creates a small Vite app with the experimental `0.1.0-alpha.2` release. The API may change.

## Install the alpha

[Section titled “Install the alpha”](#install-the-alpha)

In an existing app:

Terminal window

```sh
pnpm add -E @domfx/browser@0.1.0-alpha.2
```

Core is installed automatically. GSAP is optional. Use the same version of every `@domfx` package, pin exact versions and keep your lockfile; the API is experimental even when npm’s `latest` tag points to it.

## Create your preview app

[Section titled “Create your preview app”](#create-your-preview-app)

For a new app, run `mkdir my-domfx-preview`, then `cd my-domfx-preview`. Save this as `package.json`:

```json
{
  "name": "my-domfx-preview",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite --host 127.0.0.1",
    "build": "vite build",
    "preview": "vite preview --host 127.0.0.1"
  },
  "dependencies": {
    "@domfx/browser": "0.1.0-alpha.2"
  },
  "devDependencies": { "typescript": "5.9.3", "vite": "7.3.7" }
}
```

Save this as `pnpm-workspace.yaml`:

```yaml
autoInstallPeers: false
strictPeerDependencies: true
```

Run `pnpm install --ignore-scripts`. Import the public built package exports; no source alias, shader copy or consumer TypeGPU plugin is required.

## Provide the target and host

[Section titled “Provide the target and host”](#provide-the-target-and-host)

Create `index.html`:

```html
<!doctype html>
<html lang="en">
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width" />
  <link rel="icon" href="data:," />
  <title>domfx preview</title>
  <style>
    body { background: #14151B; color: #E8EAF3; font-family: sans-serif; }
    #host { position: relative; padding: 3rem; width: fit-content; }
    #target { min-width: 10rem; min-height: 3rem; font: inherit; }
  </style>
  <div id="host"><button id="target">Original content</button></div>
  <p>Clicks: <output id="clicks">0</output></p>
  <script type="module" src="/main.ts"></script>
</html>
```

The **target element** (`target`) is the button whose shape receives the effect. The **effect container** (`host`) holds the target and the decorative canvas. Use separate elements in the same document, with `position: relative` on the container and room for the flames. Keep both in the document while the effect runs.

Continue with [Standalone](/docs/standalone/#attach-fire) to create `main.ts` and see the result. If you already use GSAP, follow the [GSAP guide](/docs/gsap/). In React or Vue, copy the [tested recipes](/docs/frameworks/).

## Add the optional GSAP binding

[Section titled “Add the optional GSAP binding”](#add-the-optional-gsap-binding)

For native property tweens, add only `gsap` to your app. The `@domfx/gsap` package is needed only for the optional lifecycle-aware snapshot helpers.

For the GSAP walkthrough:

Terminal window

```sh
pnpm add -E gsap@3.15.0
```

If you need the [optional helpers](/docs/api/gsap/#snapshot-bindings):

Terminal window

```sh
pnpm add -E @domfx/gsap@0.1.0-alpha.2
```

Your app supplies GSAP; `@domfx/browser` does not install it.

## Set up your coding agent

[Section titled “Set up your coding agent”](#set-up-your-coding-agent)

Install the domfx skill from your app’s directory:

Terminal window

```sh
pnpm dlx skills add G0m1namm/domfx --skill domfx
```

Choose the coding agent you use and project installation when prompted. Keep `--skill domfx` to select only consumer guidance, excluding the repository’s engineering skills. This installs instructions, not the npm library.

The skill helps your agent choose effects, animate them and release resources. Ask in English or Spanish, for example: “Add Fire to this button and clean it up when the component unmounts.” Instructions are maintained in English; explanations and comments follow your language. Skill discovery depends on your agent; restart its session if needed. The installer supports multiple agents, but they have not all been tested with domfx.
