Day: August 30, 2025

Introduction

When building modern web applications, performance is a critical factor for user experience and SEO. In setups that combine Rails (for backend logic) with Vue 3 (for the frontend), and Nginx + Passenger as the web server layer, developers must understand how requests flow through the system and how caching strategies can maximize efficiency. Without a clear understanding, issues such as stale content, redundant downloads, or poor Google PageSpeed scores can creep in.

In this series, we will break down the architecture into three detailed parts. In this first part, we’ll look at the basic request flow, why caching is needed, and the specific caching strategies applied for different types of assets (HTML, hashed Vue assets, images, fonts, and SEO files).

🔹 1. Basic Request Flow

Let’s first understand how a browser request travels through our stack. In a Rails + Vue + Nginx setup, the flow is layered so that Nginx acts as the gatekeeper, serving static files directly and passing dynamic requests to Rails via Passenger. This ensures maximum efficiency.

Browser Request (user opens https://mydomain.com)
      |
      v
+-------------------------+
|        Nginx            |
| - Serves static files   |
| - Adds cache headers    |
| - Redirects HTTP → HTTPS|
+-------------------------+
      |
      |---> /public/vite/*   (hashed Vue assets: JS, CSS, images)
      |---> /public/assets/* (general static files, fonts, images)
      |---> /public/*.html   (entry files, e.g. vite.html)
      |---> /sitemap.xml, robots.txt
      |
      v
+-------------------------+
| Passenger + Rails       |
| - Handles API requests  |
| - Renders dynamic views |
| - Business logic        |
+-------------------------+
      |
      v
Browser receives response

Key takeaways:

• Nginx is optimized for serving static files and does this without invoking Rails.
• Hashed Vue assets live in /public/vite/ and are safe for long-term caching.
• HTML entry files like vite.html should never be cached aggressively, as they bootstrap the application.
• Rails only handles requests that cannot be resolved by static files (APIs, dynamic content, authentication, etc.).

🔹 2. Why Caching Matters

Every time a user visits your site, the browser requests resources such as JavaScript, CSS, images, and fonts. Without caching, the browser re-downloads these assets on every visit, leading to:

• Slower page load times
• Higher bandwidth usage
• Poorer SEO scores (Google PageSpeed penalizes missing caching headers)
• Increased server load

Caching helps by instructing browsers to reuse resources when possible. However, caching needs to be carefully tuned:

• Static, versioned assets (like hashed JS files) should be cached for a long time.
• Dynamic or frequently changing files (like HTML, sitemap.xml) should bypass cache.
• Non-hashed assets (like assets/*.png) can be cached for a shorter duration.

🔹 3. Caching Strategy in Detail

1. Hashed Vue Assets (/vite/ folder)

Files built by Vite include a content hash in their filenames (e.g., index-B34XebCm.js). This ensures that when the file content changes, the filename changes as well. Browsers see this as a new resource and download it fresh. This makes it safe to cache these files aggressively:

location /vite/ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

This tells browsers to cache these files for a year, and the immutable directive prevents unnecessary revalidation.

2. HTML Files (vite.html and others)

HTML files should always be fresh because they reference the latest asset filenames. If an old HTML file is cached, it might point to outdated JS or CSS, breaking the app. Therefore, HTML must always be served with no-cache:

location ~* \.html$ {
    add_header Cache-Control "no-cache";
}

This forces browsers to check the server every time before using the file.

3. Other Static Assets (images, fonts, non-hashed JS/CSS)

Some assets in /public/assets/ do not have hashed filenames (e.g., logo.png). Caching these too aggressively could cause stale content issues. A shorter cache period (like 1 hour) is a safe balance:

location ~* \.(?:js|css|woff2?|ttf|otf|eot|jpg|jpeg|png|gif|svg|ico)$ {
    expires 1h;
    add_header Cache-Control "public";
}

4. SEO Files (sitemap.xml, robots.txt)

Search engines like Google frequently re-fetch sitemap.xml and robots.txt to keep their index up-to-date. If these files are cached, crawlers may miss recent updates. To avoid this, they should always bypass cache:

location = /sitemap.xml {
    add_header Cache-Control "no-cache";
}
location = /robots.txt {
    add_header Cache-Control "no-cache";
}

🔹 4. Summary Diagram

The diagram below illustrates the request flow and caching rules:

Browser Request
      |
      v
+------------------+          +-------------------+
|      Nginx       |          | Passenger + Rails |
|------------------|          |-------------------|
| - Serves /vite/* |          | - Dynamic APIs    |
|   (1y immutable) |          | - Auth flows      |
| - Serves .html   |          | - Business logic  |
|   (no-cache)     |          +-------------------+
| - Serves assets/*|
|   (1h cache)     |
| - Serves SEO     |
|   (no-cache)     |
+------------------+
      |
      v
Response to Browser

Let’s bring in some real-world examples from well-known Rails projects so you can see how this fits into practice:

🔹 Example 1: Discourse (Rails + Ember frontend, served via Nginx + Passenger)

• Request flow:
  • Nginx serves all static JS/CSS files that are fingerprinted (application-9f2c01f2b3f.js).
  • Rails generates these during asset precompilation.
  • Fingerprinting ensures cache-busting (like our vite/index-B34XebCm.js).
• Caching:
  • In their Nginx config, Discourse sets: location ~ ^/assets/ { expires 1y; add_header Cache-Control "public, immutable"; }
  • All .html responses (Rails views) are marked no-cache.
  • This is exactly the same principle we applied for our /vite/ folder.

🔹 Example 2: GitLab (Rails + Vue frontend, Nginx load balancer)

• Request flow:
  • GitLab has Vue components bundled by Webpack (similar to Vite in our case).
  • Nginx first checks /public/assets/ for compiled frontend assets.
  • If not found → request is passed to Rails via Passenger.
• Caching:
  • GitLab sets very aggressive caching for hashed assets, because they change only when a new release is deployed: location ~ ^/assets/.*-[a-f0-9]{32}\.(js|css|png|jpg|svg)$ { expires max; add_header Cache-Control "public, immutable"; }
  • Non-hashed files (like /uploads/ user content) get shorter caching (1 hour or 1 day).
  • HTML pages rendered by Rails = no-cache.

🔹 Example 3: Basecamp (Rails + Hotwire, Nginx + Passenger)

• Request flow:
  • Their entrypoint is still HTML (application.html.erb) served via Rails.
  • Static assets (CSS/JS/images) precompiled into /public/assets.
  • Nginx serves these directly, without touching Rails.
• Caching:
  • Rails generates digest-based file names (like style-4f8d9d7.css).
  • Nginx rule: location /assets { expires 1y; add_header Cache-Control "public, immutable"; }
  • Same idea: hashed = long cache, HTML = no cache.

👉 What this shows:

• All large Rails projects (Discourse, GitLab, Basecamp) follow the same caching pattern we’re doing:
  • HTML → no-cache
  • Hashed assets (fingerprinted by build tool) → 1 year, immutable
  • Non-hashed assets → shorter cache (1h–1d)

So what we’re implementing in our setup is the industry standard. ✅

Conclusion

In this part, we established the foundation for how requests move through Nginx, Vue, and Rails, and why caching plays such an essential role in performance and reliability. The key principles are:

• Hashed files = cache long term
• HTML and SEO files = never cache
• Non-hashed static assets = short cache
• Rails/Passenger handles only dynamic requests

In Part 2, we’ll dive deeper into writing a complete Nginx configuration for Rails + Vue, covering gzip compression, HTTP/2 optimizations, cache busting, and optional Vue Router history mode support.