Browsers tricked to use an outdated app.css

Koszal

I encountered a weird bug(?) with Plug.Static(?) where browsers sometimes are tricked to use an outdated app.css file. I first noticed this a couple of months ago while experimenting with Phoenix and Tailwind CSS for a CSS animation effect. I’m not really a web guy, it was my first encounter with Tailwind and I found this extremely confusing. The animation worked inconsistently, and I eventually realized it depended on specific CSS classes I used. Some classes were missing from the app.css file loaded by the browser, if I happened to use one, the animation would not work.

To debug, I used a JavaScript function to scan the DOM and identify undefined CSS classes. After much trial and error, I resolved the issue (mix digest.clean (?)) and eventually forgot about it until it resurfaced yesterday. I was tweaking styles with an AI agent. It fixed most things but some elements still displayed incorrectly. The problem was - again - missing classes. The agent tried whitelisting Tailwind classes, modifying App.Endpoint, etc.—the problem persisted.

Here is what I found:

Tailwind correctly generates app.css.
Fetching the file via curl or wget returns the fresh, correct version.
In the browser, requests contain etag headers, the response from the server is 304 - not modified.

Hard reloads, recompiling, restarting the app, switching browsers does not solve the issue.

This happened on 1.7 but on that day I tried upgrading to 1.8 (in a separate branch) - not sure if that is related. I would appreciate some guidance on how to troubleshoot it and/or confirm the problem.

5 comments

/phoenix #digest #static-assets #plugstatic

0 381 5

2025-08-14 04:34:49 UTC

First 5 of 5 Posts

pupdogg

I’ve used this trick with Ruby on Rails assets in the past, but I’m not sure if it will work in your situation. Could you try appending an epoch timestamp to your stylesheet tag in root.html.heex so that it looks like this:

<link phx-track-static rel="stylesheet" href={"#{~p"/assets/css/app.css"}?v=#{System.system_time(:second)}"} />

Post #1

LostKobrakai

Plug.Static already implements caching strategies, there’s no need to come up with your own.

@Koszal what mix env are you using to deploy, are you using releases or mix to start, are you using phx.digest, what is the url as located in the downloaded html?

Post #2

Koszal

This happened on my dev machine, so iex -S mix phx.server and MIX_ENV set to dev. IIRC when it happened for the first time I eventually ran the whole thing through the build/deployment pipeline (which uses mix release). It launched on a remote machine and worked fine.

The URL where I accessed app.css was 0.0.0.0:4000/assets/app.css

I normally don’t use phx.digest. I did not even know it existed until I bumped into this problem. Normally everything just works. You add a class, the app recompiles automatically, and the updated page shows in the browser.

Post #3

slouchpie

@Koszal

Were you using hardcoded tailwind class names or building them dynamically at runtime?

I have noticed that <div class={"p-#{@padding}"}> will not work unless p-18 (assuming padding = 18) is hardcoded in some other class.

Another thing to check is your values for watchers and live_reload in the Endpoint configuration. You might be editing a file not covered by these.

Post #4

arcanemachine

For Tailwind v3, you would add a safelist to ensure such classes were generated:

assets/tailwind.config.js

module.exports = {
  content: ["./js/**/*.js", "../lib/*_web.ex", "../lib/*_web/**/*.*ex"],
  // ...
  safelist: [
    {
      pattern:
        /(alert|bg|btn)-(primary|secondary|info|success|warning|error)/,
    },
    {
      pattern:
        /text-(primary|secondary|info|success|warning|error)-content/,
    },
  ],
  // ...
}

Source: Content Configuration - Tailwind CSS

For Tailwind v4, it looks like this:

assets/css/app.css

@import "tailwindcss" source(none);
@source "../css";
@source "../js";
@source "../../lib/your_project_web/";

/* Other stuff skipped... /*

/* Safelist - Ensure that these Tailwind classes are always generated */
@source inline('{alert,bg,btn}-{primary,secondary,info,success,warning,error}');
@source inline('text-{primary,secondary,info,success,warning,error}-content');

Source: Detecting classes in source files - Core concepts - Tailwind CSS

Post #5

— All posts loaded —