Weave Code
Tailwind Bundle Laravel Package
symfonycasts/tailwind-bundle
Integrate Tailwind CSS into Symfony with zero fuss. This bundle adds an easy Tailwind build pipeline (CLI support, watch/build commands), sensible defaults, and smooth asset integration so you can ship modern utility-first styling in Symfony apps quickly.
Delightful Tailwind Support for Symfony + AssetMapper
Frequently asked questions about Tailwind Bundle
- Can I use this bundle with Laravel (Symfony) 6.2 or earlier? What’s the minimum version requirement?
- This bundle requires **Symfony 6.3+** due to its dependency on **AssetMapper**, which was introduced in that version. If you’re on Symfony 6.2 or earlier, you’ll need to upgrade or use a Node.js-based Tailwind setup. Laravel users should confirm their Symfony version via `composer show symfony/http-kernel`—if it’s below 6.3, this bundle won’t work without a major upgrade.
- How do I install and configure the bundle in a Laravel/Symfony project?
- Install via Composer: `composer require symfonycasts/tailwind-bundle`. Then enable it in `config/bundles.php` and publish the default config with `php bin/console symfonycasts:tailwind:install`. The bundle auto-detects Tailwind’s binary (no Node.js needed) and generates a `symfonycasts_tailwind.yaml` config file. Run `php bin/console assets:install` to compile assets, and use the provided CLI commands like `symfonycasts:tailwind:build` or `symfonycasts:tailwind:watch`.
- Does this bundle work with Laravel Mix or Webpack Encore for existing projects?
- Yes, but with caveats. The bundle **does not replace Webpack Encore**—it integrates with **AssetMapper**, which can coexist with Encore via the `entrypoints` config. However, Encore still requires Node.js. For a full migration, you’d need to transition assets to AssetMapper’s entrypoints. The bundle prioritizes **zero-Node.js** workflows, so if you’re tied to Webpack, this may not fully eliminate Node.js dependencies.
- How does the bundle handle Tailwind version updates? Will it break my project?
- The bundle **locks Tailwind’s binary version** via the `binary_version` config (mandatory since v0.8.0). To update Tailwind, manually edit this value in `symfonycasts_tailwind.yaml` and run `composer require symfonycasts/tailwind-bundle` again. The bundle **does not auto-update** to avoid breaking changes. Always test updates in a staging environment first, as Tailwind’s utility classes or build process may introduce breaking changes.
- What’s the difference between strict and non-strict mode? Should I use strict mode in production?
- Strict mode (`strict: true` in config) **fails the build if Tailwind errors occur**, while non-strict mode (default) **silently continues**, hiding issues in logs. Use **strict mode in development** to catch build errors early, but avoid it in production—Tailwind errors should trigger CI/CD failures instead. For production, rely on your deployment pipeline’s error handling (e.g., failed `assets:install` commands).
- Can I customize PostCSS plugins or Tailwind’s config file (tailwind.config.js) with this bundle?
- Yes, the bundle supports **custom PostCSS configs** via the `postcss` option in `symfonycasts_tailwind.yaml`. For Tailwind’s `tailwind.config.js`, place it in your project’s root or specify its path via `config_path`. The bundle merges defaults with your config, so you retain full control. However, complex setups (e.g., custom PostCSS plugins) may require additional Symfony service configurations or DI overrides.
- Will this bundle work in a CI/CD pipeline (e.g., GitHub Actions, GitLab CI)? Any gotchas?
- The bundle works in CI/CD, but you may need to configure **binary caching** to avoid slow downloads or rate limits. Use the `binary_platform` option (e.g., `linux-x64`) if deploying to multi-platform environments (e.g., Docker + Windows runners). For GitHub Actions, cache the Tailwind binary directory (`~/.cache/symfonycasts/tailwind`) between runs. Always test your CI workflow with `symfonycasts:tailwind:build --no-watch` to ensure assets compile.
- How do I use Tailwind with Symfony UX (Stimulus/Turbo) or Mercure in this bundle?
- The bundle integrates seamlessly with **Symfony UX**. Use Tailwind classes in your Stimulus controllers or Turbo-driven components as usual—no additional setup is needed. For **Mercure**, the bundle doesn’t directly support live Tailwind rebuilds, but you can trigger builds via Mercure updates by hooking into Symfony’s event system (e.g., `KernelEvents::CONTROLLER`). Example: Dispatch a `tailwind:rebuild` event when content changes, then listen for it in a custom command.
- Are there alternatives to this bundle for Laravel/Symfony? When would I choose another?
- Alternatives include **Node.js-based setups** (e.g., Laravel Mix + Tailwind CLI) or **Vite integration** (via `laravel-vite-plugin`). Choose this bundle if you want **zero Node.js dependency** and leverage **AssetMapper** for modern Symfony projects. Opt for Node.js/Vite if you need **advanced Webpack features**, **monorepo support**, or **custom Babel/TypeScript setups**. For Symfony 5/6.2, consider `spatie/laravel-tailwind` (Laravel-specific) or stick with Webpack Encore.
- How do I debug Tailwind build failures in development? The bundle isn’t showing clear error messages.
- Enable **strict mode** (`strict: true`) in `symfonycasts_tailwind.yaml` to force build failures on errors. For detailed logs, run `symfonycasts:tailwind:build --verbose` or check the Symfony debug toolbar’s **AssetMapper** section. Tailwind errors (e.g., missing plugins, invalid config) will appear in the console. If using Docker, ensure the binary platform (`binary_platform`) matches your host OS. For PostCSS-specific issues, inspect the generated `postcss.config.js` file.
Weaver
How can I help you explore Laravel packages today?