top

Setting caching headers for a SPA in NGINX cache

When your frontend app is a SPA, all the assets get loaded into the browser and routing happens within the browser unlike a SSR app or conventional/legacy web apps where every page is spat out by the server. If caching is misconfigured or not configured, you will have a horrifying time during deployments.Muscle memories of your developers will make them hit hard refresh when they hear the word “Code Deployed” but your customers will rant and rave when their web page gets mangled in the middle of something important because of your deployment.Having read on the internet before “Browsers and Web servers have been configured by default handle basic caching” made me procrastinate my learning on caching until one day. It started annoying QA and started killing developer’s productivity. That day I told myself “You are not gonna sleep tonight!”Here is a guide to caching headers for SPA in Nginx.How to Cache headers for SPA on Nginx?Primary RequirementThe configuration which I’m going to explain wil+l work only if your SPA uses webpack or any other bundler which can be configured to append random characters to file names in the final distribution folder on every build (revving). This is quite a standard practice in modern web development. I’m pretty sure it will be happening in your system without your knowledge.Checkout Revved resources section at https://developer.mozilla.org/en-US/docs/Web/HTTP/CachingStatus Quo2 WebApps segregated by NGINX locations pathsAWS ELB is sitting in front of the NGINX Web ServerAWS CloudFront is sitting in front of AWS ELB. (Actual caching is done here)NGINX is sending out last-modified and etag headers.I have some faint idea on how caching works.Configure caching in NGINXThe headers which we are going to need are cache-control, etag and vary. vary is added by NGINX by default, so we don’t have to worry about it. We need to add the other two headers in our configs at the right place to get caching working.We have to configure the following things:disable caching for index.html ( Every time browser will ask for a fresh copy of index.html)Enable caching for static assets (CSS, JS, fonts, images) and set the expiry as long as you need ( eg: 1year).1. Let's disable caching for index.html My current config.location /app1 {   alias /home/ubuntu/app1/;   try_files $uri $uri/ /index.html; } After disabling caching.location /app1{    alias /home/ubuntu/app1/;    try_files $uri $uri/ /index.html;    add_header Cache-Control "no-store, no-cache, must-revalidate"; }How this will work?When I hit /app1 from my browser NGINX will serve the index.html from /home/ubuntu/app1 directory to my browser, at the same time it will also execute the add_header directive which will add the Cache-Control "no-store, no-cache, must-revalidate"; to the response header. The header conveys the following instructions to my browserno-store: don’t cache/store any of the response in the browser.no-cache: ask every-time(every request) with the server “Can I show the cached content I have to the user?”must-revalidate: once the cache expires don’t serve the stale resource. ask the server and revalidate.The combination of these three values will disable caching for the response which is received from the server.2. Let's enable caching for static assetsMy current config.#for app1 static files location /app1/static {    alias /home/ubuntu/app1/static/; }After enabling caching.#for app1 static files location /app1/static {    alias /home/ubuntu/app1/static/;    expires 1y;    add_header Cache-Control "public";    access_log off; }How to implement cache headers with Nginx?We enable aggressive caching for static files by setting Cache-Control to "public" and set expires header to 1y. We do this because our frontend build system generates new file names (revving) for the static assets every time we build and new file names invalidate the cache when browsers request it. These static files are referred in index.html which we have disabled caching completely. I disable access logs for static assets as it adds noise to my logs.That's it! This must set up the Nginx caching headers for SPA to create a beautiful app.NGINX add-header GotchaWe usually add the headers which we want to be common for all the location blocks in the server block of the config. But beware that these headers will not get applied when you add any header inside a location block.http://nginx.org/en/docs/http/ngx_http_headers_module.html#add_headerThere could be several add_header directives. These directives are inherited from the previous level if and only if there are no add_header directives defined on the current level.server {   # X-Frame-Options is to prevent from clickJacking attack   add_header X-Frame-Options SAMEORIGIN;   # disable content-type sniffing on some browsers.   add_header X-Content-Type-Options nosniff;   # This header enables the Cross-site scripting (XSS) filter   add_header X-XSS-Protection "1; mode=block";   # This will enforce HTTP browsing into HTTPS and avoid ssl stripping attack   add_header Strict-Transport-Security "max-age=31536000; includeSubdomains;";   add_header Referrer-Policy "no-referrer-when-downgrade";   location /app1 {       alias /home/ubuntu/app1/;       try_files $uri $uri/ /index.html;        add_header Cache-Control "no-store, no-cache, must-revalidate";      } In the above example the security headers in the beginning will not be applied to /app1 block. Make sure you either duplicate it or have it written in a separate .conf file and import it in every location block.BonusEnabling CORS for fonts when serving through a different CDN domain.location /app1/static/fonts {    alias /home/ubuntu/app1/static/fonts/;    add_header “Access-Control-Allow-Origin” *;        expires 1y;    add_header Cache-Control “public”; } Adding the Access-Control-Allow-Origin header will instruct the browsers to allow loading fonts from a different sub-domain. Note that I also enabled aggressive caching for fonts too.Adding vary by gzip# Enables response header of "Vary: Accept-Encoding" gzip_vary on; This will add Vary: Accept-Encoding header to the publicly cacheable, compressible resources and makes sure that the browser will get the correct encoded cached response.NGINX HTTP to HTTPS Redirection# Get the actual IP of the client through load balancer in the logs real_ip_header     X-Forwarded-For; set_real_ip_from   0.0.0.0/0; if ($http_x_forwarded_proto = 'http') {   return 301 https://$host$request_uri; } Add the above in your server block and open port 80 along with 443 in your AWS ELB. This redirect http to https and also log the actual client IP n your logs.Putting all the above things together, this how the final config would look like.server {     server_name www.my-site.com     listen       80;         # Get the actual IP of the client through load balancer in the logs     real_ip_header     X-Forwarded-For;     set_real_ip_from   0.0.0.0/0;         # redirect if someone tries to open in http     if ($http_x_forwarded_proto = 'http') {       return 301 https://$host$request_uri;     }     # X-Frame-Options is to prevent from clickJacking attack     add_header X-Frame-Options SAMEORIGIN;         # disable content-type sniffing on some browsers.     add_header X-Content-Type-Options nosniff;         # This header enables the Cross-site scripting (XSS) filter     add_header X-XSS-Protection "1; mode=block";         # This will enforce HTTP browsing into HTTPS and avoid ssl stripping attack     add_header Strict-Transport-Security "max-age=31536000; includeSubdomains;";         add_header Referrer-Policy "no-referrer-when-downgrade";         # Enables response header of "Vary: Accept-Encoding"     gzip_vary on;         location /app1 {         alias /home/ubuntu/app1/;         try_files $uri $uri/ /index.html;         add_header Cache-Control "no-store, no-cache, must-revalidate";         }         #for app1 static files     location /app1/static {         alias /home/ubuntu/app1/static/;         expires 1y;         add_header Cache-Control "public";         access_log off;      }           #for app1 fonts     location /app1/static/fonts {         alias /home/ubuntu/app1/static/fonts/;         add_header "Access-Control-Allow-Origin" *;             expires 1y;         add_header Cache-Control "public";     } }                                                                                       Final config snippet.
Rated 4.5/5 based on 111 customer reviews
Normal Mode Dark Mode

Setting caching headers for a SPA in NGINX cache

Pratheek Hegde
Blog
16th Oct, 2018
Setting caching headers for a SPA in NGINX cache

When your frontend app is a SPA, all the assets get loaded into the browser and routing happens within the browser unlike a SSR app or conventional/legacy web apps where every page is spat out by the server. If caching is misconfigured or not configured, you will have a horrifying time during deployments.

Muscle memories of your developers will make them hit hard refresh when they hear the word “Code Deployed” but your customers will rant and rave when their web page gets mangled in the middle of something important because of your deployment.

Having read on the internet before “Browsers and Web servers have been configured by default handle basic caching” made me procrastinate my learning on caching until one day. It started annoying QA and started killing developer’s productivity. That day I told myself “You are not gonna sleep tonight!

Here is a guide to caching headers for SPA in Nginx.

How to Cache headers for SPA on Nginx?

Primary Requirement

The configuration which I’m going to explain wil+l work only if your SPA uses webpack or any other bundler which can be configured to append random characters to file names in the final distribution folder on every build (revving). This is quite a standard practice in modern web development. I’m pretty sure it will be happening in your system without your knowledge.

Checkout Revved resources section at 

https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching

Status Quo

  • 2 WebApps segregated by NGINX locations paths
  • AWS ELB is sitting in front of the NGINX Web Server
  • AWS CloudFront is sitting in front of AWS ELB. (Actual caching is done here)
  • NGINX is sending out last-modified and etag headers.
  • I have some faint idea on how caching works.


Configure caching in NGINX

The headers which we are going to need are cache-control, etag and vary. vary is added by NGINX by default, so we don’t have to worry about it. We need to add the other two headers in our configs at the right place to get caching working.

We have to configure the following things:

  1. disable caching for index.html ( Every time browser will ask for a fresh copy of index.html)
  2. Enable caching for static assets (CSS, JS, fonts, images) and set the expiry as long as you need ( eg: 1year).


1. Let's disable caching for index.html 

My current config.

location /app1 {
  alias /home/ubuntu/app1/;
  try_files $uri $uri/ /index.html;
}

After disabling caching.

location /app1{
   alias /home/ubuntu/app1/;
   try_files $uri $uri/ /index.html;
   add_header Cache-Control "no-store, no-cache, must-revalidate";
}


How this will work?

When I hit /app1 from my browser NGINX will serve the index.html from /home/ubuntu/app1 directory to my browser, at the same time it will also execute the add_header directive which will add the Cache-Control "no-store, no-cache, must-revalidate"; to the response header. The header conveys the following instructions to my browser

  • no-store: don’t cache/store any of the response in the browser.
  • no-cache: ask every-time(every request) with the server “Can I show the cached content I have to the user?”
  • must-revalidate: once the cache expires don’t serve the stale resource. ask the server and revalidate.

The combination of these three values will disable caching for the response which is received from the server.


2. Let's enable caching for static assets

My current config.

#for app1 static files
location /app1/static {
   alias /home/ubuntu/app1/static/;
}

After enabling caching.

#for app1 static files
location /app1/static {
   alias /home/ubuntu/app1/static/;
   expires 1y;
   add_header Cache-Control "public";
   access_log off;
}


How to implement cache headers with Nginx?

We enable aggressive caching for static files by setting Cache-Control to "public" and set expires header to 1y. We do this because our frontend build system generates new file names (revving) for the static assets every time we build and new file names invalidate the cache when browsers request it. These static files are referred in index.html which we have disabled caching completely. I disable access logs for static assets as it adds noise to my logs.

That's it! This must set up the Nginx caching headers for SPA to create a beautiful app.

NGINX add-header Gotcha

We usually add the headers which we want to be common for all the location blocks in the server block of the config. But beware that these headers will not get applied when you add any header inside a location block.

http://nginx.org/en/docs/http/ngx_http_headers_module.html#add_header

There could be several add_header directives. These directives are inherited from the previous level if and only if there are no add_header directives defined on the current level.


server {
  # X-Frame-Options is to prevent from clickJacking attack
  add_header X-Frame-Options SAMEORIGIN;
  # disable content-type sniffing on some browsers.
  add_header X-Content-Type-Options nosniff;
  # This header enables the Cross-site scripting (XSS) filter
  add_header X-XSS-Protection "1; mode=block";
  # This will enforce HTTP browsing into HTTPS and avoid ssl stripping attack
  add_header Strict-Transport-Security "max-age=31536000; includeSubdomains;";
  add_header Referrer-Policy "no-referrer-when-downgrade";
  location /app1 {
      alias /home/ubuntu/app1/;
      try_files $uri $uri/ /index.html;
       add_header Cache-Control "no-store, no-cache, must-revalidate";   
  }

In the above example the security headers in the beginning will not be applied to /app1 block. Make sure you either duplicate it or have it written in a separate .conf file and import it in every location block.


Bonus

  1. Enabling CORS for fonts when serving through a different CDN domain.

location /app1/static/fonts {
   alias /home/ubuntu/app1/static/fonts/;
   add_header “Access-Control-Allow-Origin” *;    
   expires 1y;
   add_header Cache-Control “public”;
}

Adding the Access-Control-Allow-Origin header will instruct the browsers to allow loading fonts from a different sub-domain. Note that I also enabled aggressive caching for fonts too.

  1. Adding vary by gzip

# Enables response header of "Vary: Accept-Encoding"
gzip_vary on;

This will add Vary: Accept-Encoding header to the publicly cacheable, compressible resources and makes sure that the browser will get the correct encoded cached response.

  1. NGINX HTTP to HTTPS Redirection

# Get the actual IP of the client through load balancer in the logs
real_ip_header     X-Forwarded-For;
set_real_ip_from   0.0.0.0/0;
if ($http_x_forwarded_proto = 'http') {
  return 301 https://$host$request_uri;
}


Add the above in your server block and open port 80 along with 443 in your AWS ELB. This redirect http to https and also log the actual client IP n your logs.

Putting all the above things together, this how the final config would look like.

server {

    server_name www.my-site.com
    listen       80;
   
    # Get the actual IP of the client through load balancer in the logs
    real_ip_header     X-Forwarded-For;
    set_real_ip_from   0.0.0.0/0;
   
    # redirect if someone tries to open in http
    if ($http_x_forwarded_proto = 'http') {
      return 301 https://$host$request_uri;
    }

    # X-Frame-Options is to prevent from clickJacking attack
    add_header X-Frame-Options SAMEORIGIN;
   
    # disable content-type sniffing on some browsers.
    add_header X-Content-Type-Options nosniff;
   
    # This header enables the Cross-site scripting (XSS) filter
    add_header X-XSS-Protection "1; mode=block";
   
    # This will enforce HTTP browsing into HTTPS and avoid ssl stripping attack
    add_header Strict-Transport-Security "max-age=31536000; includeSubdomains;";
   
    add_header Referrer-Policy "no-referrer-when-downgrade";
   
    # Enables response header of "Vary: Accept-Encoding"
    gzip_vary on;
   
    location /app1 {
        alias /home/ubuntu/app1/;
        try_files $uri $uri/ /index.html;
        add_header Cache-Control "no-store, no-cache, must-revalidate";    
    }
   
    #for app1 static files
    location /app1/static {
        alias /home/ubuntu/app1/static/;
        expires 1y;
        add_header Cache-Control "public";
        access_log off;
     }
     
    #for app1 fonts
    location /app1/static/fonts {
        alias /home/ubuntu/app1/static/fonts/;
        add_header "Access-Control-Allow-Origin" *;    
        expires 1y;
        add_header Cache-Control "public";
    }
} 


                                                                                     Final config snippet.

Pratheek

Pratheek Hegde

Blog author

Pratheek is passionate about programming. He is currently building small and large scale applications using Javascript and Node.js . His dream is to improve the web platform and bring everyone onto it. Currently he is a Frontend and Infrastructure developer at Cyware Labs.


Website : https://iam.pratheekheg.de

Leave a Reply

Your email address will not be published. Required fields are marked *

Top comments

Anfal

16 November 2018 at 4:01pm
Nice post. I used to be checking continuously this weblog and I'm inspired

SUBSCRIBE OUR BLOG

Follow Us On

Share on

other Blogs

20% Discount