How to use gatsby-source-filesystem plugin

gatsby-source-filesystem is a plugin for sourcing data into our Gatsby application from the local filesystem.

How to use gatsby-source-filesystem plugin

1. Install the plugin:

npm install gatsby-source-filesystem

2. Edit gatsby-config.js

// In gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `images`,
        path: `${__dirname}/src/images/`,
      },
    },
  ],
};

3. Query files using allFile Field

We can play with the GraphiQL in-browser IDE to see some data.

In this example, we have an images folder and add 3 sample images.

{
  allFile {
    totalCount
    nodes {
      size
      absolutePath
    }
  }
}

will show

{
  "data": {
    "allFile": {
      "totalCount": 3,
      "nodes": [
        {
          "size": 845342,
          "absolutePath": "/Users/hatruong/Code/React/gatsby-tutorial/src/images/image-1.jpg"
        },
        {
          "size": 1277574,
          "absolutePath": "/Users/hatruong/Code/React/gatsby-tutorial/src/images/image-2.jpg"
        },
        {
          "size": 1591364,
          "absolutePath": "/Users/hatruong/Code/React/gatsby-tutorial/src/images/image-3.jpg"
        }
      ]
    }
  },
  "extensions": {}
}

Explanation

• allFile points to image directory because we only have one instance
• node represents each file

4. Query Arguments

Query Arguments allow us to be more specific about the data that we will get back.

Example 1: Limit the response to 2 items

{
  allFile(limit:2) {
    nodes {
      size
      absolutePath
    }
  }
}

Example 2: Skip the first 2 items

{
  allFile(skip:2) {
    nodes {
      size
      absolutePath
    }
  }
}

Example 3: Sort by size in the descending direction

{
  allFile(sort:{fields:size, order:DESC}) {
    nodes {
      size
      absolutePath
    }
  }
}

5. Query files using File Field

We can also query each item using File field

{
  file(relativePath: {eq: "image-2.jpg"}) {
    size
    relativePath
  }
}

6. SourceInstanceName

If we have more than 1 folder, such as posts folder, SourceInstanceName will be useful.

src
├── images
│   ├── image-1.jpg
│   ├── image-2.jpg
│   └── image-3.jpg
└── posts
    └── post-1.txt

// In gatsby-config.js
module.exports = {
  siteMetadata: {
    title: "Gatsby tutorial",
    description: "Hello",
    author: "@hatrcode",
    data: ["item 1", "item 2"],
    person: { name: "Anna", age: 20 },
  },
  plugins: [
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `images`,
        path: `${__dirname}/src/images/`,
      },
    },
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `posts`,
        path: `${__dirname}/src/posts/`,
      },
    },
  ],
};

In GraphiQL

{
  allFile(filter: {sourceInstanceName: {eq: "posts"}}) {
    nodes {
      relativePath
      size
    }
  }
}

will show

{
  "data": {
    "allFile": {
      "nodes": [
        {
          "relativePath": "post-1.txt",
          "size": 0
        }
      ]
    }
  },
  "extensions": {}
}