unocss

CI

Mix tasks for installing and invoking unocss

Installation

If you are going to build assets in production, then you add unocss as dependency on all environments but only start it in dev:

def deps do
  [
    {:unocss, "~> 0.1.9", runtime: Mix.env() == :dev}
  ]
end

However, if your assets are precompiled during development, then it only needs to be a dev dependency:

def deps do
  [
    {:unocss, "~> 0.1.9", only: :dev}
  ]
end

Once installed, change your config/config.exs to pick your unocss version of choice:

config :unocss, version: "0.61.5"

Now you can install unocss by running:

$ mix unocss.install

And invoke unocss with:

$ mix unocss default

The executable is kept at _build/unocss-TARGET. Where TARGET is your system target architecture.

Profiles

The first argument to unocss is the execution profile. You can define multiple execution profiles with the current directory, the OS environment, and default arguments to the unocss task:

config :unocss,
  version: "0.61.5",
  default: [
    args: ~w(
      --config=unocss.config.js
      --input=css/app.css
      --output=../priv/static/assets/app.css
    ),
    cd: Path.expand("../assets", __DIR__)
  ]

When mix unocss default is invoked, the task arguments will be appended to the ones configured above. Note profiles must be configured in your config/config.exs, as unocss runs without starting your application (and therefore it won't pick settings in config/runtime.exs).

Adding to Phoenix

To add unocss to an application using Phoenix, you will need Phoenix v1.6+ and the following steps.

First add it as a dependency in your mix.exs:

def deps do
  [
    {:phoenix, "~> 1.6"},
    {:unocss, "~> 0.1.8", runtime: Mix.env() == :dev}
  ]
end

Also, in mix.exs, add unocss to the assets.deploy alias for deployments (with the --minify option):

"assets.deploy": ["unocss default --minify", ..., "phx.digest"]

Now let's change config/config.exs to tell unocss to use configuration in assets/unocss.config.js for building our css bundle into priv/static/assets. We'll also give it our assets/css/app.css as our css entry point:

config :unocss,
  version: "0.61.5",
  default: [
    args: ~w(
      --config=unocss.config.js
      --input=css/app.css
      --output=../priv/static/assets/app.css
    ),
    cd: Path.expand("../assets", __DIR__)
  ]

Make sure the "assets" directory from priv/static is listed in the :only option for Plug.Static in your lib/my_app_web/endpoint.ex

If your Phoenix application is using an umbrella structure, you should specify the web application's asset directory in the configuration:

config :unocss,
  version: "0.61.5",
  default: [
    args: ...,
    cd: Path.expand("../apps/<folder_ending_with_web>/assets", __DIR__)
  ]

For development, we want to enable watch mode. So find the watchers configuration in your config/dev.exs and add:

  unocss: {unocss, :install_and_run, [:default, ~w(--watch)]}

Note we are enabling the file system watcher.

Finally, run the command:

$ mix unocss.install

This command installs unocss and updates your assets/css/app.css and assets/js/app.js with the necessary changes to start using unocss right away. It also generates a default configuration file called assets/unocss.config.js for you. This is the file we referenced when we configured unocss in config/config.exs.

Unocss Configuration

The first time this package is installed, a default unocss configuration will be placed in a new assets/unocss.config.js file. See the unocss documentation on configuration options.

Note: The stand-alone Unocss client bundles first-class unocss packages within the precompiled executable. For third-party unocss plugin support, the node package must be used. See the unocss nodejs installation instructions if you require third-party plugin support.

The default unocss configuration includes unocss variants for Phoenix LiveView specific lifecycle classes:

Therefore, you may apply a variant, such as phx-click-loading:animate-pulse to customize unocss classes when Phoenix LiveView classes are applied.

License

Copyright (c) 2024 Jason Clark.

unocss source code is licensed under the MIT License.