# gatsby-page-utils

> Gatsby library that helps creating pages

Latest version **3.16.0** (published 2026-01-26) · MIT license · 0 weekly downloads

## Install

```sh
npm install gatsby-page-utils
pnpm add gatsby-page-utils
yarn add gatsby-page-utils
bun add gatsby-page-utils
```

## Health

**Score 70/100 (B)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high maintenance score; popular repo; extremely popular.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.16.0 |
| Published | 2026-01-26 |
| First published | 2019-06-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18.0.0 <26 |
| Dependencies | 8 |
| Unpacked size | 57.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 55943 |
| Author | Yvonnick FRIN |
| Maintainers | pieh, kathmbeck, serhalp-netlify, mlgualtieri-gatsby, wardpeet |
| Keywords | gatsby |

## Links

- npm: https://www.npmjs.com/package/gatsby-page-utils
- Repository: https://github.com/gatsbyjs/gatsby
- Homepage: https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-page-utils#readme
- Issues: https://github.com/gatsbyjs/gatsby/issues
- npm.io page: https://npm.io/package/gatsby-page-utils

## Dependencies (8)

- [glob](https://npm.io/package/glob.md) ^7.2.3
- [lodash](https://npm.io/package/lodash.md) ^4.17.21
- [bluebird](https://npm.io/package/bluebird.md) ^3.7.2
- [chokidar](https://npm.io/package/chokidar.md) ^3.6.0
- [micromatch](https://npm.io/package/micromatch.md) ^4.0.5
- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.20.13
- [fs-exists-cached](https://npm.io/package/fs-exists-cached.md) ^1.0.0
- [gatsby-core-utils](https://npm.io/package/gatsby-core-utils.md) ^4.16.0

## Recent versions

- 3.16.0 (latest) — 2026-01-26
- 3.17.0-next.0 (next) — 2025-11-27
- 3.10.0-alpha-adapters.165 (alpha-adapters) — 2023-07-14
- 1.15.0 (latest-v3) — 2022-12-07
- 2.25.0 (latest-v4) — 2022-12-07
- 3.0.0-alpha-drupal-proxyurl.14 (drupal-proxyurl) — 2022-11-22
- 2.14.0-alpha-transformer-json.26 (alpha-transformer-json) — 2022-10-12
- 3.0.0-alpha-v5.d20221012t101120.57 (alpha-v5) — 2022-10-12
- 2.23.0-alpha-preview-gh-api.26 (preview-gh-api) — 2022-09-08
- 2.23.0-alpha-9689ff.25 (alpha-9689ff) — 2022-08-31
- 2.20.0-mdxv4-rc.124 (mdxv4-rc) — 2022-07-27
- 2.18.0-alpha-drupal-self-reference.18 (drupal-self-reference) — 2022-07-19
- 2.18.0-alpha-mdx-v2.68 (alpha-mdx-v2) — 2022-06-30
- 2.15.0-alpha-wp-image-cdn-auth.45 (wp-image-cdn-auth) — 2022-05-20
- 2.9.0-alpha-image-service2.14 (image-cdn) — 2022-02-21
- … 379 more at https://npm.io/package/gatsby-page-utils/versions

## README

# gatsby-page-utils

## Usage

```shell
npm install gatsby-page-utils
```

### Example

```js
const {
  createPath,
  ignorePath,
  validatePath,
  watchDirectory,
} = require(`gatsby-page-utils`)

// ...

const pagesDirectory = "/pages"
watchDirectory(
  pagesDirectory,
  "**/*.{js, jsx}",
  addedPath => {
    // Filter out special components that shouldn't be made into
    // pages.
    if (!validatePath(addedPath)) {
      return
    }

    // Filter out anything matching the given ignore patterns and options
    if (ignorePath(addedPath, "*/connexion")) {
      return
    }

    // Create page object
    const createdPath = createPath(addedPath)
    const page = {
      path: createdPath,
      component: systemPath.join(pagesDirectory, addedPath),
    }

    // Add page
    createPage(page)
  },
  removedPath => {
    // Delete the page for the now deleted component.
    const componentPath = systemPath.join(pagesDirectory, removedPath)
    store.getState().pages.forEach(page => {
      if (page.component === componentPath) {
        deletePage({
          path: createPath(removedPath),
          component: componentPath,
        })
      }
    })
  }
)
```

#### watchDirectory

Watch activity on a directory and call functions each time a file is added or removed

| property      | description                                     | type     |
| ------------- | ----------------------------------------------- | -------- |
| path          | Directory path in which pages are stored        | String   |
| glob          | A glob that select files to watch               | String   |
| onNewFile     | A function called each time a new file is added | Function |
| onRemovedFile | A function called each time a file is removed   | Function |

#### createPath

Create a page path from a file path. It returns the page path.

| property | description | type   |
| -------- | ----------- | ------ |
| path     | File path   | String |

#### validatePath

Validate a file path. It verifies that the path doesn't contain specific characters or strings. It returns `true` if the path is valid otherwise it returns `false`.

| property | description | type   |
| -------- | ----------- | ------ |
| path     | File path   | String |

#### ignorePath

Determines if path should be ignored regarding of a ignore pattern passed as parameter. It returns `true` if the passed path should be ignored otherwise it returns `false`.

| property | description                       | type                        |
| -------- | --------------------------------- | --------------------------- |
| path     | File path                         | String                      |
| ignore   | A pattern to match with file path | (Object \| String \| Array) |

---
_Source: https://npm.io/package/gatsby-page-utils · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._