Tailwind

Mix tasks for installing and invoking tailwindcss via the stand-alone tailwindcss cli

Installation

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

def deps do
  [
    {:tailwind, "~> 0.1.6", 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
  [
    {:tailwind, "~> 0.1.6", only: :dev}
  ]
end

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

config :tailwind, version: "3.1.6"

Now you can install tailwind by running:

$ mix tailwind.install

And invoke tailwind with:

$ mix tailwind default

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

Profiles

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

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

When mix tailwind 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 tailwind runs without starting your application (and therefore it won't pick settings in config/runtime.exs).

Adding to Phoenix

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

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

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

Now let's change config/config.exs to tell tailwind to use configuration in assets/tailwind.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 :tailwind,
  version: "3.1.6",
  default: [
    args: ~w(
      --config=tailwind.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 :tailwind,
  version: "3.1.6",
  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:

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

Note we are enabling the file system watcher.

Check you have correctly removed the import "../css/app.css" line in your assets/js/app.js.

Finally, back in your mix.exs, make sure you have a assets.deploy alias for deployments, which will also use the --minify option:

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

Tailwind Configuration

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

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

The default tailwind configuration includes Tailwind 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-submit-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 tailwind classes when Phoenix LiveView classes are applied.

License

Copyright (c) 2022 Chris McCord. Copyright (c) 2021 Wojtek Mach, José Valim.

tailwind source code is licensed under the MIT License.