# unocss
[](https://github.com/mithereal/unocss/actions/workflows/main.yml)
Mix tasks for installing and invoking [unocss](https://unocss.dev)
## 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:
```elixir
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:
```elixir
def deps do
[
{:unocss, "~> 0.1.9", only: :dev}
]
end
```
Once installed, change your `config/config.exs` to pick your
unocss version of choice:
```elixir
config :unocss, version: "0.61.5"
```
Now you can install unocss by running:
```bash
$ mix unocss.install
```
And invoke unocss with:
```bash
$ 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:
```elixir
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`:
```elixir
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):
```elixir
"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:
```elixir
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:
```elixir
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:
```elixir
unocss: {unocss, :install_and_run, [:default, ~w(--watch)]}
```
Note we are enabling the file system watcher.
Finally, run the command:
```bash
$ 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](https://unocss.dev)
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](https://unocss.dev/) 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 user
* `phx-click-loading` - applied when an event is sent to the server on click while the client awaits the server response
* `phx-submit-loading` - applied when a form is submitted while the client awaits the server response
* `phx-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.
## License
Copyright (c) 2024 Jason Clark.
unocss source code is licensed under the [MIT License](LICENSE.md).
