{"componentChunkName":"component---src-templates-post-template-js","path":"/note-how-to-deploy-gatsby-spa-en","result":{"data":{"markdownRemark":{"id":"993488a2-a161-5376-afad-548c87066abb","html":"
\n

This page has been machine-translated from the original page.

\n
\n

This may come as a surprise, but for various reasons I decided to move my blog.

\n

I plan to gradually migrate articles from my old blog to this one (it is a hassle because I have to do it manually…).

\n

For the new blog, I used the MIT-licensed Gatsby template gatsby-starter-lumen as the base.

\n

In this article, I am recording the work I carried out before publishing the new blog as personal notes.

\n\n

Table of Contents

\n\n

The Environment Built in This Article

\n

This time I am assuming the following environment.

\n

Local Development Environment

\n\n

This will be the environment actually used to write articles.

\n

Markdown will be edited in Typora on the Windows host, and behavior will be checked in a Docker container where the Gatsby environment has been built.

\n

By the way, Typora is a highly capable Markdown editor.

\n

It recently became paid software, but it is a one-time license of about $15, so I highly recommend it.

\n

Reference: Typora

\n

Deployment Environment

\n

The blog created locally will be deployed and published on GitHub Pages.

\n

It will also be configured so that it can be published using a custom domain.

\n

Build the Gatsby Environment

\n

Install Docker

\n

Currently, I think there are two main ways to install Docker on Windows:

\n\n

Reference: Install Docker Desktop on Windows | Docker Documentation

\n

This time I planned to run Docker commands from PowerShell, so I installed Docker Desktop for Windows.

\n

Incidentally, Docker Desktop for Windows became a topic of discussion a little while ago when its license became paid, but it is still free for personal use.

\n

As for the installation method, it is enough to run the installer downloaded from the link in the documentation above.

\n

Create a Container for Gatsby Development

\n

Next, build the Gatsby development environment.

\n

I basically referred to the following documentation and created a Dockerfile like this.

\n

Reference: Part 0: Set Up Your Development Environment | Gatsby

\n
FROM ubuntu:20.04\nENV TZ=Asia/Tokyo\n\nRUN mkdir -p /app/blog\nENV HOME=/app/\nWORKDIR /app\n\nRUN apt update && apt upgrade -y\nRUN apt install tzdata -y\nRUN apt install curl git python wget -y\nRUN apt install nodejs npm -y\nRUN npm install n -g\nRUN n stable\n\nRUN apt purge -y nodejs npm\nRUN apt autoremove -y\n\nRUN node -v\nRUN npm install -g gatsby-cli\nRUN npm install gh-pages --save-dev\n\nRUN chown root:root ./* -R\nWORKDIR $HOME/blog\nEXPOSE 8000
\n

After installing the latest NodeJS on top of an Ubuntu 20.04 container, I installed gatsby-cli.

\n

This makes the gatsby command available.

\n

Also, gh-pages is the package used when deploying to GitHub Pages.

\n

I will describe the details later.

\n

The image I created this time is published as kashiwabayuki/gatsby-env, so you can also pull it with the following command.

\n
docker pull kashiwabayuki/gatsby-env
\n

Create the Gatsby Blog

\n

After creating the container image, you need to log in to the container and perform some setup only when setting up the environment.

\n

In a PowerShell environment, you can log in to the container with the following command.

\n
$pwddir = (Get-Location -PSProvider FileSystem).Path\ndocker run -it --rm --volume $pwddir/src:/app -p 8000:8000 kashiwabayuki/gatsby-env
\n

With this command, I log in while mapping the local volume src/ to the container’s home directory, /app.

\n

After logging in, create the Gatsby content with gatsby-starter-lumen using the following command.

\n
gatsby new blog https://github.com/alxshelepenok/gatsby-starter-lumen
\n

Next, run the following command under the newly generated blog directory.

\n
npm install\n# If this causes an error, run npm install --legacy-peer-deps.
\n

If the npm install command fails, it is a good idea to try again with the --legacy-peer-deps option.

\n

This completes the initial blog setup.

\n

If the local server starts when you run the following command, you are done.

\n
gatsby develop -H 0.0.0.0
\n

Troubleshooting: EACCES Permission Error for /app/.npm/sentry-cli

\n

The exact conditions are inconsistent so I am not sure of the cause, but when running npm install, a permission error such as EACCES: permission denied, mkdir '/app/.npm/sentry-cli' may occur.

\n

Because the Docker user is root, I would not normally expect this to happen, but it occurred several times in my environment.

\n

As a workaround, I was able to resolve it by explicitly setting the owner to root for the directory where the error occurs in the Dockerfile, like this.

\n
RUN chown root:root ./* -R
\n

Sometimes the error does not occur at all, so honestly I still do not know the cause…

\n

Troubleshooting: socialImage Error

\n

Incidentally, you may see an error like the following at this point.

\n

It seems to occur when the value of socialImage for each article is empty, when the target image does not exist, or when the static directory cannot be resolved.

\n
Field \"socialImage\" must not have a selection since type \"String\" has no subfields.
\n

The procedure in this article does not have that problem, but if you run gatsby develop on a Windows host, you may encounter this issue because of a known problem where the static directory cannot be resolved.

\n

To fix it, try the workaround described in the following issue, or use the container image described in this article.

\n

Reference: Field “socialImage” must not have a selection since type “String” has no subfields. · Issue #761 · alxshelepenok/gatsby-starter-lumen

\n

Change the Gatsby Settings

\n

At this point, the minimum Gatsby environment is in place, so next I will do the initial setup.

\n

Change the Profile Settings

\n

Basic profile and SNS settings can be changed in blog/config.js.

\n

The actual settings look like this.

\n
'use strict';\n\nmodule.exports = {\n  url: 'https://kashiwaba-yuki.com',\n  pathPrefix: '/',\n  title: 'Kaeru no Himitsukichi',\n  subtitle: '',\n  copyright: 'All rights reserved 2022 Kaeru-no-Himitsukichi.',\n  disqusShortname: '',\n  postsPerPage: 4,\n  googleAnalyticsId: '',\n  useKatex: false,\n  menu: [\n    {\n      label: 'All Articles',\n      path: '/'\n    },\n    {\n      label: 'Development',\n      path: '/tag/development'\n    },\n    {\n      label: 'Notes',\n      path: '/category/note'\n    }\n  ],\n  author: {\n    name: 'Kashiwaba',\n    photo: '/avatar.png',\n    bio: 'A hobby programmer who wants to become a reverse engineer.',\n    contacts: {\n      email: '',\n      facebook: '',\n      telegram: '',\n      twitter: 'yuki_kashiwaba',\n      github: 'kash1064',\n      rss: '',\n      vkontakte: '',\n      linkedin: '',\n      instagram: '',\n      line: '',\n      gitlab: '',\n      weibo: '',\n      codepen: '',\n      youtube: '',\n      soundcloud: '',\n      medium: '',\n    }\n  }\n};
\n

In particular, for SNS accounts under contacts, items you do not want to display must be left blank rather than commented out.

\n

If you comment them out, an error occurs.

\n

Site Design Settings

\n

If you want to change the site design, you need to edit the template for each element.

\n

This time I did not change the base layout, and only changed some colors and similar settings.

\n

If you want to change the base design, edit blog/src/assets/scss/base/_generic.scss.

\n

The contents look like this, and you can change text size, colors, fonts, and so on for each element.

\n
/** \n * Generic\n */\nhtml {\n  font-size: $typographic-root-font-size;\n}\n\nbody {\n  margin: 0 0 0 calc(100vw - 100%);\n  font-family: $typographic-font-family;\n  color: $typographic-base-font-color;\n  line-height: $typographic-base-line-height;\n  font-size: $typographic-base-font-size;\n  -ms-text-size-adjust: 100%;\n  -webkit-text-size-adjust: 100%;\n  text-rendering: optimizeLegibility;\n  -webkit-font-smoothing: antialiased;\n  -moz-osx-font-smoothing: grayscale;\n}\n\nh1,\nh2,\nh3,\nh4,\nh5,\nh6 {\n  font-family: $typographic-font-family;\n  font-weight: 600;\n}\n\nh1 {\n  font-size: $typographic-base-font-size * 1.8;\n  @include line-height(1.8);\n  @include margin-top(4);\n  @include margin-bottom(1);\n}\n\nh2 {\n  font-size: $typographic-base-font-size * 1.6875;\n  @include line-height(1.5);\n  @include margin-top(2);\n  @include margin-bottom(.5);\n}\n\nh3 {\n  font-size: $typographic-base-font-size * 1.375;\n  @include line-height(1);\n  @include margin-top(2);\n  @include margin-bottom(.5);\n}\n\n{{ omitted }}
\n

Also, the link colors and the sizes of some elements are configured by the variables defined in blog/src/assets/scss/_variables.scss.

\n

For example, if you want to change the link color, you need to change $color-primary.

\n

The maximum content width is set by $layout-post-single-width.

\n

For that reason, I also changed some of the base colors on my blog as follows.

\n
// Colors\n$color-base: #222;\n$color-primary: #918D40;\n$color-secondary: #A9D159;\n\n$color-white: #FFF;\n$color-gray: lighten($color-base, 40%);\n$color-gray-border: lighten($color-base, 77%);\n$color-gray-bg: lighten($color-base, 79%);
\n

Add and Edit Content

\n

When you use gatsby-starter-lumen, two content types are prepared by default.

\n\n

Both are placed under the blog/content/ directory.

\n

Gatsby searches the files under blog/content/ according to the definitions in blog/src/cms/index.js and identifies them as pages of the specified format.

\n

For that reason, by default all blog pages must be placed under blog/content/posts, but if you want to add a custom directory such as notes here, you need to associate the directory name with a template in CMS.registerPreviewTemplate as shown below.

\n
// @flow strict\nimport CMS from 'netlify-cms-app';\nimport PagePreview from './preview-templates/page-preview';\nimport PostPreview from './preview-templates/post-preview';\n\nCMS.registerPreviewTemplate('pages', PagePreview);\nCMS.registerPreviewTemplate('posts', PostPreview);\nCMS.registerPreviewTemplate('notes', PostPreview);
\n

Remove the Directory Name from Article URLs

\n

By default, article URLs are in the following format.

\n
https://<custom-domain>/<directory-name-containing-the-article>/<article-slug>
\n

If <directory-name-containing-the-article> is embedded in the URL, the URL will change every time you move the Markdown file to a different directory in the future, which is not desirable.

\n

So I change the settings so that <directory-name-containing-the-article> is not included in the URL.

\n

Rewrite createNodeField in blog/gatsby/on-create-node.js as follows.

\n
if (node.internal.type === 'MarkdownRemark') {\n  if (typeof node.frontmatter.slug !== 'undefined') {\n    const dirname = getNode(node.parent).relativeDirectory;\n    createNodeField({\n      node,\n      name: 'slug',\n      // value: `/${dirname}/${node.frontmatter.slug}`\n      value: `/${node.frontmatter.slug}`\n    });\n};
\n

This removes the directory name from the URLs generated at deploy time.

\n

Change the Syntax Highlighting Settings

\n

The syntax highlighting in the theme used this time uses Prism.js.

\n

Therefore, if you want to customize the syntax highlighting, you need to generate CSS from the following page and replace static\\css\\prismjs\\theme.min.css.

\n

Reference: Download ▲ Prism

\n

Incidentally, my blog uses the following configuration.

\n
/* PrismJS 1.27.0\nhttps://prismjs.com/download.html#themes=prism-tomorrow&languages=markup+css+clike+javascript+aspnet+bash+c+csharp+cpp+csv+dart+django+go+http+java+makefile+markdown+markup-templating+nginx+php+powershell+python+ruby+rust+sql+typescript+yaml */\ncode[class*=language-],pre[class*=language-]{color:#ccc;background:0 0;font-family:Consolas,Monaco,'Andale Mono','Ubuntu Mono',monospace;font-size:1em;text-align:left;white-space:pre;word-spacing:normal;word-break:normal;word-wrap:normal;line-height:1.5;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-hyphens:none;-moz-hyphens:none;-ms-hyphens:none;hyphens:none}pre[class*=language-]{padding:1em;margin:.5em 0;overflow:auto}:not(pre)>code[class*=language-],pre[class*=language-]{background:#2d2d2d}:not(pre)>code[class*=language-]{padding:.1em;border-radius:.3em;white-space:normal}.token.block-comment,.token.cdata,.token.comment,.token.doctype,.token.prolog{color:#999}.token.punctuation{color:#ccc}.token.attr-name,.token.deleted,.token.namespace,.token.tag{color:#e2777a}.token.function-name{color:#6196cc}.token.boolean,.token.function,.token.number{color:#f08d49}.token.class-name,.token.constant,.token.property,.token.symbol{color:#f8c555}.token.atrule,.token.builtin,.token.important,.token.keyword,.token.selector{color:#cc99cd}.token.attr-value,.token.char,.token.regex,.token.string,.token.variable{color:#7ec699}.token.entity,.token.operator,.token.url{color:#67cdcc}.token.bold,.token.important{font-weight:700}.token.italic{font-style:italic}.token.entity{cursor:help}.token.inserted{color:green}\n\n# Update\np > code[class*=language-text]{background:#F9F9F9 !important; color: #2d2d2d !important;}\nli > code[class*=language-text]{background:#F9F9F9 !important; color: #2d2d2d !important;}
\n

The last line defines the background color and text color for inline preformatted text embedded in the body.

\n

Configure Typora

\n

One very useful feature of the Markdown editor Typora, which I use all the time, is that when you copy and paste images it automatically saves them to a local folder of your choice.

\n

With Gatsby, images under blog/static/media can be accessed via /media.

\n

So in Typora I configured it as follows so that pasted images are placed in any directory under blog/static/media.

\n

\n \n \n \n \n \n \n \n \n

\n

This allows blog pages to reference the appropriate images after deployment.

\n

Deploy to GitHub Pages

\n

Now that the basic shape is in place, it is finally time to deploy.

\n

The procedure is basically based on the official instructions.

\n

Reference: How Gatsby Works with GitHub Pages | Gatsby

\n

First, you need a GitHub repository for publishing.

\n

The repository needs to be public.

\n

Once the push to the public repository is complete, you can begin deploying to GitHub Pages.

\n

Path Settings

\n

This time I use a custom domain, so I set / in pathPrefix of blog\\gatsby-config.js.

\n
module.exports = {\n  // pathPrefix: siteConfig.pathPrefix,\n  pathPrefix: \"/\",\n}
\n

This setting is necessary so that the proper path is used when accessing the site by URL.

\n

On the other hand, if you do not specify a custom domain, set the repository name in pathPrefix.

\n

Create a Custom Deployment Script

\n

Next, configure the deployment script.

\n

Set scripts>deploy in blog\\package.json as follows.

\n
\"scripts\": {\n    \n  \"deploy\": \"rm -rf node_modules/.cache/gh-pages && gatsby clean && gatsby build --prefix-paths && echo 'kashiwaba-yuki.com' > public/CNAME && gh-pages -d public -b pages\",\n\n},
\n

rm -rf node_modules/.cache/gh-pages removes past cache so that errors do not occur during the build.

\n

gatsby clean && gatsby build --prefix-paths builds the content with the gatsby command.

\n

gatsby clean is required to make sure your changes are reflected.

\n

echo 'kashiwaba-yuki.com' > public/CNAME is used to place a CNAME file for using a custom domain in the public directory.

\n

Without this, the custom domain is removed every time you deploy.

\n

gh-pages -d public -b pages uses gh-pages to place the built content in the pages branch.

\n

Because this pushes to a Git repository, you need to make sure you can push to the repository from inside the container.

\n

Pages Settings

\n

Once you get this far, the rest is easy.

\n

Open the settings screen of the public repository, and under “Pages” specify the publishing branch pages to publish with GitHub Pages.

\n

\n \n