Primer / Live
Storybook

Installation and usage

Install primer_live

Add PrimerLive as a dependency in your Phoenix application's mix.exs:

{:primer_live, "~> 0.6"}

Run mix.deps get

CSS and optional JavaScript dependencies

You can either serve the dependencies as static resources, or use npm to bundle all assets.

If you plan to use menus, dialogs, or drawers in your project, you will need to include JavaScript dependencies. If not, you may skip the JavaScript imports and hooks.

Option A: Serve the dependencies as static resources

Create a new static plug entry to endpoint.ex:

# PrimerLive resources
plug(Plug.Static,
  at: "/primer_live",
  from: {:primer_live, "priv/static"}
)

CSS only

Add the import link to root.html.heex.

If you are using verified routes:

<link phx-track-static rel="stylesheet" href={~p"/primer_live/primer-live.min.css"}>

Otherwise:

<link phx-track-static rel="stylesheet" href="/primer_live/primer-live.min.css">

CSS and JavaScript

Add both import links to root.html.heex.

If you are using verified routes:

<link phx-track-static rel="stylesheet" href={~p"/primer_live/primer-live.min.css"}>
<script defer phx-track-static type="text/javascript" src={~p"/primer_live/primer-live.min.js"}></script>

Advanced usage: to only include core Prompt functionality (to enable menus, dialogs and drawers, but without included styling), replace the import filenames with primer-live-prompt.min.css and primer-live-prompt.min.js.

Otherwise:

<link phx-track-static rel="stylesheet" href="/primer_live/primer-live.min.css">
<script defer phx-track-static type="text/javascript" src="/primer_live/primer-live.min.js"></script>

In assets/js/app.js, add global Prompt to the hooks:

let liveSocket = new LiveSocket("/live", Socket, {
  params: { _csrf_token: csrfToken },
  hooks: {
    Prompt: window.Prompt,
    // existing hooks ...
  },
});

Option B: Adding dependencies using npm

This process will bundle all of the app's dependencies together with PrimerLive assets into app.js and app.css inside priv/static/assets.

Add npm library primer-live to your assets/package.json. For a regular project, do:

{
  "dependencies": {
    "primer-live": "file:../deps/primer_live"
  }
}

If you're adding primer-live to an umbrella project, change the paths accordingly:

{
  "dependencies": {
    "primer-live": "file:../../../deps/primer_live"
  }
}

Now run the next command from your web app root:

npm install --prefix assets

If you had previously installed primer-live and want to get the latest JavaScript, then force an install with:

npm install --force primer-live --prefix assets

To ensure that the assets are installed before your application has started, and before it has been deployed, add "npm install" to the setup and deploy scripts in mix.exs.

For example:

defp aliases do
  [
    setup: ["deps.get", "cmd npm --prefix assets install"],
    "assets.deploy": [
      "cmd npm --prefix assets install",
      "esbuild default --minify",
      "phx.digest"
    ]
  ]
  end

Run mix setup to install the npm dependencies.

Add to assets/js/app.js:

import "primer-live/primer-live.css";
import { Prompt } from "primer-live";

Advanced usage: to only include core Prompt functionality (to enable menus, dialogs and drawers, but without included styling), replace the CSS filename to primer-live-prompt.min.js.

Also in assets/js/app.js, add Prompt to the hooks:

let liveSocket = new LiveSocket("/live", Socket, {
    params: { _csrf_token: csrfToken },
    hooks: {
      Prompt,
      // existing hooks ...
    },
  });

Usage

To use components, either use or import module PrimerLive:

defmodule MyAppWeb.MyLiveView do
  use MyAppWeb, :live_view
  use PrimerLive

  def render(assigns) do
    ~H"""
      <.button>Click me</.button>
    """
  end

end
defmodule MyAppWeb.MyLiveView do
  use MyAppWeb, :live_view
  import PrimerLive

  def render(assigns) do
    ~H"""
      <PrimerLive.Component.button>Click me</PrimerLive.Component.button>
    """
  end

end