Installation

v1.0.x

Set up Fluxon in your project.

Prerequisites

Before installing Fluxon, ensure you have the following prerequisites:

Phoenix

v1.7 or later

LiveView

v1.0 or later

Tailwind CSS

v4 or later

Setting up your project

  1. Add the Hex Repository

    Fluxon is available as a Hex package. Follow these steps to integrate it into your Phoenix project:

    1. Obtain the FLUXON_KEY_FINGERPRINT and FLUXON_LICENSE_KEY from your account dashboard.

    2. Add the repository using the following command:

      >_ terminal
      mix hex.repo add fluxon https://repo.fluxonui.com \
        --fetch-public-key $FLUXON_KEY_FINGERPRINT \
        --auth-key $FLUXON_LICENSE_KEY
  2. Install Fluxon

    Once the repository is added, add Fluxon to your project dependencies:

    ex mix.exs
    {:fluxon, "~> 1.1.0", repo: :fluxon}

    Run mix deps.get to install the package.

  3. Configure Your Project

    Several files need to be updated to fully integrate Fluxon into your project:

    1. Update the lib/[app_name]_web.ex file to include the Fluxon module.

      ex [app_name]_web.ex
      defp html_helpers do
        quote do
          import Phoenix.HTML
      
          use Fluxon
      
          # ...
        end
      end
    2. Update assets/css/app.css to allow TailwindCSS to process the Fluxon component classes.

      {} app.css
      @import "tailwindcss" source(none);
      @source "../css";
      @source "../js";
      @source "../../lib/phx_app_web";
      @source "../../deps/fluxon/**/*.*ex";
    3. Update the assets/js/app.js file to include the Fluxon hooks and the onBeforeElUpdated function.

      js app.js
      import 'phoenix_html';
      import { Socket } from 'phoenix';
      import { LiveSocket } from 'phoenix_live_view';
      import { Hooks as FluxonHooks, DOM as FluxonDOM } from 'fluxon';
      
      const liveSocket = new LiveSocket("/live", Socket, {
        longPollFallbackMs: 2500,
        params: {_csrf_token: csrfToken},
        hooks: FluxonHooks,
        dom: { 
          onBeforeElUpdated(from, to) { 
            FluxonDOM.onBeforeElUpdated(from, to);
          },
        },
      });

Troubleshooting

If you encounter any issues during the installation process, please refer to the Troubleshooting section which contains a list of common issues and their solutions.

CoreComponents Conflicts

Some Fluxon components share names with Phoenix's CoreComponents, which results in function definition conflicts. This section explains how to handle these conflicts in different scenarios.

Using Only Fluxon Components

If you're starting a brand new Phoenix project and plan to use only Fluxon components, you can remove the conflicting functions from the CoreComponents module:

ex lib/[your_app]_web/components/core_components.ex
def button(assigns)
def error(assigns)
def input(assigns)
def table(assigns)

Mixing Components

If you are already using CoreComponents in your project, you have two options to import Fluxon components while avoiding conflicts:

You can use the except option to import all Fluxon components except those that conflict with CoreComponents:

ex lib/[your_app]_web.ex
defp html_helpers do
  quote do
    import Phoenix.HTML
    use Fluxon, except: [:button, :error, :input, :table]
    # ...
  end
end

Or use the only option to import just the specific Fluxon components you need:

ex lib/[your_app]_web.ex
defp html_helpers do
  quote do
    import Phoenix.HTML
    use Fluxon, only: [:dropdown, :modal, :sheet]
    # ...
  end
end

Direct Access

When you need to use a Fluxon component that conflicts with CoreComponents, you can access it directly through the Fluxon.Components module:

{} example.html.heex
<Fluxon.Components.Input.input name="full_name" />
<Fluxon.Components.Button.button variant="solid">
  Click me
</Fluxon.Components.Button.button>

DaisyUI Compatibility

Starting with Phoenix 1.8, DaisyUI will be included by default. This addition won't affect Fluxon's functionality - you can continue using Fluxon components as before, even with DaisyUI installed.

While it's technically possible to use both libraries simultaneously, they follow different design principles and philosophies. Fluxon maintains its own design system and component library, independent of DaisyUI.