Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
be found at [https://hexdocs.pm/ex_postcss](https://hexdocs.pm/ex_postcss).
# ExPostcss
Mix tasks for installing and invoking [postcss](https://github.com/postcss/postcss-cli).
## Installation
If you are going to build assets in production, then you add
`ex_postcss` as a dependency on all environments but only start it
in dev:
```elixir
def deps do
[
{:ex_postcss, "~> 0.1", 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
[
{:ex_postcss, "~> 0.4", only: :dev}
]
end
```
## Adding to Phoenix
You must install postcss-cli by running:
```bash
npm i -D postcss postcss-cli
```
You may also want to install additional plugins for the postcss environment
like `autoprefixer`, `postcss-preset-env`, and `cssnano`
```bash
cd assets
npm -i -D autoprefixer postcss-preset-env
```
Next we will add a configuration file for postcss and place it in our assets directory.
```bash
touch assets/postcss.config.js
```
Here's a sample configuration using autoprefixer, postcss-preset-default, and cssnano.
```javascript
module.exports = (ctx) => ({
plugins: [
require("autoprefixer"),
require("postcss-preset-env")({
stage: 3,
browsers: [
"> 0.5% in US",
"not IE 11",
"not dead"
]
}),
require("cssnano")({
preset: [
"default",
{
discardComments: { removeAll: true }
}
]
})
]
})
```
## Profiles
The first argument to `ex_postcss` is the execution profile.
You can define multiple execution profiles with the current
directory, the OS environment, and default arguments to the
`postcss` task:
```elixir
config :ex_postcss,
default: [
args: ~w(css/app.scss -o ../priv/static/assets/app.css --config ./postcss.config.js),
cd: Path.expand("../assets", __DIR__)
]
```
*Note* You must pass in the path to the configuration file for postcss to pick up your plugins.
You can now invoke postcss with:
```bash
$ mix postcss default --no-map
```
When `mix postcss default` is invoked, the task arguments will be appended
to the ones configured above.
## Watching for changes in development
Add the following configuration to your `config/dev.exs` file within the `watchers` section.
```elixir
postcss: {ExPostcss, :run, [:default, ~w(--watch)]}
```
## Usage with `DartSass`
We can combine ex_postcss with DartSass by having dart sass compile to a file in a temporary directory. Postcss can then watch that file and output its contents to the /priv/static directory.
```
config :dart_sass,
version: "1.49.9",
default: [
args: ~w(css/app.scss ../priv/temp/assets/app.css --load-path=assets/node_modules/),
cd: Path.expand("../assets", __DIR__)
]
config :ex_postcss,
default: [
args: ~w(../priv/temp/assets/app.css -o ../priv/static/assets/app.css --config ./postcss.config.js),
cd: Path.expand("../assets", __DIR__)
]
```
We should ignore this directory in our `.gitconfig` file.
```
# Ignore assets that are produced by build tools.
/priv/temp/
/priv/static/assets/
```
> Note: if you are using esbuild (the default from Phoenix v1.6),
> make sure you remove the `import "../css/app.css"` line at the
> top of assets/js/app.js so `esbuild` stops generating css files.
> Note: make sure the "assets" directory from priv/static is listed
> in the :only option for Plug.Static in your endpoint file at,
> for instance `lib/my_app_web/endpoint.ex`.
Finally, back in your `mix.exs`, make sure you have an `assets.deploy`
alias for deployments:
```elixir
"assets.deploy": [
"esbuild default --minify",
"postcss default",
"phx.digest"
]
```
## Acknowledgements
This package is based on the excellent [esbuild](https://github.com/phoenixframework/esbuild) by Wojtek Mach and José Valim, and [dart_sass](https://github.com/CargoSense/dart_sass) by CargoSense, Inc.
## License
Copyright (c) 2022 Thomas Cioppettini.
ex_postcss source code is licensed under the [MIT License](LICENSE.md).