Registry / storage / gatsby-source-youtube-v3

gatsby-source-youtube-v3

library3.0.2jsnpmunverified

A Gatsby source plugin for fetching videos from YouTube channels via the YouTube Data API v3. It consumes channel IDs and an API key to retrieve video metadata including title, description, thumbnails, and privacy status. The plugin supports Gatsby v3 (and v2 with older versions) and provides GraphQL nodes for use in Gatsby sites. Version 3.0.2 is the latest stable release as of early 2023, with irregular updates. It differentiates from similar plugins by supporting local thumbnail caching for use with gatsby-image, filtering by channel, and limiting max videos. The plugin requires a YouTube API key and handles pagination automatically.

storage

npm install gatsby-source-youtube-v3

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GATSBY-SOURCE-YOUT

gatsby-source-youtube-v3

storagejavascriptv3.0.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Plugin configuration

✓ plugins: [{ resolve: `gatsby-source-youtube-v3`, options: { channelId: ['UC...'], apiKey: 'YOUR_KEY' } }]

✗ plugins: ['gatsby-source-youtube-v3']

Must provide options object with channelId array and apiKey string

GraphQL query allYoutubeVideo

✓ query { allYoutubeVideo { edges { node { id title } } } }

✗ query { allYoutubeVideo { id title } }

GraphQL nodes are returned in edges/node pattern

GraphQL filter by channelId

✓ filter: { channelId: { eq: "UC..." } }

✗ filter: { channelId: "UC..." }

Must use eq operator for exact match

Shows plugin configuration in gatsby-config.js and a GraphQL query to retrieve videos with thumbnails.

// gatsby-config.js module.exports = { plugins: [ { resolve: `gatsby-source-youtube-v3`, options: { channelId: ['UCK8sQmJBp8GCxrOtXWBpyEA'], apiKey: process.env.YOUTUBE_API_KEY ?? '', maxVideos: 10, }, }, ], }; // Example page query import { graphql } from 'gatsby'; export const query = graphql` query { allYoutubeVideo(limit: 5) { edges { node { id title description videoId publishedAt privacyStatus channelTitle thumbnail { url width height } localThumbnail { childImageSharp { fluid { src } } } } } } } `;

Debug

Known issues

breakingGatsby v3 changed the way plugins handle images; localThumbnail may require additional configuration with gatsby-plugin-sharp.

fix

Ensure gatsby-plugin-sharp and gatsby-transformer-sharp are installed and configured when using localThumbnail.

affects: >=1.0.0

deprecatedThe use of graphql template literals outside of page components is deprecated in Gatsby v3 but still works.

fix

Only use graphql in page components or static queries.

affects: >=2.0.0

gotchaAPI key is sent as query parameter; ensure key is kept secret and use environment variables.

fix

Set API key via environment variable, e.g., process.env.YOUTUBE_API_KEY, and never commit it.

affects: *

gotchaChannel IDs must be the actual channel ID (starting with UC), not the channel name.

fix

Use the channel ID from the YouTube channel's advanced settings, e.g., 'UCK8sQmJBp8GCxrOtXWBpyEA'.

affects: *

gotchamaxVideos defaults to 50; total videos fetched may be less if there are fewer videos on the channel.

fix

Set maxVideos to a number up to 50 (the free API limit per page).

affects: *

Errors

Common errors & fixes

Error: Can't resolve 'gatsby-source-youtube-v3'

Package not installed or not in node_modules.

fix

Run 'npm install gatsby-source-youtube-v3' or add to package.json.

GraphQL Error: Unknown field 'allYoutubeVideo'

Plugin not configured in gatsby-config.js or Gatsby not restarted.

fix

Ensure plugin is added to gatsby-config.js plugins array and restart the Gatsby development server.

Error: Request failed with status code 403

Invalid or missing YouTube API key, or API key quota exceeded.

fix

Verify the API key is correct, has YouTube Data API v3 enabled, and quota not exhausted.

Error: Cannot query field 'thumbnail' on type 'YoutubeVideo'

Plugin version doesn't include thumbnail field or schema not updated.

fix

Update to latest version of gatsby-source-youtube-v3 and clear Gatsby cache (gatsby clean).

Upgrade

Version history

3.0.2latest on npm

Audit

Dependencies

gatsbyrequiredPeer dependency required for Gatsby plugins

Agent activity

24 hits · last 30 days

node

Resources

githubhttps://github.com/bene/gatsby-source-youtube-v3 ↗

packagegatsby-source-youtube-v3 ↗

homepagehttps://github.com/bene/gatsby-source-youtube-v3#readme ↗