Configure a Gatsby Theme to Take Options

Jason Lengstorf
InstructorJason Lengstorf

Share this video with your friends

Send Tweet
Published 2 years ago
Updated 10 months ago

Gatsby themes accept options. Learn how to read these options and generate pages from the correct data at the appropriate locations.

In this lesson, we'll:

  • turn the gatsby-config into a function
  • pass in options as arguments to that function
  • update gatsby-node to reference the options passed in

For a written version of this course, check out the Gatsby docs.

In a consuming package, you can configure the options object however you need to within the plugins array.

Instructor: [00:00] In a Gatsby theme, you can pass options to both the Gatsby config and to the Gatsby node. In Gatsby config, let's make our config object into a function. Any options passed to the theme will be provided as arguments to this function.

[00:21] We're going to update to use both the content path, which will default to data, and the base path, which will default to the root URL. We're going to pass those in here. Where the path is, we're going to use content path. We'll come back to base path here in just a minute.

[00:43] In Gatsby node, options are passed as a second argument to the API hooks, so we can grab it out of options. Content path will now be options.contentPath or data. We'll do the same thing on our createResolvers. Get an options object.

[01:05] We'll say options.basePath or root. We can copy that and come down here. Do the same thing one last time. Base path will be options.basePath or a forward slash.

[01:24] To test this, we need to actually set up our site, which we've thus far ignored, to use our theme so we can set some options. We've already installed the theme as a dependency, which means that we can set up our gatsby-config.js. Inside Gatsby config, we're going to export a config object. In the plugins array, we're going to include our theme.

[01:50] Let's resolve to Gatsby theme events. We'll set the options to our two options. We've got the content path, which needs to be set, and the base path, which also needs to be set. To test that these options are working, we're going to pick something deliberately different.

[02:12] We'll set this to events. Let's set the base path to events as well. What we should see is that when we run this theme, an events directory will get created here. We'll see a page called events that has our event listing on it.

[02:29] To test this, run yarn workspace site develop in the terminal. Once this is running, we can see that the events folder was created. If we go back out to our page, we can see that the events page was created with the events. However, we don't have any events yet. Let's copy our events over from the data directory into our new events directory.

[02:55] Once we stop and restart with yarn workspace site develop, we should see our events directory here. We can see six pages have been generated. If we jump back out, we can see here's our event. We've got events-dinosaur.js. This shows that our config options are being taken into account.

Alex Mejias
Alex Mejias
~ 2 years ago

This video does not quite stress the point that your theme's local data import will no longer work after changing your gatsby-config to export a function rather than an object.

Jason Lengstorf
Jason Lengstorfinstructor
~ 2 years ago

@Alex that's a good point. I’m planning to record some updates, and I'll add this to the list. Thanks!

HaveF
HaveF
~ 2 years ago

I did the same thing, and I can see the events page in site project, but when I click one of the event to jump to the template/event.js page, it fails(404). On the build process, it says warning below. Did I missing something?

warn The GraphQL query in the non-page component "/Users/User/egghead_gatsby-theme-authoring/gatsby-theme-events/src/template/event.js" will
not be run.
Exported queries are only executed for Page components. It's possible you're
trying to create pages in your gatsby-node.js and that's failing for some
reason.

If the failing component(s) is a regular component and not intended to be a page
component, you generally want to use a <StaticQuery> (https://gatsbyjs.org/docs/static-query)
instead of exporting a page query.

If you're more experienced with GraphQL, you can also export GraphQL
fragments from components and compose the fragments in the Page component
query and pass data down into the child component — http://graphql.org/learn/queries/#fragments
Jason Lengstorf
Jason Lengstorfinstructor
~ 2 years ago

@HaveF this looks like the createPage call isn't being fired, which would mean that the event template isn't being used. Gatsby will warn for page queries in any files that aren't actively being used as pages or page templates.

Hope that helps!

Md. Anam Hossain
Md. Anam Hossain
~ 2 years ago
UNHANDLED REJECTION Unable to find plugin "gatsby-theme-events". Perhaps you need to install its package?
  Error: Unable to find plugin "gatsby-theme-events". Perhaps you need to install its package?

I got this when I run yarn workspace site develop Let me know how to solve this. Thanks.

Ryan Murray
Ryan Murray
~ 2 years ago

Hi Jason,

I got the same error as MD. Anam. Did this get resolved?

Ryan Murray
Ryan Murray
~ 2 years ago

Here's a little more information:

These are my dependencies in /site

"dependencies": {
        "gatsby": "^2.16.5",
        "react": "^16.10.2",
        "react-dom": "^16.10.2",
        "gatsby-theme-events": "*"
    }
Ryan Murray
Ryan Murray
~ 2 years ago

Figured it out my error.

In my case the blank index.js was not in /gatsby-theme-events

André
André
~ a year ago

Hi Jason, I'm having the same problem as @HaveF.

I looked into what you suggested and to me it seems like the createPage call is being called but there are no generated nodes, so the createPage query returns no data to generate the pages.

Any ideas on what might be wrong? I started the entire process from scratch twice just to make sure it wasn't a typo but no luck.

yarn run v1.21.1
$ gatsby develop
success open and validate gatsby-configs - 0.014s
success load plugins - 0.033s
success onPreInit - 0.022s
success initialize cache - 0.006s
success copy gatsby files - 0.042s
success onPreBootstrap - 0.011s
success createSchemaCustomization - 0.005s
warn The events plugin has generated no Gatsby nodes. Do you need it?
success Checking for changed pages - 0.002s
success source and transform nodes - 0.033s
success building schema - 0.139s
info Total nodes: 21, SitePage nodes: 2 (use --verbose for breakdown)
success createPages - 0.022s
success Checking for changed pages - 0.001s
success createPagesStatefully - 0.023s
success update schema - 0.022s
success write out redirect data - 0.002s
success onPostBootstrap - 0.003s
info bootstrap finished - 2.150s
success onPreExtractQueries - 0.002s
success extract queries from components - 0.077s
warn The GraphQL query in the non-page component "/Users/User/gatsby-themes/events/src/templates/event.js" will not be run.
Exported queries are only executed for Page components. It's possible you're
trying to create pages in your gatsby-node.js and that's failing for some
reason.

If the failing component(s) is a regular component and not intended to be a page
component, you generally want to use a <StaticQuery> (https://gatsbyjs.org/docs/static-query)
instead of exporting a page query.

If you're more experienced with GraphQL, you can also export GraphQL
fragments from components and compose the fragments in the Page component
query and pass data down into the child component — https://graphql.org/learn/queries/#fragments
success write out requires - 0.005s
success run page queries - 0.022s - 2/2 89.82/s
⠀
You can now view site in the browser.
⠀
  http://localhost:8000/
⠀
View GraphiQL, an in-browser IDE, to explore your site's data and schema
⠀
  http://localhost:8000/___graphql
⠀
Note that the development build is not optimized.
To create a production build, use gatsby build
⠀
success Building development bundle - 2.141s
success onPreExtractQueries - 0.008s
success extract queries from components - 0.014s