# How to Configure gatsby-source-filesystem and How It Differs From Other Gatsby Source Plugins

> Learn how to configure gatsby-source-filesystem to source local files into Gatsby nodes. Understand its differences from remote API source plugins for efficient data management.

- Repository: [Gatsby/gatsby](https://github.com/gatsbyjs/gatsby)
- Tags: how-to-guide
- Published: 2026-03-06

---

**gatsby-source-filesystem is the core source plugin that converts local files into Gatsby File nodes using a Chokidar-based file watcher, while other source plugins fetch data from remote APIs and create specialized node types like ContentfulAsset or WordPressPost.**

The `gatsby-source-filesystem` plugin serves as the bridge between your local disk and Gatsby's GraphQL data layer. As part of the gatsbyjs/gatsby monorepo, this plugin implements the standard source plugin contract through the `sourceNodes` API in [`packages/gatsby-source-filesystem/src/gatsby-node.js`](https://github.com/gatsbyjs/gatsby/blob/main/packages/gatsby-source-filesystem/src/gatsby-node.js), specializing in file system operations rather than remote data fetching.

## What Is gatsby-source-filesystem?

`gatsby-source-filesystem` creates **generic `File` nodes** from any file type on your local disk. Each node includes fields such as `relativePath`, `extension`, `size`, and `modifiedTime`, plus a crucial `sourceInstanceName` field that identifies which plugin instance created the node.

This plugin uses an **XState state machine** combined with **Chokidar** to watch for file changes, enabling incremental builds that only update modified nodes. The core node creation logic resides in [`packages/gatsby-source-filesystem/src/create-file-node.js`](https://github.com/gatsbyjs/gatsby/blob/main/packages/gatsby-source-filesystem/src/create-file-node.js).

## Key Differences Between gatsby-source-filesystem and Other Source Plugins

While all source plugins implement the `sourceNodes` API, they differ significantly in data origin, node types, and configuration patterns.

### Data Origin and Node Types

**gatsby-source-filesystem** sources data from your **local filesystem**, creating generic `File` nodes that any transformer plugin can consume. In contrast, remote source plugins like `gatsby-source-contentful` or `gatsby-source-wordpress` fetch data from external APIs, creating plugin-specific node types such as `ContentfulAsset` or `WordPressPost`.

### Configuration and Multiple Instances

`gatsby-source-filesystem` supports **multiple plugin instances** in [`gatsby-config.js`](https://github.com/gatsbyjs/gatsby/blob/main/gatsby-config.js), each requiring a unique `name` option that becomes the `sourceInstanceName`. This enables granular sourcing from separate directories:

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

```

Remote source plugins typically support only a single instance per service unless they explicitly implement `typePrefix` or `spaceId` distinctions.

### File Watching and Incremental Builds

`gatsby-source-filesystem` provides **built-in file watching** via Chokidar and an XState state machine that tracks file additions, changes, and deletions. This enables true incremental builds where only changed files trigger node updates.

Remote source plugins rely on **polling intervals** or **webhook-based cache invalidation**, requiring network requests to detect changes rather than watching local files.

### Performance Optimization

`gatsby-source-filesystem` offers **performance-specific options** like `fastHash` (to skip MD5 hashing on large files) and `ignore` globs (to exclude unwanted paths). These optimizations address filesystem-specific concerns like hashing overhead and directory traversal.

Remote source plugins optimize through pagination settings (`pageLimit`) and cache TTLs, but do not deal with local file hashing.

## How to Configure gatsby-source-filesystem

### Basic Single Source Configuration

The minimal configuration requires `name` and `path` options:

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

```

The `name` option becomes the `sourceInstanceName` field, enabling GraphQL filtering by source.

### Multiple Source Instances

Declare separate instances to organize different content types:

```javascript
module.exports = {
  plugins: [
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `content`,
        path: `${__dirname}/src/content/`,
      },
    },
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `images`,
        path: `${__dirname}/src/images/`,
        ignore: [`**/*.svg`],
        fastHash: true,
      },
    },
  ],
}

```

Query specific instances using the `sourceInstanceName` filter:

```graphql
{
  allFile(filter: { sourceInstanceName: { eq: "content" } }) {
    nodes {
      relativePath
      extension
      birthTime
    }
  }
}

```

### Advanced Configuration Options

**Ignore Patterns**

Use the `ignore` option with glob patterns to exclude files from processing:

```javascript
{
  resolve: `gatsby-source-filesystem`,
  options: {
    name: `images`,
    path: `${__dirname}/src/images/`,
    ignore: [`**/*.svg`, `**/thumbnails/**`],
  },
}

```

**Fast Hashing**

Enable `fastHash` to skip MD5 hashing of file contents, improving startup performance:

```javascript
{
  resolve: `gatsby-source-filesystem`,
  options: {
    name: `media`,
    path: `${__dirname}/src/media/`,
    fastHash: true,
  },
}

```

## Creating URL Slugs With createFilePath

The `createFilePath` helper from [`packages/gatsby-source-filesystem/src/create-file-path.js`](https://github.com/gatsbyjs/gatsby/blob/main/packages/gatsby-source-filesystem/src/create-file-path.js) generates URL-friendly paths from file system locations:

```javascript
// gatsby-node.js
const { createFilePath } = require(`gatsby-source-filesystem`);

exports.onCreateNode = ({ node, getNode, actions }) => {
  const { createNodeField } = actions;
  if (node.internal.type === `MarkdownRemark`) {
    const slug = createFilePath({ node, getNode, basePath: `src/content` });
    createNodeField({
      node,
      name: `slug`,
      value: `/blog${slug}`,
    });
  }
};

```

This utility automatically handles index files and directory structures, converting [`src/content/my-post/index.md`](https://github.com/gatsbyjs/gatsby/blob/main/src/content/my-post/index.md) to `/my-post/`.

## Comparing With Remote Source Plugins

While `gatsby-source-filesystem` handles local assets, remote plugins like `gatsby-source-contentful` fetch external data:

```javascript
module.exports = {
  plugins: [
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `assets`,
        path: `${__dirname}/static/`,
      },
    },
    {
      resolve: `gatsby-source-contentful`,
      options: {
        spaceId: process.env.CONTENTFUL_SPACE_ID,
        accessToken: process.env.CONTENTFUL_ACCESS_TOKEN,
        downloadLocal: true,
      },
    },
  ],
}

```

The `downloadLocal: true` option in Contentful mirrors `gatsby-source-filesystem` behavior by storing remote assets locally, creating `File` nodes that work with `gatsby-plugin-image`.

## Summary

- **gatsby-source-filesystem** creates generic `File` nodes from local disk paths, while remote plugins create specific node types like `ContentfulAsset` or `WordPressPost`.
- Configure multiple plugin instances using unique `name` options to enable `sourceInstanceName` filtering in GraphQL.
- Leverage built-in file watching via Chokidar and XState for incremental builds during development.
- Optimize performance with `fastHash` to skip MD5 hashing and `ignore` globs to exclude unnecessary files.
- Use the `createFilePath` helper from [`packages/gatsby-source-filesystem/src/create-file-path.js`](https://github.com/gatsbyjs/gatsby/blob/main/packages/gatsby-source-filesystem/src/create-file-path.js) to generate URL slugs from file paths.

## Frequently Asked Questions

### What is the difference between gatsby-source-filesystem and gatsby-source-contentful?

**gatsby-source-filesystem** reads files from your local disk and creates generic `File` nodes with fields like `relativePath` and `extension`, utilizing a Chokidar file watcher for incremental updates. In contrast, **gatsby-source-contentful** fetches data from the Contentful API, creates specific node types such as `ContentfulAsset` and `ContentfulEntry`, and relies on webhooks or polling for cache invalidation rather than file watching.

### How do I query only files from a specific gatsby-source-filesystem instance?

Use the `sourceInstanceName` field in your GraphQL query, which corresponds to the `name` option you configured in [`gatsby-config.js`](https://github.com/gatsbyjs/gatsby/blob/main/gatsby-config.js). For example, if you set `name: 'content'`, filter with `allFile(filter: { sourceInstanceName: { eq: "content" } })` to retrieve only files from that specific directory.

### What does the fastHash option do in gatsby-source-filesystem?

The `fastHash` option skips MD5 hashing of file contents during node creation, significantly improving startup performance when working with large media files. When enabled, the plugin relies on file metadata like modification time rather than content hashing to detect changes, which is faster but slightly less robust for detecting content changes when timestamps remain identical.

### Can I use gatsby-source-filesystem alongside remote source plugins?

Yes, you can combine `gatsby-source-filesystem` with remote plugins like `gatsby-source-contentful` or `gatsby-source-wordpress` in the same project. This hybrid approach allows you to manage static assets locally while pulling structured content from headless CMSs, and some remote plugins even offer `downloadLocal` options to mirror remote assets as local File nodes compatible with the filesystem plugin's ecosystem.