Gatsby

---
name: gatsby
description: "Maintenance and migration guidance for Gatsby 5. Gatsby is in maintenance mode (Netlify-owned, security fixes only, no roadmap) -- use this skill for maintaining existing Gatsby sites and migrating them to modern alternatives (Astro for content sites, Next.js for applications). Covers the GraphQL data layer, source plugins, useStaticQuery, createPages API, Slice API, Head API, build process, and step-by-step migration paths. Do not recommend Gatsby for new projects. Use for \"Gatsby\", \"gatsby\", \"GraphQL Gatsby\", \"gatsby-source\", \"useStaticQuery\", \"Gatsby plugin\" questions."
license: MIT
---

# Gatsby Maintenance & Migration

This skill covers Gatsby 5 maintenance and migration. Gatsby is in maintenance mode: Netlify-owned, security fixes only, no active development, no roadmap. The plugin ecosystem is degrading. Do not recommend Gatsby for new projects.

Use this skill to:

1. **Maintain** existing Gatsby sites -- fix build issues, work around plugin failures, optimize build times.
2. **Migrate** Gatsby sites to modern alternatives -- Astro (content sites) or Next.js (applications).

## Status

- Feb 2023: Netlify acquired Gatsby Inc.
- Aug 2023: Engineering team laid off. Active development ended.
- 2024-present: Security patches only.
- Gatsby Cloud shut down. Plugin ecosystem degrading.
- Node.js 18 (required by Gatsby 5) reached EOL April 2025.

## How to Approach Tasks

When you receive a request:

1. **Classify** the request:
   - **Maintaining existing site** -- Load `references/architecture.md` and `references/patterns/graphql.md`
   - **Migration planning** -- Load `references/migration.md`
   - **Migrating to Astro** -- Load `references/patterns/migration-astro.md`
   - **Migrating to Next.js** -- Load `references/migration.md` (Next.js section)
   - **Plugin issues** -- Check if plugin is abandoned, suggest replacement or custom sourceNodes

2. **Assess migration urgency** -- Check for: broken plugins, Node.js compatibility issues, security CVEs, need for SSR/ISR/API routes.

3. **Recommend** -- For maintenance: provide working solutions. For migration: provide step-by-step guidance with conceptual mappings.

## Core Knowledge

### GraphQL Data Layer

Gatsby sources all data into a local GraphQL store at build time. Query with page queries and `useStaticQuery`.

```jsx
// Page query (build-time, supports variables)
export const query = graphql`
  query BlogQuery {
    allMarkdownRemark(sort: { frontmatter: { date: DESC } }) {
      nodes { id frontmatter { title date slug } excerpt }
    }
  }
`;
export default function BlogPage({ data }) {
  return data.allMarkdownRemark.nodes.map(post => (
    <article key={post.id}>{post.frontmatter.title}</article>
  ));
}
```

```jsx
// useStaticQuery (no variables, any component)
const data = useStaticQuery(graphql`
  query { site { siteMetadata { title } } }
`);
```

### Key Config Files

- `gatsby-config.js` -- plugins, site metadata, feature flags
- `gatsby-node.js` -- createPages, createSchemaCustomization, onCreateNode
- `gatsby-browser.js` / `gatsby-ssr.js` -- client/SSR lifecycle hooks

### Gatsby 5 Features

- **Slice API**: isolates shared components into separate build units
- **Head API**: replaces react-helmet for `<head>` management
- **Script component**: controls third-party script loading strategy

### Migration Targets

- **Astro**: content/docs sites, minimal interactivity, reducing JS bundle size
- **Next.js**: SSR/ISR/API routes, authentication, complex React interactivity

## Common Maintenance Issues

**1. Plugin incompatible with Node.js 20+**
Many plugins use deprecated Node.js APIs. Pin Node.js 18 or fork the plugin.

**2. CMS source plugin broken**
CMS vendors update APIs; abandoned plugins lag behind. Replace with custom `sourceNodes` in `gatsby-node.js`.

**3. Build time exceeding 30 minutes**
Use Slice API for shared components. Reduce page count. Consider migration.

**4. Security CVE in plugin**
If unpatched upstream, fork the plugin and apply fix. Or migrate.

## Reference Files

- `references/architecture.md` -- GraphQL data layer, build process, Slice API
- `references/migration.md` -- Migration paths to Astro and Next.js

## Pattern Guides

- `references/patterns/graphql.md` -- Source plugins, queries for maintaining existing projects
- `references/patterns/migration-astro.md` -- Step-by-step Gatsby to Astro migration