Mix tasks for installing and invoking unocss
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.
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
).
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
.
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:
phx-no-feedback
- applied when feedback should be hidden from the userphx-click-loading
- applied when an event is sent to the server on click while the client awaits the server responsephx-submit-loading
- applied when a form is submitted while the client awaits the server responsephx-change-loading
- applied when a form input is changed while the client awaits the server response
Therefore, you may apply a variant, such as phx-click-loading:animate-pulse
to customize unocss classes
when Phoenix LiveView classes are applied.
Copyright (c) 2024 Jason Clark.
unocss source code is licensed under the MIT License.