mix phia.install (phia_ui v0.1.5)

Copy Markdown View Source

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

Summary

Functions

app_name()

Returns the current Mix project's application name atom.

inject_app_js(root)

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

inject_hooks(root)

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

inject_theme(path)

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

Functions

app_name()

@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(root)

@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(root)

@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(path)

@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.