From 3d2e0660b556f0a1a1f2edb2a959bd18cb5caca3 Mon Sep 17 00:00:00 2001 From: Mike Dalessio Date: Sat, 3 Sep 2022 15:54:27 -0400 Subject: [PATCH 1/3] feat: generate unminified assets with `debug` task param Suggested by #163 --- CHANGELOG.md | 3 ++- README.md | 6 ++++-- lib/tailwindcss/commands.rb | 7 ++++--- lib/tasks/build.rake | 10 ++++++---- test/lib/tailwindcss/commands_test.rb | 13 +++++++++++++ 5 files changed, 29 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6bf4e9b..f1f8928 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,7 +1,8 @@ ## Unreleased -* Correctly handle paths with embedded spaces. [#184](https://github.com/rails/tailwindcss-rails/issues/184) +* Correctly handle paths with embedded spaces. [#184](https://github.com/rails/tailwindcss-rails/issues/184) by [@flavorjones](https://github.com/flavorjones) +* Rake tasks accept a `debug` argument to generate unminified assets, e.g. `tailwindcss:build[debug]`. [#198](https://github.com/rails/tailwindcss-rails/pull/198) by [@flavorjones](https://github.com/flavorjones) ## v2.0.12 / 2022-08-10 diff --git a/README.md b/README.md index a580de0..61540ac 100644 --- a/README.md +++ b/README.md @@ -8,9 +8,11 @@ You can customize the Tailwind build through the `config/tailwind.config.js` fil The installer will create your Tailwind input file in `app/assets/stylesheets/application.tailwind.css`. This is where you import the plugins you want to use, and where you can setup your custom `@apply` rules. When you run `rails tailwindcss:build`, this input file will be used to generate the output in `app/assets/builds/tailwind.css`. That's the output CSS that you'll include in your app (the installer automatically configures this, alongside the Inter font as well). -If you need to use a custom input or output file, you can run `bundle exec tailwindcss` to access the platform-specific executable, and give it your own build options. +**If you need to use a custom input or output file**, you can run `bundle exec tailwindcss` to access the platform-specific executable, and give it your own build options. -When you're developing your application, you want to run Tailwind in watch mode, so changes are automatically reflected in the generated CSS output. You can do this either by running `rails tailwindcss:watch` as a separate process, or by running `./bin/dev` which uses [foreman](https://github.com/ddollar/foreman) to starts both the Tailwind watch process and the rails server in development mode. If you are running `rails tailwindcss:watch` as a process in a Docker container, set `tty: true` in `docker-compose.yml` for the appropriate container to keep the watch process running. +**When you're developing your application**, you want to run Tailwind in watch mode, so changes are automatically reflected in the generated CSS output. You can do this either by running `rails tailwindcss:watch` as a separate process, or by running `./bin/dev` which uses [foreman](https://github.com/ddollar/foreman) to starts both the Tailwind watch process and the rails server in development mode. If you are running `rails tailwindcss:watch` as a process in a Docker container, set `tty: true` in `docker-compose.yml` for the appropriate container to keep the watch process running. + +**If you want unminified assets**, you can pass the `debug` parameter to the rake task, i.e. `rails tailwindcss:build[debug]` or `rails tailwindcss:watch[debug]`. ## Installation diff --git a/lib/tailwindcss/commands.rb b/lib/tailwindcss/commands.rb index 1c4b4a3..0bc52d5 100644 --- a/lib/tailwindcss/commands.rb +++ b/lib/tailwindcss/commands.rb @@ -55,14 +55,15 @@ def executable( exe_path end - def compile_command(**kwargs) + def compile_command(debug: false, **kwargs) [ executable(**kwargs), "-i", Rails.root.join("app/assets/stylesheets/application.tailwind.css").to_s, "-o", Rails.root.join("app/assets/builds/tailwind.css").to_s, "-c", Rails.root.join("config/tailwind.config.js").to_s, - "--minify", - ] + ].tap do |command| + command << "--minify" unless debug + end end def watch_command(**kwargs) diff --git a/lib/tasks/build.rake b/lib/tasks/build.rake index eb79273..da78465 100644 --- a/lib/tasks/build.rake +++ b/lib/tasks/build.rake @@ -1,14 +1,16 @@ namespace :tailwindcss do desc "Build your Tailwind CSS" - task :build do - command = Tailwindcss::Commands.compile_command + task :build do |_, args| + debug = args.extras.include?("debug") + command = Tailwindcss::Commands.compile_command(debug: debug) puts command.inspect system(*command, exception: true) end desc "Watch and build your Tailwind CSS on file changes" - task :watch do - command = Tailwindcss::Commands.watch_command + task :watch do |_, args| + debug = args.extras.include?("debug") + command = Tailwindcss::Commands.watch_command(debug: debug) puts command.inspect system(*command) end diff --git a/test/lib/tailwindcss/commands_test.rb b/test/lib/tailwindcss/commands_test.rb index 184f82c..8734665 100644 --- a/test/lib/tailwindcss/commands_test.rb +++ b/test/lib/tailwindcss/commands_test.rb @@ -48,6 +48,12 @@ def mock_exe_directory(platform) actual = Tailwindcss::Commands.compile_command(exe_path: dir) assert_kind_of(Array, actual) assert_equal(executable, actual.first) + assert_includes(actual, "--minify") + + actual = Tailwindcss::Commands.compile_command(exe_path: dir, debug: true) + assert_kind_of(Array, actual) + assert_equal(executable, actual.first) + refute_includes(actual, "--minify") end end end @@ -59,6 +65,13 @@ def mock_exe_directory(platform) assert_kind_of(Array, actual) assert_equal(executable, actual.first) assert_includes(actual, "-w") + assert_includes(actual, "--minify") + + actual = Tailwindcss::Commands.watch_command(exe_path: dir, debug: true) + assert_kind_of(Array, actual) + assert_equal(executable, actual.first) + assert_includes(actual, "-w") + refute_includes(actual, "--minify") end end end From 4da93dd54c1b017365f8b3ae0113627a23454d17 Mon Sep 17 00:00:00 2001 From: Mike Dalessio Date: Sat, 3 Sep 2022 16:19:38 -0400 Subject: [PATCH 2/3] doc: refactor the README - distinguish content with subsection headings - highlight the rake tasks' attachments, which seem to be confusing for some folks - lead with installation, then get to the development mode content --- README.md | 49 ++++++++++++++++++++++++++++++++++--------------- 1 file changed, 34 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 61540ac..c59da8a 100644 --- a/README.md +++ b/README.md @@ -2,47 +2,66 @@ [Tailwind CSS](https://tailwindcss.com) is a utility-first CSS framework packed with classes like flex, pt-4, text-center and rotate-90 that can be composed to build any design, directly in your markup. +## Installation + +With Rails 7 you can generate a new application preconfigured with Tailwind by using `--css tailwind`. If you're adding Tailwind later, you need to: + +1. Run `./bin/bundle add tailwindcss-rails` +2. Run `./bin/rails tailwindcss:install` + This gem wraps [the standalone executable version](https://tailwindcss.com/blog/standalone-cli) of the Tailwind CSS v3 framework. These executables are platform specific, so there are actually separate underlying gems per platform, but the correct gem will automatically be picked for your platform. Supported platforms are Linux x64, macOS arm64, macOS x64, and Windows x64. (Note that due to this setup, you must install the actual gems – you can't pin your gem to the github repo.) + +## Developing with Tailwindcss + +### Configuration + You can customize the Tailwind build through the `config/tailwind.config.js` file, just like you would if Tailwind was running in a traditional node installation. All the first-party plugins are supported. The installer will create your Tailwind input file in `app/assets/stylesheets/application.tailwind.css`. This is where you import the plugins you want to use, and where you can setup your custom `@apply` rules. When you run `rails tailwindcss:build`, this input file will be used to generate the output in `app/assets/builds/tailwind.css`. That's the output CSS that you'll include in your app (the installer automatically configures this, alongside the Inter font as well). -**If you need to use a custom input or output file**, you can run `bundle exec tailwindcss` to access the platform-specific executable, and give it your own build options. -**When you're developing your application**, you want to run Tailwind in watch mode, so changes are automatically reflected in the generated CSS output. You can do this either by running `rails tailwindcss:watch` as a separate process, or by running `./bin/dev` which uses [foreman](https://github.com/ddollar/foreman) to starts both the Tailwind watch process and the rails server in development mode. If you are running `rails tailwindcss:watch` as a process in a Docker container, set `tty: true` in `docker-compose.yml` for the appropriate container to keep the watch process running. +### Building for production -**If you want unminified assets**, you can pass the `debug` parameter to the rake task, i.e. `rails tailwindcss:build[debug]` or `rails tailwindcss:watch[debug]`. +The `tailwindcss:build` is automatically attached to `assets:precompile`, so before the asset pipeline digests the files, the Tailwind output will be generated. -## Installation +### Building for testing -With Rails 7 you can generate a new application preconfigured with Tailwind by using `--css tailwind`. If you're adding Tailwind later, you need to: +The `tailwindcss:build` is automatically attached to `test:prepare`, which runs before Rails tests. (Note that this currently only applies to rails `test:*` tasks (like `test:all` or `test:controllers`), not "rails test", as that doesn't load `test:prepare`). -1. Run `./bin/bundle add tailwindcss-rails` -2. Run `./bin/rails tailwindcss:install` +### Update assets automatically -## Building in production +While you're developing your application, you want to run Tailwind in "watch" mode, so changes are automatically reflected in the generated CSS output. You can do this by: -The `tailwindcss:build` is automatically attached to `assets:precompile`, so before the asset pipeline digests the files, the Tailwind output will be generated. +- running `rails tailwindcss:watch` as a separate process, +- or by running `./bin/dev` which uses [foreman](https://github.com/ddollar/foreman) to start both the Tailwind watch process and the rails server in development mode. -## Building for testing +If you are running `rails tailwindcss:watch` as a process in a Docker container, set `tty: true` in `docker-compose.yml` for the appropriate container to keep the watch process running. -The `tailwindcss:build` is automatically attached to `test:prepare`, which runs before Rails tests. (Note that this currently only applies to rails `test:*` tasks (like `test:all` or `test:controllers`), not "rails test", as that doesn't load `test:prepare`). +### Debugging with unminified assets -## Conflict with sassc-rails +If you want unminified assets, you can pass a `debug` argument to the rake task, i.e. `rails tailwindcss:build[debug]` or `rails tailwindcss:watch[debug]`. -Tailwind uses modern CSS features that are not recognized by the `sassc-rails` extension that was included by default in the Gemfile for Rails 6. In order to avoid any errors like `SassC::SyntaxError`, you must remove that gem from your Gemfile. -## Class names must be spelled out +### Custom inputs or outputs + +If you need to use a custom input or output file, you can run `bundle exec tailwindcss` to access the platform-specific executable, and give it your own build options. -For Tailwind to work, your class names need to be spelled out. They can't be programmatically composed. So no "text-gray-#{grade}", only "text-gray-500". ## Troubleshooting Some common problems experienced by users ... +### Conflict with sassc-rails + +Tailwind uses modern CSS features that are not recognized by the `sassc-rails` extension that was included by default in the Gemfile for Rails 6. In order to avoid any errors like `SassC::SyntaxError`, you must remove that gem from your Gemfile. + +### Class names must be spelled out + +For Tailwind to work, your class names need to be spelled out. They can't be programmatically composed. So no "text-gray-#{grade}", only "text-gray-500". + ### ERROR: Cannot find the tailwindcss executable for <supported platform> Some users are reporting this error even when running on one of the supported native platforms: From bf09205b0b78c9c0498536a660dbb1d78d6745b7 Mon Sep 17 00:00:00 2001 From: Mike Dalessio Date: Sat, 3 Sep 2022 16:22:12 -0400 Subject: [PATCH 3/3] feat: support polling instead of fs events when watching Polling was added upstream in 3.1.0. Suggested by #168 --- CHANGELOG.md | 3 ++- README.md | 5 +++++ lib/tailwindcss/commands.rb | 7 +++++-- lib/tasks/build.rake | 3 ++- test/lib/tailwindcss/commands_test.rb | 9 +++++++++ 5 files changed, 23 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f1f8928..099f7d4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,8 @@ ## Unreleased * Correctly handle paths with embedded spaces. [#184](https://github.com/rails/tailwindcss-rails/issues/184) by [@flavorjones](https://github.com/flavorjones) -* Rake tasks accept a `debug` argument to generate unminified assets, e.g. `tailwindcss:build[debug]`. [#198](https://github.com/rails/tailwindcss-rails/pull/198) by [@flavorjones](https://github.com/flavorjones) +* The `build` and `watch` tasks accept a `debug` argument to generate unminified assets: `rails tailwindcss:build[debug]` or `rails tailwindcss:watch[debug]`. [#198](https://github.com/rails/tailwindcss-rails/pull/198) by [@flavorjones](https://github.com/flavorjones) +* The `watch` task accepts a `poll` argument to use polling instead of file system events: `rails tailwindcss:watch[poll]`. [#199](https://github.com/rails/tailwindcss-rails/pull/199) by [@flavorjones](https://github.com/flavorjones) ## v2.0.12 / 2022-08-10 diff --git a/README.md b/README.md index c59da8a..acaa69a 100644 --- a/README.md +++ b/README.md @@ -40,10 +40,15 @@ While you're developing your application, you want to run Tailwind in "watch" mo If you are running `rails tailwindcss:watch` as a process in a Docker container, set `tty: true` in `docker-compose.yml` for the appropriate container to keep the watch process running. +If you are running `rails tailwindcss:watch` on a system that doesn't fully support file system events, pass a `poll` argument to the task to instruct tailwindcss to instead use polling: `rails tailwindcss:watch[poll]`. If you use `bin/dev` then you should modify your `Procfile.dev`. + + ### Debugging with unminified assets If you want unminified assets, you can pass a `debug` argument to the rake task, i.e. `rails tailwindcss:build[debug]` or `rails tailwindcss:watch[debug]`. +Note that you can combine task options, e.g. `rails tailwindcss:watch[debug,poll]`. + ### Custom inputs or outputs diff --git a/lib/tailwindcss/commands.rb b/lib/tailwindcss/commands.rb index 0bc52d5..136b5ee 100644 --- a/lib/tailwindcss/commands.rb +++ b/lib/tailwindcss/commands.rb @@ -66,8 +66,11 @@ def compile_command(debug: false, **kwargs) end end - def watch_command(**kwargs) - compile_command(**kwargs) << "-w" + def watch_command(poll: false, **kwargs) + compile_command(**kwargs).tap do |command| + command << "-w" + command << "-p" if poll + end end end end diff --git a/lib/tasks/build.rake b/lib/tasks/build.rake index da78465..258930e 100644 --- a/lib/tasks/build.rake +++ b/lib/tasks/build.rake @@ -10,7 +10,8 @@ namespace :tailwindcss do desc "Watch and build your Tailwind CSS on file changes" task :watch do |_, args| debug = args.extras.include?("debug") - command = Tailwindcss::Commands.watch_command(debug: debug) + poll = args.extras.include?("poll") + command = Tailwindcss::Commands.watch_command(debug: debug, poll: poll) puts command.inspect system(*command) end diff --git a/test/lib/tailwindcss/commands_test.rb b/test/lib/tailwindcss/commands_test.rb index 8734665..7ff0c5c 100644 --- a/test/lib/tailwindcss/commands_test.rb +++ b/test/lib/tailwindcss/commands_test.rb @@ -65,13 +65,22 @@ def mock_exe_directory(platform) assert_kind_of(Array, actual) assert_equal(executable, actual.first) assert_includes(actual, "-w") + refute_includes(actual, "-p") assert_includes(actual, "--minify") actual = Tailwindcss::Commands.watch_command(exe_path: dir, debug: true) assert_kind_of(Array, actual) assert_equal(executable, actual.first) assert_includes(actual, "-w") + refute_includes(actual, "-p") refute_includes(actual, "--minify") + + actual = Tailwindcss::Commands.watch_command(exe_path: dir, poll: true) + assert_kind_of(Array, actual) + assert_equal(executable, actual.first) + assert_includes(actual, "-w") + assert_includes(actual, "-p") + assert_includes(actual, "--minify") end end end