Breaking CSS Change: How to Upgrade Scaffold CRUD Styling to v0.8.0 (or greater)

[thedavid]

Redwood’s Scaffold CRUD is styled via a lightweight implementation of Tailwind CSS. However, it was a challenge to modify or replace styles. In PR #611, the addition of Semantic Classes provides much more flexibility but is not compatible with previously generated CRUD components.

Who is affected by this breaking change?

If you have a project with existing CRUD generated via yarn rw g scaffold <model> with RedwoodJS v0.7.0 or earlier, you will experience broken styling if you generate new Scaffold CRUD using RedwoodJS v0.8.0 or greater.

This does not affect new projects or projects originally installed at v0.8.0 or greater.

tl;dr

If you see something like this and want to fix it, you’re in the right place!

The Problem

The new CRUD templates and scaffold.css file are incompatible with the previous versions. The first time the Generator is run, it creates the scaffold.css file. However, if it already exists it will skip fiel creation, which avoids overwriting customization.

There are two options for resolving this issue. The “easiest” one for you will depend on the kind and quantity of changes you’ve made to existing CRUD (if any).

The “Live in Harmony” option is a way to keep existing styling for existing CRUD while using new styling ongoing. This path requires minimal changes to your existing code and might be the right way forward if you’ve made a lot of customization.

The “Fix All the Things” option will update your existing CRUD to use the new styling. If you have made little to no changes, this should be manageable and is recommended. If you have heavily customized your CRUD, you may end up re-working a lot of changes. The point here is that your mileage will vary.

Before we begin, please save everything and commit any changes!

Option 1: Live in Harmony

You’ll need to rename the existing scaffold.css, remove some normalization styles, and update index.js.

1. Rename the file web/src/scaffold.css to something like scaffold-v0.7.css. (The specific name does not matter.)
2. Edit this file by deleting lines 14-34. This is the section starting with /* normalize.css v8.0.1 ... and ending before /* Classes we use in scaffolds from TailwindCSS v1.1.4 ...
3. Edit the file web/src/index.js by updating import './scaffold.css' with the new name for this file, e.g. import 'scaffold-v0.7.css'

When you generate a new Scaffold, it will add the new version of scaffold.css. You can check to make sure everything is working correctly by running yarn rw dev and viewing the respective CRUD pages.

Note: if you have already generated CRUD using the recent version, you’ll be missing the updated scaffold.css file. Add it by re-running the generator for the new CRUD using the --force option. This will overwrite all files so please proceed with caution.

Option 2: Fix All the Things

Using the --force option, you will overwrite existing CRUD with the new version of templates and CSS.

1. Delete the file web/src/scaffold.css
2. Rerun the Scaffold Generator using the --force option.
   • For example, running yarn rw g scaffold post --force will overwrite existing CRUD for the post model.
   • Confirm results by running yarn rw dev and visiting the page. You may need to restart the dev server.
3. If you previously modified page routes, you will now have duplicates. Remove the re-added default routes in web/src/Routes.js.
   • For example, if you previously changed post routes to be admin/post, etc. you will need to remove four routes added during the overwrite and located at the top of the list: /posts/new, /posts/{id:Int}/edit, /posts/{id:Int}, and /posts.
4. If applicable, reapply previous code changes.
5. Repeat steps 2-4 for each generated CRUD.

Final Result

If all goes well, your end result will look something like this