Gatsby: what's the difference between basepath and path prefix?

Question

I don't understand the difference between basepath and path prefix in Gatsby, and when to use each feature

Basepath: https://www.gatsbyjs.org/tutorial/part-seven/

Path prefix: https://www.gatsbyjs.org/docs/path-prefix/

Answer 1

TL:DR

pathPrefix has much more impact on your site — it add a prefix to the generated url of all your pages and assets. basePath is just a helper for generating slug from your filesystem — In my experience with Gatsby I rarely use it at all.

---

pathPrefix

It appends a prefix to url of all your pages & assets. This way, you can deploy Gatsby site as a sub directory of another site.

Without Prefix             | With 'blog' Prefix
---------------------------|--------------------------------
myblog.com/                | myblog.com/blog
myblog.com/hello/          | myblog.com/blog/hello
myblog.com/image-123.png   | myblog.com/blog/image-123.png

---

basePath

It's an option of createFilePath which helps you create slug from your project structure. It doesn't affect whether you're serving your Gatsby from root or not.

If your project directory is like this:

<root>
  |--content
  |     |--writing
  |     |    `--page1.md
  |     `--images
  |          `--cat.md
  |
  |--gatsby-config.js
 ...

And you set this in your gatsby-config.js

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-filesystem',
      options: {
        path: `${__dirname}/content`,
        name: 'content'
      }
    }
  ]
}

Then createFilePath will return this slug for your file: writing/page1/, which maybe not what you want. Maybe you want it to be /page1/. In this case, setting basePath to writing will return /page1/.

Answer 2

Understanding path generation in Gatsby is tricky, because there are many factors at play:

• how do you set up your project directory?
• how do you configure gatsby-source-filesystem?
• in case you create pages programmatically in gatsby-node.js, what did you pass to the path field of the createPages API?

Since the OP said that all of their site URLs were prefixed with blog/, that means they had set up path prefix to serve the whole site at the blog/ path relative to the root of their domain. basePath has nothing to do with this.

Unless you are very sure that you want to serve your whole Gatsby site at a different path other than the root / of the domain, I suggest you don't do anything to path prefix.

Continuing from Derek Nguyen's example:

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-filesystem',
      options: {
        path: `${__dirname}/content`,
        name: 'content'
      }
    }
  ]
}

In gatsby-node.js, when you call the function createFilePath of gatsby-source-filesystem, you will get relative paths to the two Markdown files as followed:

• /writing/page1
• /images/cat

Then, if you create pages followed this Gatsby tutorial, those files should be generated into two HTML pages at:

• localhost:8000/blog/writing/page1
• localhost:8000/blog/images/cat

In this case, whether you use basePath or not doesn't matter. It is simply a helper function to remove a common path from your file path. You can't remove /blog because it is set up by path prefix.

However, suppose you decide to move cat.md from /images directory to /writing, basePath can come in handy. Actually, you should, because there is no reason why cat.md should be under /images directory.

<root>
  |--content
  |     |--writing
  |     |    `--page1.md
             `--cat.md
  |
  |--gatsby-config.js
 ...

Now, the path generated for each Markdown file will changed:

• /writing/page1/
• /writing/cat/

You can remove writing from the urls by passing it to basePath as followed.

const { createFilePath } = require('gatsby-source-filesystem')
exports.onCreateNode({ node, getNode }) => {
  if (node.internal.type === 'MarkdownRemark') {
    console.log(createFilePath({ node, getNode, basePath: 'writing' }))
  }
}

Restart the development server and you should see your markdown pages will be served at:

• localhost:8000/blog/page1
• localhost:8000/blog/cat