# gatsby-starter-default: the boilerplate Gatsby publishes on every update

> The default Gatsby starter is a small, deliberately boring repository: four configuration files, a src directory, an image pipeline and a Manifest plugin, and a README that is regenerated from a template on every push. It is a starting point, not a product, and it says so.

**gatsbyjs/gatsby-starter-default** — The default Gatsby starter

- Repository: https://github.com/gatsbyjs/gatsby-starter-default
- Website: https://gatsbystarterdefaultsource.gatsbyjs.io/
- Stars: 1,396 · Forks: 956
- Language: JavaScript
- License: 0BSD
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/gatsbyjs-gatsby-starter-default

## A README that regenerates itself

The first thing in the README source is a pair of marker comments, AUTO-GENERATED-CONTENT:START (STARTER) and AUTO-GENERATED-CONTENT:END, which means the prose you read is produced from a template rather than written by hand, and the whole block is replaced whenever the template changes. That tells you a great deal about the repository. It is not a curated showcase, it is a distribution point. The README says the starter ships with the main Gatsby configuration files you might need to get up and running, and points to a collection of official and community-created starters for a more specific idea. The repository is licensed under 0BSD, and the README is explicit that the licence file is a placeholder you can see and replace with your own. The top level is small by design: a.gitignore, a.prettierrc and.prettierignore, the licence, the README, the four Gatsby config files, a package-lock.json, a package.json and the src directory. The homepage field points at a Gatsby-hosted site for the starter, and there is a live site to look at.

## The four configuration files are the architecture

Gatsby's extension model is four files, and the starter includes exactly those. gatsby-config.js is the main configuration file for a site, where you specify metadata such as the site title and description and which plugins to include. gatsby-node.js is where you find usage of the Gatsby Node APIs, which let you customise or extend settings affecting pieces of the site build process, and that is the file where data sourcing and page creation are wired. gatsby-browser.js holds usage of the Gatsby browser APIs, for customization affecting the browser, and gatsby-ssr.js holds usage of the server-side rendering APIs. Each is described in the README as a file where you would put that particular usage, if any, and all four are present in the starter as empty hooks. The src directory holds the front-end code, what you see in the browser, such as the site header or a page template, and the README notes that src is a convention for source code. The first file you will edit is src/pages/index.js, and the development server updates the browser in real time as you save.

## The plugin list is the real payload

The dependency list is where the starter earns its keep, because the image pipeline is the part that is tedious to set up correctly. The runtime dependencies are gatsby at ^5.14.6, react and react-dom at ^18.2.0, and five plugins: gatsby-plugin-image, gatsby-plugin-manifest, gatsby-plugin-sharp, gatsby-source-filesystem and gatsby-transformer-sharp, all on the 5.14 line apart from the image plugin at 3.14.0. The sharp family does the work: gatsby-source-filesystem points the build at your files, gatsby-transformer-sharp processes images, gatsby-plugin-sharp is the bridge, and gatsby-plugin-image exposes the React components that render responsive, lazily loaded images. gatsby-plugin-manifest generates the web app manifest and the icons that a mobile browser uses when someone adds your site to their home screen. Prettier is the only development dependency, at ^2.8.8, and the format script runs it over js, jsx, ts, tsx, json, md and css files. So this repository is best understood as a pinned, known-good set of plugin versions that produce a working image and manifest pipeline, and the value of forking it is that you do not have to discover the right combination yourself.

## Three commands and a GraphiQL endpoint

The quick start is two steps. You create the site with the Gatsby CLI, pointing it at this repository:

```shell
gatsby new my-default-starter https://github.com/gatsbyjs/gatsby-starter-default
```

Then you move into the directory and start the development server:

```shell
cd my-default-starter/
gatsby develop
```

The site is then at http://localhost:8000, and the README points out a second URL at http://localhost:8000/___graphql, which is the tool for experimenting with querying your data, with a link into the Gatsby tutorial on using GraphiQL to explore the data layer and write GraphQL queries. That endpoint is the part of the starter with lasting value even after you delete the sample pages, because it is where you find out what the data layer actually contains before you write a query against it. The package scripts mirror the CLI, with develop and start both running gatsby develop, build running gatsby build, serve running gatsby serve and clean running gatsby clean. The test script is the one to notice: it echoes a message pointing at the unit testing documentation and then exits 1, so the starter ships with a test command that always fails.

## Deploying with one click to Netlify

The README offers a second quick start specifically for Netlify, described as deploying the starter with one click, with a button that opens a deploy form pointed at this repository. That is worth a moment's thought because it reveals how the starter is meant to be consumed. This is not a project you import as a dependency. It is a template you copy, either by pointing the CLI at the repository or by letting a hosting provider clone it for you. Netlify is named as the place to build, deploy and host Gatsby sites, and the starter's package.json contains the scripts a build service needs, build and serve among them. For a team that wants to own the deployment, the same scripts work with any CI system that runs npm run build and serves the public directory, and the repository keeps a package-lock.json, so an install in CI is deterministic. The one-click path is convenient, but it is also a hosting decision made on your behalf at the moment you click, and the starter does not configure anything about how the site should be built beyond the default scripts.

## Where the default starter is the wrong choice

The honest assessment is that this repository is deliberately minimal, and minimality is a cost when your project is not. The pages are placeholders, the site metadata is placeholder metadata, and the licence file is a placeholder. The plugin set is tuned for a site with images and a manifest, and if you are building a documentation site with no images, you have installed the Sharp toolchain and the image plugin for nothing, which is not a huge cost but is a real one. The test script fails by design, so there is no test infrastructure here at all, and a team that cares about tests starts from zero. The starter also says nothing about data sources beyond the filesystem plugin, so if your content lives in a CMS you are integrating it yourself from the start, which is exactly where a more specific starter would help. The README itself points to a collection of official and community-created starters for a more specific idea, and that is the correct first move for most projects. The failure mode to watch for is keeping the boilerplate because it is already there: a starter that arrives with a public folder, an image pipeline and a page you never wrote will quietly become the shape of your site, and the longer it stays the more of it you will keep.

## Conclusion

Adopt gatsby-starter-default when you want a Gatsby project with a working image pipeline and web app manifest from minute one, and are prepared to delete most of what is in it. Do not adopt it as a finished site template, since the pages are placeholders and the licence file is explicitly a placeholder for your own. Before you build, read the four configuration files, since the plugin list in package.json is the real content of this repository, and note that the test script deliberately fails, so the starter ships with no tests at all.

## FAQ

### How do I create a site from the default Gatsby starter?

Run `gatsby new my-default-starter https://github.com/gatsbyjs/gatsby-starter-default`, then `cd my-default-starter/` and `gatsby develop`. The site is served at http://localhost:8000 with a GraphiQL endpoint at http://localhost:8000/___graphql.

### What is in the default Gatsby starter?

A src directory, the four Gatsby configuration files gatsby-config.js, gatsby-node.js, gatsby-browser.js and gatsby-ssr.js, a .gitignore, prettier configuration, a package.json and a package-lock.json. The dependencies are Gatsby, React and React DOM plus the Sharp image pipeline, gatsby-plugin-image, gatsby-plugin-manifest, gatsby-plugin-sharp, gatsby-source-filesystem and gatsby-transformer-sharp.

### Does the starter come with tests?

No. The test script prints a message pointing at the unit testing documentation and exits with status 1, so the test command always fails and there is no test suite in the repository.

### What licence is the Gatsby default starter under?

It is licensed under the 0BSD license, and the README notes that the LICENSE file is a placeholder you can replace with your own. The repository is marked private in package.json and the version is 0.1.0.

### How do I deploy the starter?

The README gives a one-click Netlify deploy option pointed at this repository, and the package scripts are the conventional ones: build runs gatsby build, serve runs gatsby serve and clean runs gatsby clean, so the same project works with another CI provider.

## Sources

- [gatsbyjs/gatsby-starter-default on GitHub](https://github.com/gatsbyjs/gatsby-starter-default)
- [Issues](https://github.com/gatsbyjs/gatsby-starter-default/issues)
- [License: 0BSD](https://github.com/gatsbyjs/gatsby-starter-default/blob/master/LICENSE)
- [Project website](https://gatsbystarterdefaultsource.gatsbyjs.io/)
- [README](https://github.com/gatsbyjs/gatsby-starter-default/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/gatsbyjs-gatsby-starter-default