Deployment

When you build your Doctocat site using gatsby build, the output is static content: HTML, CSS, JavaScript, images, etc. Static content is incredibly easy and affordable to host with any deployment solution. We have landed on using Now for our deploys.

Deploying to Now

If you started with the Doctocat template, your site is already configured to deploy with Now. You're ready to set up the Now for GitHub integration. If you did not start with the Doctocat template, before you set up the Now for Github integration, you'll need to create a now.json file and add a now-build script to package.json:

// now.json
{
  "version": 2,
  "name": "my-site",
  "builds": [
    {
      "src": "package.json",
      "use": "@now/static-build",
      "config": {"distDir": "public"}
    }
  ]
}

// package.json
{
  "scripts": {
    ...
    "build": "gatsby build",
    "now-build": "npm run build"
  }
}

Once your site has the necessary configuration files and scripts, you can enable the Now for GitHub integration. You'll need to create a Now account, connect your GitHub account, then enable the integration for your repository. Check out the Now for GitHub docs for more detailed instructions.

After you have the GitHub integration set up, you should be able to access your site from a prefixed .now.sh domain.

Deploying to other providers

Check out Gatsby's Deploying and Hosting guides for more information about deploying to other providers.

Adding a primer.style path alias

1. Update gatsby-config.js

To make your site available from primer.style/my-site, start by setting a pathPrefix in your gatsby-config.js:

// gatsby-config.js
module.exports = {
+ pathPrefix: '/my-site',
}

2. Update package.json

Next, make sure your build script in package.json runs gatsby build with the --prefix-paths flag:

// package.json
{
  "scripts": {
-   "build": "gatsby build",
+   "build": "gatsby build --prefix-paths",
    "now-build": "npm run build"
  }
}

If this flag is not set, Gatsby will ignore your pathPrefix.

3. Update now.json

The --prefix-paths flag tells Gatsby to prefix paths used in the Link component and navigate helper with the pathPrefix value assigned in your gatsby-config.js file. However, --prefix-paths doesn't change where built files get stored in the build directory. This creates a mismatch between the links on your site and the actual paths to your files.

To fix this issue, you'll need to define a route in your now.json file that proxies /my-site/* to /* so that behind the scenes a path like /my-site/getting-started will find /getting-started.html in your build directory:

// now.json
{
  ...
  "routes": [
    {"src": "/my-site(/.*)?", "dest": "$1"},
  ]
}

If your site is located in a subdirectory, make sure the destination (dest) of your proxy route is the path to that subdirectory followed by $1. Here's what your now.json file might look like if your site is located in a subdirectory called docs:

// now.json
{
  ...
  "routes": [
    {"src": "/my-site(/.*)?", "dest": "/docs$1"},
  ]
}

In order to route branch deploys correctly, you'll also need to set up a route that redirects root route requests (my-site.now.sh) to your path prefix (my-site.now.sh/my-site):

// now.json
{
  ...
  "routes": [
    {"src": "/my-site(/.*)?", "dest": "/docs$1"},
+   {
+     "src": "/",
+     "status": 301,
+     "headers": {"Location": "/my-site"}
+   }
  ]
}

This is necessary because when your project lives in a subdirectory, there isn't any content for the site in the root of your deploy.

4. Update now.json in primer/primer.style

After everything is set up in your repository, open a pull request on the primer/primer.style repository to add your site to the routes list in now.json:

// now.json in primer/primer.style
{
  "routes": [
    {"src": "/components(/.*)?", "dest": "https://primer-components.now.sh"},
    {"src": "/css(/.*)?", "dest": "https://primer-css.now.sh"},
    {"src": "/design(/.*)?", "dest": "https://primer-design.now.sh"},
    {"src": "/blueprints(/.*)?", "dest": "https://primer-blueprints.now.sh"},
    {"src": "/presentations(/.*)?", "dest": "https://primer-presentations.now.sh"},
+   {"src": "/my-site(/.*)?", "dest": "https://my-site.now.sh"}
  ]
}

Once your pull request is approved and merged, you'll be able to access your site from primer.style/my-site. 🎉