The Gatsby hello-world starter is a handful of files and one page

The repository holds less than the README's file tree suggests

A starter template is judged on two things, the scaffold it gives you and how little it hides from you. On the second count this one is about as bare as it gets. The top level of the repository contains .gitignore, LICENSE, README.md, gatsby-config.js, package-lock.json, package.json, src/ and static/. There is no theme, no TypeScript configuration, no styling framework, no linting setup and no CI definition in that list.

That list is worth comparing with the file tree the README prints, because the two do not match. The tree in the README shows node_modules, src, .gitignore, gatsby-browser.js, gatsby-config.js, gatsby-node.js, gatsby-ssr.js, LICENSE, package.json and README.md, and it is introduced as a quick look at what you will see in a typical Gatsby project rather than as a listing of this repository. The README also carries AUTO-GENERATED-CONTENT markers around the section, which indicates the text is produced from a shared template across starters rather than hand written for this one.

The practical consequence is that the README is a general introduction to the Gatsby file conventions, useful as orientation, while the repository itself is the actual starting point. The static/ directory appears in the repository but not in the printed tree, which is a useful reminder to check the tree of the files you actually clone rather than the one described in prose.

gatsby new and gatsby develop are the entire quick start

The workflow is short enough to hold in your head. You create the site with the Gatsby CLI, naming the starter explicitly, then you move into the generated directory and start the development server:

    gatsby new my-hello-world-starter https://github.com/gatsbyjs/gatsby-starter-hello-world

    cd my-hello-world-starter/
    gatsby develop

The first command clones the starter into a directory named after the argument you pass, and the second starts the development server. The site is then served at http://localhost:8000, and the README tells you to edit src/pages/index.js and save, at which point the browser updates in real time.

A second URL is worth knowing about before you start poking around. Alongside the site, the development server exposes http://localhost:8000/___graphql, which the README describes as a tool for experimenting with queries, pointing at the Gatsby tutorial section about using GraphiQL to explore the data layer and write GraphQL queries. Even in a starter with no data sources, that endpoint is where you will build the query habits that a real content model depends on, and it is the part of the local setup that most beginners skip.

package.json pins Gatsby 5 and React 18 with caret ranges

The manifest is the only place in the repository where concrete versions appear, and it is worth reading before you build anything on top of it. The dependency block is short:

  "dependencies": {
    "gatsby": "^5.14.6",
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  },

Gatsby is on the 5 line with React 18 as its renderer. The caret ranges mean a fresh install resolves to the latest compatible 5.x and 18.x releases rather than to those exact numbers, and the repository also ships package-lock.json, which pins the resolved tree for anyone who runs an install with a lockfile-aware workflow. That combination is sensible: the manifest declares the supported line, and the lockfile records one known-good resolution of it.

The npm scripts cover the commands a Gatsby project needs. gatsby build produces the production output, gatsby develop starts the development server, gatsby serve serves the built site, and gatsby clean clears the caches. One script deserves a note. The test script does not run tests; it prints a message pointing at the Gatsby unit testing documentation and then exits with status 1, so npm test fails by design in a fresh clone. Treat a red test command as expected here rather than as a broken checkout.

gatsby-config.js is the one configuration file the repository ships

Gatsby's configuration is split across several files, each of which the README walks through, and the repository ships only gatsby-config.js. That file is where site metadata such as the title and description live, and where plugins are declared. The other three are optional hooks: gatsby-browser.js holds code that runs in the browser and extends the browser APIs, gatsby-node.js holds Node API usage that affects the build process, and gatsby-ssr.js holds server-side rendering API usage. None of them exists in this repository, which is the honest signal that a Gatsby site starts with none of them and adds them when a specific need appears.

The same convention applies to the content side. The src directory holds the front-end code, page templates and headers, following the usual convention that src means source code, and the file the README points you at for editing is src/pages/index.js. The static directory is the sibling that holds files served as they are rather than processed, which is where you would put assets that should reach the output unchanged.

For a team evaluating the framework, the starter's value is that it shows the minimum. One configuration file, one page, one static folder, and every other file is something you add on purpose.

Netlify's one-click deploy assumes a repository you do not have

The README offers a Netlify deploy button for the starter and a short section pointing at Netlify for building, deploying and hosting Gatsby sites. It is a convenient path when you already have a Netlify account, since the button points at a deploy endpoint seeded with the repository URL.

Two details make it worth reading carefully rather than clicking straight away. The button deploys the upstream repository, so the site you get is the starter itself rather than your own project, and Netlify's build will read the package.json in that repository, which is the manifest described earlier. The alternative path is the local one: gatsby build followed by gatsby serve produces the same output on your machine, and any static host can serve the generated directory. The difference in approach is who runs the build. Netlify runs it on every push and gives you a preview URL per branch, while the local path gives you the artefact and leaves hosting to you, which is the option to pick if your sites live on a host you already control or if a build has to run inside your own network.

The 0BSD licence makes the scaffold yours to relicense

The licence is the least common feature of a starter and here it is unusually permissive. The repository is under the 0BSD license, which the README explains with a sentence that matters more than the usual legal boilerplate: the LICENSE file is a placeholder and you can replace it with your own.

In practice that means you can take this repository, copy the structure, and put whatever licence terms you want on the result without carrying attribution obligations forward. It also means the starter imposes nothing on the projects built from it, which is different from most open source scaffolding, where a copyleft or attribution-carrying licence would follow the template into your site.

This is a description of what the licence permits, not legal advice, and it does not cover code you add later or plugins you install. The dependencies named in the manifest, Gatsby itself and React, carry their own terms separately, so the 0BSD covering the template does not extend to the framework it pulls in.

Where this starter stops being the right choice

The hello-world starter is deliberately narrow, and that narrowness has a cost. There is no TypeScript, no CSS approach, no component library, no routing convention and no content sourcing configuration. A team that wants a blog, a documentation site or a storefront ends up making the same architectural decisions the framework should have suggested, and every one of those decisions is a decision you now own.

The failure mode to watch for is subtler. Because the README is auto-generated and describes typical Gatsby projects rather than this repository, a reader can come away believing that gatsby-browser.js, gatsby-node.js and gatsby-ssr.js are present and configured, and that node_modules is checked in as a directory entry. Neither is true of the repository you clone. Checking the actual file list before building assumptions on top of it costs one command.

The other limit is that a starter with no content layer gives you the development server and a GraphiQL endpoint, but nothing to query yet. Until you add a data source, the GraphQL layer returns what the single page exposes. If your plan depends on a working query pipeline on day one, you will be writing the sourcing configuration yourself, and at that point the starter has given you the project shape and little else.

Editorial conclusion

Adopt gatsby-starter-hello-world when you want the canonical Gatsby 5 project layout with the tooling already wired and are prepared to add the content layer, styling and deployment configuration yourself. Do not adopt it if you need TypeScript, a theme, routing conventions or a working test suite, since the repository ships none of those and its npm test script exits with a failure by design. Verify first that the src and static directories in this repository match the structure your own site needs, because the file tree printed in the README is shared boilerplate and lists configuration files that the repository itself does not contain.

Frequently asked questions

Official sources

1. gatsbyjs/gatsby-starter-hello-world on GitHub
2. Issues
3. License: 0BSD
4. Project website
5. README