gatsby-plugin-nginx

This plugin will output a nginx.conf template file at the root directory, containing nginx rules for every page, static asset, createRedirect call and pages with mistmatched path/matchPath.

Hosting locally

After building your gatsby site, you can launch nginx locally for testing or development. Here is an one-liner using docker:

1sed -i -e 's/\$PORT/80/' public/nginx.conf && docker run --rm --name local_nginx -v "$PWD/public/nginx.conf:/etc/nginx/nginx.conf" -v "$PWD/public:/etc/nginx/html" -p 80:80 -it nginx:latest

If no errors occur, your site will be available at http://localhost

All this one-liner does is:

• Replace the $PORT placeholder with an arbitrary port (80)
• Mount the generated configuration at public/nginx.conf to the default nginx path /etc/nginx/nginx.conf
• Mount the public folder to the default nginx root folder at /etc/nginx/html
• Name the container local_nginx for easy of use with other docker commands and instruct docker to remove (--rm) the container when it stops.

To copy over nginx access or error logs, you can then use:

1docker cp local_nginx:/var/log/nginx/error.log .
2docker cp local_nginx:/var/log/nginx/access.log .

To enable debug level error logs, add nginx-debug -g 'daemon off;' at the end of the docker run command.

If you want to use a locally installed version of nginx instead of the docker imager, the paths included in these instructions might not work for you. To find out the paths used by your nginx distribution, you can use the following command:

1nginx -V

Sample configuration

1// gatsby-config.js
2module.exports = {
3  // [...]
4  plugins: [
5    // [...]
6    {
7      resolve: '@vtex/gatsby-plugin-nginx',
8      options: {
9        transformHeaders: (headers, path) => {
10          const DEFAULT_SECURITY_HEADERS = [
11            'X-XSS-Protection: 1; mode=block',
12            'X-Content-Type-Options: nosniff',
13            'Referrer-Policy: same-origin',
14          ]
15
16          return path.includes('/preview')
17            ? [...DEFAULT_SECURITY_HEADERS, 'Content-Security-Policy: frame-src https://*.myvtex.com/', ...headers]
18            : ['X-Frame-Options: DENY', ...DEFAULT_SECURITY_HEADERS, ...headers]
19        },
20      }
21    },
22  ],
23}

Sample output

1worker_processes 3;
2worker_rlimit_nofile 8192;
3error_log /var/log/nginx/error.log debug;
4pid /var/log/nginx_run.pid;
5events {
6  worker_connections 1024;
7}
8http {
9  access_log /var/log/nginx/access.log;
10  server {
11    listen 0.0.0.0:8080 default_server;
12    resolver 8.8.8.8;
13    location = /gorgeous-watch/p {
14      add_header X-Frame-Options "DENY";
15      add_header X-XSS-Protection "1; mode=block";
16      add_header X-Content-Type-Options "nosniff";
17      add_header Referrer-Policy "same-origin";
18      add_header Link "</commons~253ae210-6f947986d9c5bc2d04a1.js>; rel=preload; as=script";
19      proxy_pass https://s3.amazonaws.com/${BUCKET}/${BRANCH}/public/gorgeous-watch/p/index.html;
20    }
21    location = /commons~253ae210-6f947986d9c5bc2d04a1.js {
22      add_header X-Frame-Options "DENY";
23      add_header X-XSS-Protection "1; mode=block";
24      add_header X-Content-Type-Options "nosniff";
25      add_header Referrer-Policy "same-origin";
26      add_header Cache-Control "public, max-age=31536000, immutable";
27      proxy_pass https://s3.amazonaws.com/${BUCKET}/${BRANCH}/public/commons~253ae210-6f947986d9c5bc2d04a1.js;
28    }
29    location ~* ^/api/.* {
30      proxy_pass https://storecomponents.vtexcommercestable.com.br$uri$is_args$args;
31      proxy_ssl_server_name on;
32    }
33    location / {
34      try_files /dev/null @s3;
35    }
36    location @clientSideFallback {
37      rewrite ^/[^/]+/p /__client-side-product__/p last;
38      rewrite ^/pt/[^/]+/p /pt/__client-side-product__/p last;
39      rewrite ^/.* /__client-side-search__ last;
40      rewrite ^/pt/.* /pt/__client-side-search__ last;
41      return 404;
42    }
43    error_page 403 = @clientSideFallback;
44    location @s3 {
45      proxy_pass https://s3.amazonaws.com/${BUCKET}/${BRANCH}/public$uri;
46      proxy_intercept_errors on;
47    }
48  }
49}

How it works

---

Every page and static asset are matched by an exact match location:

1location = /gorgeous-watch/p {}

Additionally, pages include Link headers to its dependencies, and static assets include the Cache-Control: public, max-age=31536000, immutable header.

---

Gatsby's createRedirect calls which toPath is an absolute URI become a regex location that proxies the request to that URL:

1location ~* ^/api/.* {
2    proxy_pass https://storecomponents.vtexcommercestable.com.br$uri$is_args$args;
3    proxy_ssl_server_name on;
4}

Note that the proxy_pass call uses the original request path (the nginx variable $uri above), so any createRedirect call with mistmatching paths will cause this plugin to throw an error for now. Let me (@cezar) know if we want/need to support this scenario.

---

If an incoming request does not match any of these classes of location, it could be either a non-cached asset (such as page-data.json) or a product page that we did not build.

So we first check if we have a matching file on storage with a catch-all, lowest-priority location rule:

1location / {
2    try_files /dev/null @s3;
3}

The try_files above is the nginx equivalent of a goto, and will send the request to the location named @s3:

1error_page 403 = @clientSideFallback;
2location @s3 {
3    proxy_pass https://s3.amazonaws.com/${BUCKET}/${BRANCH}/public$uri;
4    proxy_intercept_errors on;
5}

This location, similary to the others, will try and proxy the request to our storage, but this time we will intercept proxy errors, and in such case that a file does not exist on storage (i.e, product pages that were not built), S3 returns a status code 403 and the error_page directive above will send the request to the location named @clientSideFallback:

1location @clientSideFallback {
2    rewrite ^/[^/]+/p /__client-side-product__/p last;
3    rewrite ^/pt/[^/]+/p /pt/__client-side-product__/p last;
4    rewrite ^/.* /__client-side-search__ last;
5    rewrite ^/pt/.* /pt/__client-side-search__ last;
6    return 404;
7}

This location finally handles pages with mismatching path and matchPath.

createRedirect with relative paths are not yet implemented.

Adding custom blocks to nginx config

Our default nginx config may not be suited for all use cases. For those use cases where you need to enable/disable some extra flags in the server and http block you can use the serverOptions and httpOptions params respectively.

For instance, say we don't want to use Google's dns server, but use the AWS one instead. One could configure the plugin like:

1// gatsby-config.js
2module.exports = {
3  // [...]
4  plugins: [
5    // [...]
6    {
7      resolve: '@vtex/gatsby-plugin-nginx',
8      options: {
9        // other options
10        serverOptions: [['resolver', '169.254.169.253']],
11      }
12    },
13  ],
14}

This will create an nginx.conf file similar to:

...
 server {
    resolver 169.254.169.253;
    ...
 }
...