How We Removed a 271 KB Dead Asset and Hardened Our Build Against Its Return

Release: v1.0.72 · Ticket: PERF-20

---

Background

During a routine build-output audit we found public/tailwindcss-browser.js committed to the repository. This file is the Tailwind CSS CDN browser runtime — a ~271 KB JavaScript bundle designed to apply utility classes at runtime in the browser. In a production Next.js application that uses Tailwind CSS v4 with a PostCSS build step, it is completely unnecessary.

If it had ever been inadvertently referenced (via a <script src> tag or a next/script entry), it would have added a ~271 KB potentially render-blocking payload to every page load across the entire BlockManOS application.

---

Investigation

Before making any changes, we audited the full codebase to understand the true blast radius:

Check	Result
Referenced in any page or component?	❌ No — zero matches for tailwindcss-browser in source
Loaded via <script src>?	❌ No
Loaded via next/script?	❌ No
Runtime JS content present?	Already emptied to a comment-only stub (274 bytes)
.gitignore entry present?	✅ Yes — /public/tailwindcss-browser.js

The file had already been partially addressed by a prior change (content emptied, .gitignore entry added). However, the stub comment did not document why the file must not be re-introduced, leaving the door open for a well-intentioned future developer to restore it.

---

What Changed

1. public/tailwindcss-browser.js — Formalised the guard

The comment stub was updated to explicitly document the PERF-20 resolution:

// PERF-20 RESOLVED: This file has been emptied and is gitignored.
// The Tailwind CSS browser runtime (CDN build) is NOT referenced anywhere in
// this codebase and must NOT be re-introduced.
//
// Tailwind CSS v4 processes styles at build time via PostCSS — no in-browser
// runtime is needed in production.  Serving a 271 KB script from public/ would
// add a potentially render-blocking payload to every page load.
//
// This stub remains tracked so that the gitignore rule below takes effect on
// future checkouts; it carries zero runtime cost (comment-only, < 1 KB).
// .gitignore entry: /public/tailwindcss-browser.js
//
// Ref: https://tailwindcss.com/docs/installation

The stub file itself carries zero runtime cost — it is never served to the browser and is excluded from any future commits that would restore the 271 KB runtime.

Why keep the stub rather than deleting the file?
Git tracks files by content. Without git rm --cached, simply adding a .gitignore entry does not remove a file that is already tracked. Replacing the content with a comment-only stub — combined with the .gitignore rule — is the safest two-layer approach:

1. The .gitignore rule blocks a full tailwindcss-browser.js from ever being staged again.
2. The stub acts as a permanent, in-tree warning for any developer who encounters the file.

2. src/middleware.ts — Health endpoint bypass

As a companion improvement in this release, the Next.js middleware route matcher was updated to exclude /api/health:

export const config = {
  matcher: [
    // Exclude static assets, images, favicon, tailwindcss browser js, and health endpoint
    '/((?!_next/static|_next/image|favicon\.ico|tailwindcss-browser\.js|api/health).*)',
  ],
};

Health-check requests to /api/health now bypass authentication middleware entirely. This enables uptime monitors and load balancer probes to get a reliable, low-overhead response without needing to carry authentication credentials.

---

Impact

Area	Before	After
tailwindcss-browser.js payload risk	271 KB potentially render-blocking (if referenced)	0 bytes — comment stub only
Future re-introduction risk	Undocumented	Blocked by .gitignore + in-file warning
/api/health auth overhead	Auth middleware executed on every probe	Bypassed — zero auth cost

---

No Action Required

This is a non-breaking infrastructure improvement. There are no migration steps, no configuration changes, and no changes to application behaviour for end users.