Fixing ad blockers breaking CSS Styling in Astro

Ever had one of those "It works on my machine" moments? Well, I had one of those quite recently; in all fairness, it also worked on other people's machines but it didn't work on others.

After deploying the Treblle Docs in time for Treblle 2.0 release, everything was all fun and good as I used one of my favorite technologies lately - Astro - to build the docs in record time.

However, fast-forward a couple of months and one Treblle user mentioned that the docs were broken for him.

So Instead of this 👇🏾

Beautifully styled Treblle docs 😌

This was what he was seeing 👇🏾

Unstyled Treblle docs 😢

You can imagine my horror as I have so much pride in those docs - why shouldn't I? it's super good in my opinion.

I did some probing and asking around and someone mentioned asking the user if he has an ad blocker on, I hesitated thinking "how can an ad blocker cause such mayhem? 🤔"

Well, I did ask the user, and good enough he did have an ad blocker on. I proceeded feeling good telling them to turn it off. Can you see the problem already?

Asking a user to turn off their ad blocker just to use your docs doesn't sound good at all. That's too much overhead if you ask me. But at the time, I decided to shrug it off as a one-off (how dare they use an adblocker, I thought 😅)

A couple of more days passed, and I shared the Treblle docs Integrations page in a Discord community I am a part of, someone in there also complained about the CSS styling being broken, and sure enough, he had an ad blocker on 😏.

Well at this point I was irritated and very much perplexed. I couldn't figure out for the life of me why ad blockers will be blocking CSS styling on a page. I had questions:

• Is the Treblle Docs perceived as an ad by these blockers?
• Was there a bug in Astro that's responsible for this?
• Am I going to have to switch the docs from Astro? (I know right, I was paranoid at this point 😅t)

Anyways, I went on improving the docs while having this problem at the back of my mind. As I made some more updates like incrementally migrating the styling of the docs to Tailwind CSS.

I decided to ask in the Astro discord if anyone else has encountered this issue. I shared the link to the Treblle docs and within moments we figured it out and it was those "wtf?" moments.

API Analytics is breaking the docs.

I have noticed that the CSS files in the link elements on the pages head section when Astro builds the docs for production were named api-analytics.[hash].css, I didn't pay it any mind because that was a page on the docs - but it sorts of felt curious but I didn't think much of it, to be honest.

Generated CSS files having api-analytics in the filenames

So, this is why this was happening: When Vite uses Rollup to build the Astro project for production, it uses the name of the first file it bundles as the name for your assets so in the case of the Treblle docs, the first file (which can be a component or a Markdown file) was api-analytics.md

It turns out that part of how ad blockers work is to look for resources being downloaded in a page request and block the download of resources that have the words analytics, ad, advertisement, etc. Well, I didn't know this because I hadn't used an ad blocker before so that was a learning moment for me.

How do we fix this?

The first obvious fix for this was to rename the offending file - api-analytics.md and this was suggested in the Astro Discord.

The problem with that is, the file in question is explaining a core feature of Treblle and I wasn't about to rename it as the name of the file is also going to be used as part of the URL to that feature explanation on the docs. So yeah, that wasn't an option.

So how can this be resolved in a way that doesn't involve Treblle losing a feature? 😅

Customizing how Astro output filenames

So, while we were brainstorming on the Astro Discord how to turn off the output of the CSS file being api-analytics.[hash].css, someone mentioned:

I thought: "ah, you took the words out of my mouth" but how?

As it turns out, Astro - having exceptional docs - has already mentioned how to customize the output filenames for the exact scenario I was having. Here is what the Astro docs said:

It went further to say the reason why this might be helpful:

OMG! That makes perfect sense, right? Yeah, I know. Now the obvious choice was to just customize the output name for the *.css files but I felt that was shortsighted as probably this might still crop up in the future for perhaps *.js files.

I opted to customize the entire asset output and this is how I did it:

I edited the Astro config file in the Treblle docs project - astro.config.mjs and added the following config as suggested by the Astro docs

import { defineConfig } from 'astro/config'
 
export default defineConfig({
  vite: {
    build: {
      rollupOptions: {
        output: {
          entryFileNames: 'entry.[hash].js',
          chunkFileNames: 'chunks/chunk.[hash].js',
          assetFileNames: 'assets/asset.[hash][extname]',
        },
      },
    },
  },
})

The part of the config we are interested in, is this bit 👇🏾

rollupOptions: {
    output: {
        entryFileNames: 'entry.[hash].js',
        chunkFileNames: 'chunks/chunk.[hash].js',
        assetFileNames: 'assets/asset.[hash][extname]',
    },
 }

So what's happening? We are telling Rollup that when it outputs entryFileNames it should prefix them with the word "entry" followed by a "period" and a hash rollup will generate before the ".js" extension.

For chunks, we follow the convention chunks/chunk.[hash].js - you may already see the pattern that [hash] is the only unique bit here.

Lastly and the part which directly solves the problem with the CSS styling not loading on the Treblle docs is this bit: assetFileNames: 'assets/asset.[hash][extname]'

So, after making the changes described above, I rebuilt the Treblle docs in production and sure enough, the problem was fixed as the filename for the CSS files was no longer api-analytics.[hash].css but now as we specified, it was now asset.[hash].css.

CSS files using asset.[hash].css as filenames

Conclusion

This issue was indeed a learning moment as I got to understand a bit of how ad blockers work and how they might have unintended consequences. Plus I got to learn a little bit about how Vite uses Rollup to build assets in Astro works.

I hope this helps you if you ever have such an issue with your Astro websites; it won't take you as long as it took me to fix it 😀.

I've got to also thank the Astro community for being so helpful.

Oh, by the way, you can now turn on your ad blocker if you have one and visit the Treblle docs and you can be sure not to see an unstyled page! 😁