Tailwind CSS for Symfony!

Installation

Install the bundle & initialize your app with two commands:

1
2

$ composer require symfonycasts/tailwind-bundle
$ php bin/console tailwind:init

Done! This will create a tailwind.config.js file and make sure your assets/styles/app.css contains the Tailwind directives.

Usage

To use the Tailwind CSS file, start by including the input file (assets/styles/app.css by default) in base.html.twig. It's quite likely you already have this:

1
2
3
4
5

{# templates/base.html.twig #}

{% block stylesheets %}
    <link rel="stylesheet" href="{{ asset('styles/app.css') }}">
{% endblock %}

The bundle works by automatically swapping out the contents of styles/app.css with the compiled CSS. For this to work, you need to run the tailwind:build command:

1

$ php bin/console tailwind:build --watch

That's it! This will watch for changes to your assets/styles/app.css file and automatically recompile it when needed. If you refresh the page, the final app.css file will already contain the compiled CSS.

1

$ php bin/console tailwind:build --watch --poll

1
2
3
4
5
6

# .symfony.local.yaml
workers:
    # ...

    tailwind:
        cmd: ['symfony', 'console', 'tailwind:build', '--watch']

How Does It Work?

The first time you run one of the Tailwind commands, the bundle will download the correct Tailwind binary for your system into a var/tailwind/ directory.

When you run tailwind:build, that binary is used to compile each CSS file into a var/tailwind/<filename>.built.css file. Finally, when the contents of the CSS file is requested, the bundle swaps the contents of that file with the contents of var/tailwind/<filename>.built.css.

E.g.: A request for assets/styles/app.css will be replaced by var/tailwind/app.built.css. Nice!

Deploying

When you deploy, run the tailwind:build command before the asset-map:compile command so the built file is available:

1
2

$ php bin/console tailwind:build --minify
$ php bin/console asset-map:compile

Form Theming

To make your Symfony forms look nice with Tailwind, you'll need a dedicated form theme. Check out https://github.com/tales-from-a-dev/flowbite-bundle for a helpful bundle that provides that!

Tailwind Plugins

The Tailwind binary that the bundle downloads already contains the "Official Plugins" - e.g. typography. This means you can use those simply by adding the line to the plugins key in tailwind.config.js - e.g. require('@tailwindcss/typography').

In Tailwind CSS v4 you include plugins with the @plugin directive in your input CSS file - e.g. @plugin "@tailwindcss/typography";.

For other plugins - like Flowbite Datepicker, you will need to follow that package's documentation to require the package with npm:

1

$ npm install flowbite

Then add it to tailwind.config.js:

1
2
3
4
5

module.exports = {
    plugins: [
        require('flowbite/plugin')
    ]
}

Configuration

To see the full config from this bundle, run:

1

$ php bin/console config:dump symfonycasts_tailwind

The main option is input_css option, which defaults to assets/styles/app.css. This represents the "source" Tailwind files (the one that contains the @tailwind directives):

1
2
3

# config/packages/symfonycasts_tailwind.yaml
symfonycasts_tailwind:
    input_css: 'assets/styles/other.css'

It's possible to use multiple input files by providing an array:

1
2
3
4
5

# config/packages/symfonycasts_tailwind.yaml
symfonycasts_tailwind:
    input_css:
        - 'assets/styles/other.css'
        - 'assets/styles/another.css'

Another option is the config_file option, which defaults to tailwind.config.js. This represents the Tailwind configuration file:

1
2
3

# config/packages/symfonycasts_tailwind.yaml
symfonycasts_tailwind:
    config_file: 'tailwind.config.js'

If you include any other files containing CSS classes that are located outside of the default directories, for example, in the vendor/ directory like the Tailwind CSS form theme from the symfony/twig-bridge package, then after changing your Twig configuration:

1
2
3
4

# config/packages/twig.yaml
twig:
    form_themes:
        - 'tailwind_2_layout.html.twig'

You will have to add them to your tailwind.config.js file:

1
2
3
4
5
6
7
8

# tailwind.config.js
  module.exports = {
      content: [
          "./assets/**/*.js",
          "./templates/**/*.html.twig",
+         "./vendor/symfony/twig-bridge/Resources/views/Form/*.html.twig",
      ],
  }

Using a Different Binary

The standalone Tailwind binary comes with first-party plugins. However, if you want to add extra plugins, you may choose to install Tailwind via npm instead:

1

$ npm add tailwindcss

To instruct the bundle to use that binary instead, set the binary option:

1
2
3

# config/packages/symfonycasts_tailwind.yaml
symfonycasts_tailwind:
    binary: 'node_modules/.bin/tailwindcss'

Using a Different Binary Version

To use a different version, adjust the binary_version option:

1
2
3

# config/packages/symfonycasts_tailwind.yaml
symfonycasts_tailwind:
    binary_version: 'v3.3.0'

Using a PostCSS config file

If you want to use additional PostCSS plugins, you can specify the PostCSS config file to use, set postcss_config_file option or pass the --postcss option to the tailwind:build command.

1
2
3

# config/packages/symfonycasts_tailwind.yaml
symfonycasts_tailwind:
    postcss_config_file: 'postcss.config.js'

1

$ php bin/console tailwind:build --postcss='postcss.config.js'