# `mix phia.install`
[🔗](https://github.com/phiaui/phia_ui/blob/v0.1.5/lib/mix/tasks/phia.install.ex#L1)

Sets up PhiaUI in the current Phoenix project.

This is the first command to run when integrating PhiaUI into an existing
Phoenix application. It performs three idempotent setup steps:

1. **Injects the theme CSS** — Prepends the PhiaUI TailwindCSS v4 `@theme`
   block (color tokens, radius, typography, etc.) into `assets/css/app.css`.
2. **Creates the hooks entry point** — Writes
   `assets/js/phia_hooks/index.js` with an empty `PhiaHooks` export that
   you can add individual component hooks to.
3. **Wires hooks into app.js** — Prepends an import statement and the
   `PhiaHooks` registration snippet to `assets/js/app.js`.

## Usage

    mix phia.install

Run this command once from the root of your Phoenix project. It is safe to
run multiple times — each step is idempotent and skips silently when already
applied.

## What gets modified

    assets/css/app.css          — PhiaUI @theme block prepended
    assets/js/phia_hooks/       — directory created
    assets/js/phia_hooks/index.js — PhiaHooks export created
    assets/js/app.js            — import + hook registration prepended

## Typical workflow

    # 1. Install PhiaUI setup
    $ mix phia.install

    # 2. Eject individual components as editable source files
    $ mix phia.add button
    $ mix phia.add dialog

    # 3. Optionally install theme presets for runtime colour switching
    $ mix phia.theme install

## Idempotency markers

The task uses sentinel strings to detect prior installation:

- CSS: `/* PhiaUI Theme — do not remove this line */`
- JS: `// phia_hooks_registered`

Do not remove these markers, as they prevent double-injection.

## Options

    --help    Print this help message

# `app_name`

```elixir
@spec app_name() :: atom()
```

Returns the current Mix project's application name atom.

## Example

    iex> Mix.Tasks.Phia.Install.app_name()
    :phia_ui

# `inject_app_js`

```elixir
@spec inject_app_js(Path.t()) :: :ok | :already_installed | :not_found
```

Adds a PhiaHooks import and registration snippet to `assets/js/app.js`
under `root`.

The snippet is prepended to the file so the hooks are available before
any LiveSocket initialisation code.

Skips if the idempotency marker is already present.

## Return values

- `:ok` — snippet was prepended to app.js.
- `:already_installed` — marker was already present; file was not changed.
- `:not_found` — `assets/js/app.js` does not exist.

# `inject_hooks`

```elixir
@spec inject_hooks(Path.t()) :: :ok | nil
```

Creates `assets/js/phia_hooks/index.js` under `root` with an empty
`PhiaHooks` export.

Uses `Mix.Generator.create_file/3` for interactive conflict handling: if the
file already exists, the user is prompted before any overwrite.

The generated file exports an empty object that you populate by importing
individual component hook files, for example:

    import PhiaDialog from "./dialog.js"
    const PhiaHooks = { PhiaDialog }
    export default PhiaHooks

# `inject_theme`

```elixir
@spec inject_theme(Path.t()) :: :ok | :already_installed
```

Injects the PhiaUI `@theme` block into the CSS file at `path`.

The theme block is read from `priv/templates/theme/theme.css` and prepended
to the existing file contents, separated by the idempotency marker comment.

Skips silently if the marker is already present, so it is safe to call this
function multiple times.

## Return values

- `:ok` — theme block was injected.
- `:already_installed` — marker was already present; file was not changed.

---

*Consult [api-reference.md](api-reference.md) for complete listing*