Skip to main content
All Docs
FeaturesBlockManOSUpdated March 26, 2026

Performance: Removing tailwindcss-browser.js from the Deployed Bundle

Performance: Removing tailwindcss-browser.js from the Deployed Bundle

Control: PERF-20 · Version: 1.0.71

Overview

A 271 KB file — public/tailwindcss-browser.js — was found committed to the repository and shipped as part of the production deployment. This document explains what the file is, why it should not be in the bundle, and how to resolve it.

What Is tailwindcss-browser.js?

tailwindcss-browser.js is the Tailwind CSS browser runtime, designed for CDN or playground environments where Tailwind cannot run a build step. It scans the DOM at runtime and injects styles dynamically.

This is distinct from how Tailwind is used in a Next.js project:

ContextHow Tailwind Works
CDN / PlaygroundBrowser runtime (tailwindcss-browser.js) scans DOM at runtime
Next.js (Tailwind v4)PostCSS plugin compiles all classes at build time — no runtime needed

In a Next.js application using Tailwind v4, the browser runtime is not required in production.

Impact

  • Bundle size: 271 KB added to every deployment, regardless of whether the file is used.
  • Page load risk: If the file is referenced via a <script> tag without a deferred or lazy loading strategy, it becomes a render-blocking resource, delaying First Contentful Paint (FCP) and Largest Contentful Paint (LCP).
  • Likely affected area: The MarketingIframe component, which renders external HTML content, is the most probable consumer of a Tailwind browser runtime via an inline or linked script tag.

Resolution Steps

Step 1 — Audit references

Search the codebase for any reference to tailwindcss-browser.js:

grep -r "tailwindcss-browser" ./src ./public --include="*.tsx" --include="*.ts" --include="*.html" --include="*.js"

Step 2a — If the file IS referenced (e.g. MarketingIframe)

Replace any direct <script> tag with Next.js's built-in Script component using the lazyOnload strategy. This defers execution until after the page is fully interactive:

import Script from 'next/script';

// Before (render-blocking)
<script src="/tailwindcss-browser.js" />

// After (deferred, non-blocking)
<Script
  src="/tailwindcss-browser.js"
  strategy="lazyOnload"
/>

Note: Even with lazy loading, shipping 271 KB of a Tailwind runtime to production is rarely justified. Consider whether the MarketingIframe content can be pre-processed to use compiled styles instead.

Step 2b — If the file is NOT referenced

Remove the file and prevent it being re-added:

# Remove the file
rm public/tailwindcss-browser.js

# Stage the deletion
git rm public/tailwindcss-browser.js

Add the following to .gitignore:

# Tailwind browser runtime — CDN/playground only, not for production
public/tailwindcss-browser.js

Expected Outcome

MetricBeforeAfter
Deployed bundle size+271 KB (always)0 KB saved
Render-blocking riskPresent (if referenced)Eliminated
Build-time safetyNone.gitignore prevents re-introduction

Related