Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

ContactSign Up
Community Plugin
View plugin on GitHub

plugin image


A Gatsby plugin to source events from a user’s Google Calendars.

🚀 Getting started

To get started using the plugin follow these steps:

1. Install plugin

npm install gatsby-source-google-calendar

2. Include the plugin in gatsby-config.js

module.exports = {
  plugins: [
    // other gatsby plugins
    // ...
      resolve: `gatsby-source-google-calendar`,
      options: {
        calendarIds: [
        // options to retrieve the next 10 upcoming events
        timeMin: (new Date()).toISOString(),
        maxResults: 10,
        singleEvents: true,
        orderBy: 'startTime',

All options are optional. Specify the IDs of all the calendars you wish to query in the array calendarIds. If you omit this field, it will query all calendars of the authenticated Google user. You can further specify fields to filter the events of the calendars (e.g. minimum start/maximum end date, number of returned results, etc.). A full list of options can be found here.

3. Authorize with Google

Before you can access the Google Calendar API, you have to authorize your site with Google.

Enable Google Calendar API for your project

To enable an API for your project:

  1. Open the API Library in the Google API Console.
  2. If prompted, select a project, or create a new one.
  3. The API Library lists all available APIs, grouped by product family and popularity. If the API you want to enable isn’t visible in the list, use search to find it, or click View All in the product family it belongs to.
  4. Select the API you want to enable, then click the Enable button.
  5. If prompted, enable billing.
  6. If prompted, read and accept the API’s Terms of Service.

Create authorization credentials

  1. Go to the Credentials page.
  2. Click Create credentials > OAuth client ID.
  3. Select the Web application application type.
  4. Fill in the form and click Create.

When prompted for a redirect URI, type in http://localhost:8000/oAuthCallback. The redirect URI is the endpoint to which the OAuth 2.0 server can send responses. It is setup by the plugin automatically. 5. Store the resulting client configuration (Client ID and Client Secret) in your .env files in the root directory of your project:


Retrieve API tokens

Once you’ve stored the client credentials, execute gatsby develop. When first executed, the plugin throws the following error:

"gatsby-source-google-calendar" threw an error while running the sourceNodes lifecycle:

    Authorize this app by visiting this url:


Visit the displayed URL and follow the steps to complete the authorization. On successful authorization, the plugin prints out the access and refresh tokens to the console:

Successfully authorized app for Google Calendar API.
Store the following values in your .env files then restart gatsby develop:


Store these lines (e.g. the complete FIELD=VALUE lines without newlines) in your .env files, then restart gatsby develop. The plugin should now query the events from Google Calendar.

Important: You should never expose API keys to your source control so you should not commit .env files to your source control (make sure they are listed in .gitignore). Services like Netlify provide a secure way to include environment variables for your builds).

4. Accessing calendars and events in your site

To access the sourced calendars and events in your site write a GraphQL query like this:

query MyCalendarQuery {
  allCalendar {
    edges {
      node {
        childrenCalendarEvent {
          start {
          end {

This will return all calendars (with summary and description) with their respective events (childrenCalendarEvent).

The event schema generally follows the event schema of the Google Calendar API. However, the plugin adds an additional allDay flag indicating whether or not an event is marked as all-day.

Further, if an event is marked all-day, the plugin populates the event’s dateTime field with the event’s date field taking into account the calendar’s timezone. This allows unified filtering of all kinds of events (all-day or not) in GraphQL queries.

Visit http://localhost:8000/___graphql to check out the created data and schema.


Plugin throws Error: invalid_grant

If the plugin throw an invalid_grant error it means that the provided Google refresh token is invalid. While there may be a number of causes for this, here are some things you can try to resolve this issue:

  1. Ensure that the token is correct, i.e. your .env.* files don’t include any accidental line breaks.
  2. Remove values for GOOGLE_ACCESS_TOKEN and GOOGLE_REFRESH_TOKEN and restart the authentication process.
  3. Revoke access to your Google Account for your app and restart the authentication process.
  4. If above doesn’t help, set up a new OAuth2 client in the Google Console.

How to contribute

Contributions are very welcome! File a bug report or submit feature requests through the issue tracker. Of course, you can also just submit a pull request 😉


This project is licensed under the MIT License.

© 2023 Gatsby, Inc.