Gatsby: Document typical directory structure of a Gatsby project

[m-allanson]

Summary

Gatsby expects a certain directory structure for some files. The structure is described Gatsby's docs, but there isn't a single reference anywhere.

Basic example

Structure of a Gatsby project:

/                   // The root of your project
  .cache            // Gatsby's cache directory (created automatically)
  plugins           // (optional) Local plugins - link to writing plugin docs
  public            // Gatsby's output directory (created automatically)
  src               // Your project source
    components      // describe components dir
    pages           // describe pages dir
    templates       // describe templates dir
    ...         // more docs + directories here?
  static            // (optional) Your static files - link to https://www.gatsbyjs.org/docs/adding-images-fonts-files/
  gatsby-config.js  // describe & link to docs
  gatsby-node.js    // describe & link to docs
  gatsby-ssr.js     // describe & link to docs
  gatsby-browser.js // describe & link to docs

While writing this I found a doc that includes some of this information. The key difference is that this new doc would describe all optional files and directories, along with directories generated by Gatsby.

Motivation

This would be a useful reference for people that have started using Gatsby, but are still becoming familiar with where everything goes. It could be particularly useful for looking up optional directories like plugins and static.

[kripod]

I often encounter the situation of having a page with multiple distinct sections (e.g. a single-page website).

It would be great if we could associate the components of those sections with the pages they are used on, so we wouldn’t have to put AboutSection, ContactSection, etc. inside the same directory as regular reusable components (src/components), but use a distinct path for them (e.g. src/sections or src/pages/[pageName]/_components).

[ryanditjia]

@kripod I’ve always thought about doing this. I take it naming a folder _components prevents the component in its directory from being generated as page?

Perhaps this could go under “advanced” section in the doc.

[kripod]

@ryanditjia Well, that naming convention came out of nothing and should definitely be improved.

My goal was to demonstrate the need for keeping components which are strictly related to a single page as close to the page itself as possible _(which is not possible with the approach involving a separate src/sections directory)_.

[heyjordn]

I'd be willing to take this, where would the new addition doc go, ? Or would it be it's own section? @m-allanson

[ryanditjia]

I think this could go under Conceptual Guide in https://next.gatsbyjs.org/docs/.

[mikelax]

One additional file to include in the list is the default html.js
The file isn't created in the src filesystem, only in the cache unless the user manually copies the files from the cache to src folder. There is a reference to that in the docs, but it would be nice to be included here as well.

[shannonbux]

Hi @m-allanson! How close is this to the default starter READme (new one @amberleyromo wrote recently): https://github.com/gatsbyjs/gatsby-starter-default

Just wondering if some of that content is reusable. Either way, I'll add this to the content pipeline!

[amberleyromo]

Direct link to that section: https://github.com/gatsbyjs/gatsby-starter-default#-whats-inside

We had talked about repurposing this elsewhere, so this is perfect. Whats in the starter is reusable, but it's a jumping off point to what would be more in-depth/fuller, i'd imagine.

[Tomekmularczyk]

What about keeping a separate directory like:

views/
  HomePage/
    index.js
    HomePageComponent1.js
    HomePageComponent2.js
  OthePage/
    index.js
    OtherPageComponent1.js
    OtherPageComponent2.js

and then in pages you only import a view:
pages/other.js:

import HomePage from '../views/HomePage'

export default HomePage;

This gives you the flexibility of keeping related components together rather than having just one big components/ directory.

[mikelax]

@Tomekmularczyk I think we should stop just short of recommending components folder layouts, as that is a decision with numerous options and opinions. I think as long as we document the gatsby specific recommended/required folder structures, we can provide a link to the react docs that discusses folder layouts for components.

[shannonbux]

@Pr0x1m4 I know this is super late! Any chance you'd still be interested in taking this on now that there's been additional discussion?

[palerdot]

@shannonbux I came across this issue and I too feel this should be documented. I can take up if there are no takers. I can give a PR. But I do not want to duplicate the efforts if someone else is already working on it. Let me know!

[shannonbux]

@arun1595 feel free to take this! I assume no one has started it because this issue isn't linked to a PR yet. Thank you! 👍

[palerdot]

@shannonbux Sure. Will look into this and will give a PR. I hope you mean me. I guess you might have tagged a wrong person.

[palerdot]

@shannonbux @m-allanson @mikelax I have created a PR documenting typical Gatsby project folder structure. The file is committed as gatsby-folder-structure inside docs. The file can be seen here - https://github.com/gatsbyjs/gatsby/blob/34a4c8157ebea3e223687114f870c3e61e1c0190/docs/docs/gatsby-folder-structure.md

Does this capture all the relevant info of this thread?

[calcsam]

Thanks @palerdot, this is great! As soon as we get this issue in a place in the hierarchy, let's go ahead and close this issue.

[shannonbux]

Closing because #8405 finished it