Using Gatsby with platformOS

This use case describes how to configure Gatsby(a free and open source framework based on React) to work with platformOS. Through the example of using Gatsby, this article also gives you an overview of how to use any static site generator with platformOS.

Gatsby and platformOS

In the pursuit of performance, flexibility, and developer experience a lot of front-end developers turned their heads to static site generators like Gatsby.

Gatsby is a static site generator based on React.js that became popular because of its good performance, documentation, plugins ecosystem, and integrations with hostings.

Gatsby has a very nice architecture, where data can be pulled on build time from various sources to build static HTML, or during runtime in the browser using standard AJAX using React.

Read more about how Gatsby connects can pull data from multiple sources.

Because the output of static site generators is assets and HTML files, platformOS can be used as a hosting platform for that kind of content.

Using static site generators with platformOS

No matter which static site generator you choose for your project (there are plenty), you always have to consider the same three steps when using it with platformOS.

Pages (routes)

• Entry file should be named index.html. That's usually the default.
• To make URLs pretty, routes should be like this: about-us/index.html. For example, if you want to have a /contact page, the best way is to have the app/views/pages/contact/index.html file. That's usually also the default.
• HTML files need to land in the app/views/pages directory. This you have to do yourself.

Assets

All other files (assets: js, css, images, fonts, etc.) need to be in the app/assets directory. This you have to do yourself.

It is a good practice to use asset_path.

Migration

For our example migration we used the official Gatsby Blog repository.

It includes Markdown processing (all the blog posts are written in Markdown), image generation using sharp, and a couple more features.

After building the project by default you will get a lot of files in the public/ directory. This is where output files are located. By default, all files are generated there with no separation. We want a little bit more structure.

Assets

To put all the assets into the public/assets directory instead of just public/ we use gatsby-plugin-asset-path.

$ npm i gatsby-plugin-asset-path

And activate it:

gatsby-config.js

module.exports = {
+  assetPrefix: "assets/",
...
plugins: [
+ {
+   resolve: "gatsby-plugin-asset-path",
+ },

Gatsby also needs a --prefix-paths flag in its build command to make use of this option:

package.json

+ "build": "gatsby build --prefix-paths",

We will also add gatsby-plugin-no-sourcemaps because we don't need sourcemaps.

$ npm i gatsby-plugin-no-sourcemaps

plugins: [
+ {
+   resolve: "gatsby-plugin-no-sourcemaps",
+ },

Now assets are in a separate directory and the public/ directory is much cleaner:

$ ls -l public
404
404.html
assets
chunk-map.json
favicon-32x32.png
favicon.ico
hello-world
icons
index.html
manifest.webmanifest
my-second-post
new-beginnings
robots.txt
webpack.stats.json

Now all we need to do is to move assets to app/assets. We chose rsync and basic bash commands for that task.

rsync -a -m --include '*/' --exclude '*.html' public app && \
rsync -a -v app/public/assets/ app/public && rm -rf app/public/assets && \
mv -f app/public app/assets

The first line copies all non .html files from the public directory to app/public while preserving the directory structure.
The second line flattens the structure, because some files are now in app/public/assets and we want them in app/public. This step is an intermediary step before the structure is stabilized.
The third line renames app/public to app/assets as a final step.

Pages

The public directory has some directories with index.html files inside of them. Those are our pages.

Let's use rsync to move them to the correct place.

rsync -a -m --include '*/' --include '*.html' --exclude '*' public app/views && \
mv -f app/views/public app/views/pages

The first line is copies HTML files from public to views preserving the directory structure.
The second line renames app/views/public to app/views/pages as a final step.

Automation

Now that we have commands to do the migration for us, let's make our build more automated using npm tasks.

package.json

+ "prepare:html": "rsync -a -m --include '*/' --include '*.html' --exclude '*' public app/views && mv -f app/views/public app/views/pages",
+ "prepare:assets": "rsync -a -m --include '*/' --exclude '*.html' public app && mv -f app/public app/assets",
+ "prebuild": "rm -rf public app/assets app/views/pages && mkdir -p app/views",
  "build": "gatsby build --prefix-paths",

Now, when we run npm run build it will prepare empty directories, build the Gatsby site, and move the necessary files into their proper places.

Result

The only thing left to do is to deploy the page.

pos-cli deploy production

You can find the result at: https://gatsby-blog.prod01.oregon.platform-os.com/
You can find the source code of this project on GitHub: https://github.com/mdyd-dev/demo-gatsby

Notes on using our CDN

Because assets can be accessed using relative paths to the Instance domain, this is all there is to it to make it work, but if you want to make it even faster, you should use our CDN.

There are two ways to make this happen:

1. Using the asset_url Liquid filter
2. Setting up your asset builder to prefix URLs with your CDN path. There is a lot of ways to do it, two of them are the following:
   • One way of doing it we presented in the use case about Connecting an Angular Single Page Application with platformOS
   • Another way is to use the webpack-require-from plugin (we use it in our documentation project: webpack config, Liquid code)

Read more on assets.

Although Gatsby tried to implement support for CDN-hosted assets our minimal experience with Gatsby didn't allow us to use it with success. If you know how to leverage it, feel free to create an issue/PR in our documentation repo with a hint.