Skip to content

Prep docs and post-install message for final v4.0.0 release #485

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Feb 1, 2025
Merged

Prep docs and post-install message for final v4.0.0 release #485

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e37ed78
doc: update README upgrade guide for css class names
flavorjones Jan 31, 2025
976ddab
doc: emit a post-install message with a pointer to upgrade docs
flavorjones Jan 31, 2025
0cc3f19
doc: further improvements to the README
flavorjones Jan 31, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
doc: update README upgrade guide for css class names 
I think 787bf26 left these instructions split across sections, I've
tried to clean that up.
  • Loading branch information
@flavorjones
flavorjones committed Jan 31, 2025
commit e37ed78f5aced5f8aac1a5176659c6e66734672b
76 changes: 40 additions & 36 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,19 +72,19 @@ This gem will help with some of the mechanics of the upgrade, however.

Keep in mind that you don't _need_ to upgrade. You can stay on Tailwind v3 for the foreseeable future if you prefer not to migrate now, or if your migration runs into problems.

Just make sure you're either pinned to v3.3.1 of this gem:
Just make sure you're pinned to v3.3.1 of this gem:

``` ruby
# Gemfile
gem "tailwindcss-rails", "3.3.1" # which transitively pins tailwindcss-ruby to v3
gem "tailwindcss-rails", "~> 3.3.1" # which transitively pins tailwindcss-ruby to v3
```

or if you're on an earlier version of this gem, make sure you're pinning the version of **both** `tailwindcss-rails` and `tailwindcss-ruby`:

``` ruby
# Gemfile
gem "tailwindcss-rails", "~> 3.3"
gem "tailwindcss-ruby", "~> 3.4"
gem "tailwindcss-ruby", "~> 3.4" # only necessary with tailwindcss-rails < 3.3.1
```


Expand All @@ -98,33 +98,7 @@ First, update to `tailwindcss-rails` v4.0.0 or higher. This will also ensure you
gem "tailwindcss-rails", "~> 4.0" # which transitively pins tailwindcss-ruby to v4
```

If you want to migrate class names for v4 (optional), apply this [step](#upgrading-class-names-for-v4) and continue this guide.

Add the following line to the `.gitignore` file:

```gitignore
/node_modules
```
(So the Tailwind update tool won’t dig through your node_modules files and infer incorrect migrations, because it complies with ``.gitignore`` constraints)

Then create a ``package.json`` in the root of the project:

```jsonc
{
"name": "app_name",
"version": "1.0.0",
"dependencies": {
"tailwindcss": "^3.4.17", // Mandatory!!
// Install all plugins and modules that are referenced in tailwind.config.js
"@tailwindcss/aspect-ratio": "^0.4.2",
"@tailwindcss/container-queries": "^0.1.1",
"@tailwindcss/forms": "^0.5.10",
"@tailwindcss/typography": "^0.5.16"
// And so on...
}
}
```
**Run** ``npm install`` (or ``yarn install`` if using ``yarn``)
If you want to migrate CSS class names for v4 (this is an optional step!), jump to [Updating CSS class names for v4](#updating-css-class-names-for-v4) before continuing.

Then, **run** the `tailwindcss:upgrade` task. Among other things, this will try to run the official Tailwind upgrade utility. It requires `npx` in order to run, but it's a one-time operation and is *highly recommended* for a successful upgrade.

Expand Down Expand Up @@ -187,14 +161,42 @@ You may want to check out [TailwindCSS v4 - upgrade experience report · rails/t

We know there are some cases we haven't addressed with the upgrade task:

- In setups without JavaScript tooling, the update process may fail to fully migrate `tailwind.config.js` because the tool assumes that the imported packages (e.g., tailwind plugins) are installed via a package manager, allowing them to be called.
- In setups without JavaScript tooling, the update process may fail to fully migrate `tailwind.config.js` because the tool assumes that the imported packages (e.g., tailwind plugins) are installed via a package manager, allowing them to be called. In this case, you should try following the instructions in [Updating CSS class names for v4](#updating-css-class-names-for-v4) which will install the needed javascript packages for the updater.

We'll try to improve the upgrade process over time, but for now you may need to do some manual work to upgrade.


### Updating CSS class names for v4

Before running the upgrade task, go to ``config/tailwind.config.js`` update the ``content`` part to:
With some additional manual work the upstream upgrade tool will update your application's CSS class names to v4 conventions. **This is an optional step that requires a Javascript toolchain!**
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think from this line up to line 198 should be part of the main Upgrade steps, since the upgrade rake task runs the upgrade tool, the tool will fail if the user has not installed the packages referenced in the config file.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These steps are necessary not only to migrate the class names but also to convert the configuration to the new CSS format, such as plugins and user custom configurations that might reference to tailwind default theme.

Copy link
Member Author

@flavorjones flavorjones Jan 31, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The upstream upgrade tool only fails if additional packages have been added and can't be found. A vanilla rails app doesn't need these steps, and they are complex and frankly hard to visually parse and follow as currently written.

I think if this is truly "required" then we should automate it. And if it's not worth automating we should keep it marked as optional. And if it's hard to automate then we need to file issues upstream to have the Tailwind project make the tool work better.

WDYT?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Like, I'm really having a hard time understanding why these steps are necessary, and I'm sorry about that. The rake task works fine for me on my personal projects. And I understand that more complex setups need more complex steps, but then I think it's OK to leave those steps as a separate section. If you want to suggest alternative wording for the section maybe that would split the difference?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Makes senses. Another suggestion is to move up the following excerpt and place it below Upgrade Steps title, maybe something like this:

Warning

In setups without JavaScript tooling, the update process may fail to fully migrate tailwind.config.js because the tool assumes that the imported packages (e.g., tailwind plugins) are installed via a package manager, allowing them to be called. In this case, you should try following the instructions in Updating CSS class names for v4 which will install the needed javascript packages for the updater.

So the reader is aware upfront and doesn't have to go all the way down the guide to find a solution if something goes wrong.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like this, will update the PR. Thank you!! 🙏❤️

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great!!

Side note: I sent you an email. You might want to check it when you have a moment.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've updated the PR with some more README changes. LMK what you think if you get a moment, otherwise I'll merge over the weekend.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It looks perfect to me.


**Add** the following line to the `.gitignore` file, to prevent the upstream upgrade tool from accessing node_modules files.

```gitignore
/node_modules
```

**Create** a `package.json` in the root of the project:

```jsonc
{
"name": "app_name",
"version": "1.0.0",
"dependencies": {
"tailwindcss": "^3.4.17", // Mandatory!!
// Install all plugins and modules that are referenced in tailwind.config.js
"@tailwindcss/aspect-ratio": "^0.4.2",
"@tailwindcss/container-queries": "^0.1.1",
"@tailwindcss/forms": "^0.5.10",
"@tailwindcss/typography": "^0.5.16"
// And so on...
}
}
```

**Run** `npm install` (or `yarn install` if using `yarn`)

**Update** `config/tailwind.config.js` and temporarily change the `content` part to have an additional `.` on all paths so they are relative to the config file:

```js
content: [
Expand All @@ -204,17 +206,19 @@ Before running the upgrade task, go to ``config/tailwind.config.js`` update the
'../app/views/**/*.{erb,haml,html,slim}'
],
```
(Just add an additional ``.`` to all the paths referenced)

Run the upstream upgrader as instructed above.
(Just add an additional `.` to all the paths referenced)

**Run** the upstream upgrader as instructed above.

Then, once you've run that successfully:
Then, once you've run that successfully, clean up:

- **Delete** ``package.json``, ``node_modules/`` and ``package-lock.json`` (or ``yarn.lock``), plus remove ``/node_modules`` from ``.gitignore``.
- **Delete** `package.json`, `node_modules/` and `package-lock.json` (or `yarn.lock`), plus remove `/node_modules` from `.gitignore`.
- **Go** to your CSS file and remove the following line (if present):
```css
@plugin '@tailwindcss/container-queries';
```
- **Revert** the changes to `config/tailwind.config.js` so that paths are once again relative to the application root.


## Developing with Tailwindcss
Expand Down