nuxtss-s3-fix

Tools and Gear around a website with Nuxt and S3 bucket logos.

The nuxtss-s3-fix is a tool for optimizing Nuxt.js Static Sites HTML page objects to work with the Amazon AWS S3 bucket static web site hosting. These optimizations improve:

  1. Social Media sharing - showing article images and meta data.
  2. SEO metadata - search crawlers can find and record the page meta data
  3. Quicker loading times - avoiding unnecessary redirects.

In my testing, I built my sites using the using Nuxt.js Flat static layout, then ran the commands that the tool provided which arranged the HTML page objects into a Single layout. After applying the fix, I verified that social media sharing and SEO crawlers worked as expected. I found that direct page loading was faster. No observed negative effects of this arrangement were found, but your mileage may vary.

The tool can be used in a local CLI environment or in a CICD pipeline script. It can generate AWS S3 CLI commands that you can run or it makes the calls directly. In both cases the running of the tool or the commands that the tool generates, requires that a proper AWS S3 CLI context with correct permissions.

Prerequisites

In order for the tool to produce appropriate AWS CLI S3 commands you must provide the following:

  1. An AWS S3 bucket containing all the objects as built by Nuxt Static Site generator using npm run generate and autoSubfolderIndex setting in the nuxt.config.js file.
    • autoSubfolderIndex: true = index layout
    • autoSubfolderIndex: false = flat layout
  2. By default, it expects an accurate sitemap.xml object describing the page HTML objects in the bucket root. If you use a sitemap Nuxt.js module, such as @nuxtjs/sitemap, this file gets generated automatically.
    • Optionally, you can provide a different sitemap.xml file, using the --sitemap-file option. The specified sitemap file can be a local file, an https: file, or in another S3 bucket.
  3. The tool needs an inherited AWS S3 CLI context with thegetObject, listObjects, and removeObject permissions for the site S3 bucket.
    • important nuxtss-s3-fix exclusively uses the AWS S3 CLI context in its execution space and does not store or request AWS S3 permissions
    • If you are running the tool in a CICD pipeline action, ensure that the action has the appropriate AWS S3 context permissions.

Nuxt.js Page Layouts

When building a Nuxt Static Site for AWS S3 bucket hosting, for each page (we'll use example) the HTML object will be in one of two layout arrangements depending on the autoSubfolderIndex setting in the nuxt.config.js file.

  1. In the flat layout (autoSubfolderIndex: false) the HTML page object has a .html extension and is a peer next to a directory with the page name.
    • example/
    • example/_payload.json
    • example.html - flat HTML page object
  2. In the index layout (autoSubfolderIndex: true) the HTML page object is placed in the <page> directory with the name index.html page generates files and bucket objects:
    • example/
    • example/_payload.json
    • example/index.html - index HTML page object
  3. In the new optimal Single layout, which is the ideal arrangement for S3 static web site hosting, the HTML page object has no extension and is named the same as the directory object. This is only legal within an AWS S3 bucket, where a directory and an object have the same name, but this not allowed in most file system. The ideal arrangement of the S3 bucket objects for each page looks like this:
    • example/
    • example/_payload.json
    • example - Single HTML page object

Flat or Index Problems

When using a Nuxt static site on an Amazon S3 bucket, the flat and index arrangements have the following issues:

  1. Social Media sharing of a page URL does not show the article image or meta data.
  2. SEO search crawlers do not record the page meta data.
  3. Direct page loading times are slower than they could be.

More details about this can be found at: AWS S3 Configuring an index document and Blog on S3 Static Hosting Issues

S3 Web Server Quirks

The key points of the S3 Web Server quirky behavior are:

  1. For each page URL request without a tailing slash, i.e. a url http://example.com/example, the AWS S3 Web Server will return 1. 200 OK if s3://bucket/example exists 2. 302 Temporarily Moved redirect if s3://bucket/example/index.html exists. The redirect will include a trailing slash, i.e. http://example.com/example/ which causes a reload and confusion by SEO crawlers and Social Media posts. 3. 404 Not Found if not found
  2. For each page URL request with a trailing slash, i.e. a URL http://example.com/example/, the AWS S3 Web Server will return 1. 200 OK if s3://bucket/example/index.html exists 2. 404 Not Found if not found

Router Navigation vs Direct Load

Once the Nuxt.js web app is loaded from the home page, the Vue.js router will handle any further navigation within the app and update the URL directly. This means that if a user starts at the home page http://example.com and then clicks on a link to the photo page, the URL will be updated to http://example.com/photo and the Nuxt.js app knows how to load that page HTML and content without interacting with the S3 site web hosting quirkiness.

It's only on direct URL links to a page that the S3 web server quirkiness comes into play, i.e. for http://example.com/photo or http://example.com/photo/. The page HTML object once loaded has all the information it needs to load the Nuxt.js web app and display the proper page information from there, but the S3 web server has to deliver that page HTML object first. This is where the problems with the flat and index layouts arise.

Flat Direct Load Issues

When the Nuxt static site is built using the flat layout, each S3 bucket HTML page object is named <page>.html. This means than any URL requests (except home) which doesn't include the .html extension, regardless of the trailing slash, will get a 404. If the URL request includes the .html extension, it will work, but that is not a user friendly URL.

For example:

  • If a photo URL request arrives, the AWS S3 Web Server will not find a photo HTML object or a photo/index.html object and return a 404 Not Found.
  • If photo/ URL requests arrives, the AWS S3 Web Server will not find a photo/index.html HTML object and return a 404 Not Found.
  • If a photo.html URL request arrives, the AWS S3 Web Server will find the photo.html HTML object and return a 200 OK.

Index Direct Load Issues

When the Nuxt static site is built using the index layout, each S3 bucket HTML page object is named <page>/index.html. If the URL request does not include the trailing slash, it will work, but will receive a 302 Temporarily moved reload to the page with the trailing slash. If the URL request includes the trailing slash will receive a 200 OK.

For example:

  • If a photo URL request arrives, the AWS S3 Web Server will not find a photo HTML object, but will find the photo/index.html object and return a 302 Temporarily Moved to photo/.
  • If photo/ URL requests arrives, the AWS S3 Web Server will find the photo/index.html HTML object and return a 200 OK.

Generally the index layout is better than the flat layout, as the Nuxt app will generally load, but the 302 redirect is not ideal and makes your site less useful to users for sharing and can slow down the page load time for the redirect.

Single Optimization

When the Nuxt static site is optimized by the nuxt-ss-fix tool into the Single layout, each S3 bucket HTML page object is named <page>, with no extension or placed in a folder. If the URL request does not include the trailing slash it will respond with 200 OK. If a URL request includes the trailing slash, it will get a 404 Not Found, but that can be a logical response and rarely used

For example:

  • If a photo URL request arrives, the AWS S3 Web Server will find a photo HTML object and return a 200 OK.
  • If photo/ URL requests arrives, the AWS S3 Web Server will not find a photo/index.html HTML object and return a 404 Not Found.

The natural user expectation is that photo is the page and photo/ is a directory, and the 404 Not Found response is logical.

Double Optimization

If you want to avoid the 404 Not Found response for URL with slashes in the Single layout, you can use the double optimization, which duplicates the HTML page object, for example, both photo and photo/index.html S3 object exists. Double the storage space is used, but both URL requests will work without redirects or 404s.

For example:

  • If a photo URL request arrives, the AWS S3 Web Server will find a photo HTML object and return a 200 OK.
  • If photo/ URL requests arrives, the AWS S3 Web Server will find a photo/index.html HTML object and return a 200 OK.

Tool Operation

The nuxtss-s3-fix tool requires you provide it an AWS S3 bucket as a parameter. And S3 bucket path starts with s3://. Examples: s3://bucket-name or s3://bucket-name/key

  1. nuxtss-s3-fix s3://my-nuxt-bucket

It requires an accurate sitemap.xml for scanning for page routes. It will scan for sitemap.xml file either:

  1. In the root of the S3 bucket
  2. specified to a sitemap file using the --sitemap-location <location> option. The specified sitemap file can be a local file, an https: file, or in another S3 bucket.

The tool can operate in two modes:

  1. generate commands (default)
  2. execute commands (with --execute-commands or -e option)

The Tool can optimize the AWS S3 Bucket into two different optimal layouts:

  1. Single layout (default)
  2. Double layout (with --double-layout or -2 option)

Generate Commands Mode

The default mode of operation is to generate AWS S3 CLI commands that you can run in your AWS S3 CLI context. The tool will output the commands to the console our you can redirect the output to a script file for later execution.

Note, however, that the commands are generated based on the current state of the S3 bucket and the sitemap.xml file at the time of execution. If the S3 bucket or sitemap.xml file changes after the commands are generated, the commands may not be valid anymore.

Further, since there is no AWS S3 bucket move operation, it is accomplished with a copy and remove operation. Given that we don't know the success of the generated copy operation, the tool only generates a remove command once the copy is successful. This means that you'll need to run the tool again to get the next command generation.

The sequence that the tool was designed to operate in is:

  1. Deploy a Nuxt.js static site (either generated with the Index (recommended) or Flat layout) to an AWS S3 bucket
  2. Run the tool to generate the copy commands.
  3. Run the copy commands in your AWS S3 CLI context.
  4. Verify that the site works as expected.
  5. Run the tool to generate the remove commands.
  6. Run the remove commands in your AWS S3 CLI context.
  7. Verify that the site works as expected.
  8. Run the tool again to ensure that all pages are copied and removed successfully or to re-generate any failed commands.

The tool will not generate a copy command for a page if a Single Layout HTML object already exists. It wasn't meant to generate commands to 'overwrite' the destination. This allows you to re-run the tool to generate commands, run the commands, re-run the tool, to generate commands for any pages that may have failed to be copied.

The tool will not generate a remove command for the Index or Flat HTML page objects unless the Single HTML page object already exists. For safety, the tool will not generate remove commands unless HTML page duplication exists. If only one copy of the page exists, it will not be removed.

Execute Commands Mode

With the --execute-commands or -e option, the tool will execute the generated AWS S3 CLI commands directly. This requires that the execution environment has an appropriate AWS S3 CLI context with the necessary permissions. The tool will output the results of each command execution to the console. Unlike the generate commands mode, the execute commands mode will perform the copy and remove operations directly assuming it the copy was successful first. Meaning if all the copy and remove operations are successful, you only need to run the tool once.

In this mode, since the tool is operating on the data, it is recommended to use --dry-run option first to see what operations would be performed without actually making any changes. Or with the generate command mode which allows you to see the the first commands that would be executed.

The sequence that the tool was designed to operate in for Execute Commands mode is:

  1. Deploy a Nuxt.js static site (either generated with the Index (recommended) or Flat layout) to an AWS S3 bucket
  2. Run the tool in your AWS S3 CLI context to execute commands and for either Single or Double layout.
  3. See if all the executions were successful. Rerun the tool if necessary to complete any failed operations.
  4. Verify that the site works as expected

Conclusion

The nuxtss-s3-fix tool provides a simple way to optimize your Nuxt.js static site HTML page objects hosted on an AWS S3 bucket for better social media sharing, SEO metadata, and quicker loading times. By converting the page objects into a Single or Double layout, you can avoid the quirks of the AWS S3 web server and provide a better user experience for your site visitors.