@rmdes/indiekit-endpoint-youtube

YouTube channel endpoint for Indiekit.

Display latest videos and live streaming status from any YouTube channel on your IndieWeb site.

Installation

Install from npm:

npm install @rmdes/indiekit-endpoint-youtube

Features

• Admin Dashboard - Overview of channel with latest videos in Indiekit's admin UI
• Live Status - Shows when channel is live streaming (with animated badge)
• Upcoming Streams - Display scheduled upcoming live streams
• Latest Videos - Grid of recent uploads with thumbnails, duration, view counts
• Public JSON API - For integration with static site generators like Eleventy
• Quota Efficient - Uses YouTube API efficiently (playlist method vs search)
• Smart Caching - Respects API rate limits while staying current

Configuration

Add to your indiekit.config.js:

import YouTubeEndpoint from "@rmdes/indiekit-endpoint-youtube";

export default {
  plugins: [
    new YouTubeEndpoint({
      mountPath: "/youtube",
      apiKey: process.env.YOUTUBE_API_KEY,
      channelId: process.env.YOUTUBE_CHANNEL_ID,
      // OR use channel handle instead:
      // channelHandle: "@YourChannel",
      cacheTtl: 300_000,      // 5 minutes
      liveCacheTtl: 60_000,   // 1 minute for live status
      limits: {
        videos: 10,
      },
    }),
  ],
};

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | YOUTUBE_API_KEY | Yes | YouTube Data API v3 key | | YOUTUBE_CHANNEL_ID | Yes* | Channel ID (starts with UC...) | | YOUTUBE_CHANNEL_HANDLE | Yes* | Channel handle (e.g., @YourChannel) |

*Either channelId or channelHandle is required.

Getting a YouTube API Key

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the "YouTube Data API v3"
4. Go to Credentials > Create Credentials > API Key
5. (Optional) Restrict the key to YouTube Data API only

Finding Your Channel ID

• Go to your YouTube channel
• The URL will be youtube.com/channel/UC... - the UC... part is your channel ID
• Or use a tool like Comment Picker

Routes

Admin Routes (require authentication)

| Route | Description | |-------|-------------| | GET /youtube/ | Dashboard with channel info, live status, latest videos | | POST /youtube/refresh | Clear cache and refresh data |

Public API Routes (JSON)

| Route | Description | |-------|-------------| | GET /youtube/api/videos | Latest videos (supports ?limit=N) | | GET /youtube/api/channel | Channel information | | GET /youtube/api/live | Live streaming status |

Example: Eleventy Integration

// _data/youtube.js
import EleventyFetch from "@11ty/eleventy-fetch";

export default async function() {
  const baseUrl = process.env.SITE_URL || "https://example.com";

  const [channel, videos, live] = await Promise.all([
    EleventyFetch(`${baseUrl}/youtube/api/channel`, { duration: "15m", type: "json" }),
    EleventyFetch(`${baseUrl}/youtube/api/videos?limit=6`, { duration: "5m", type: "json" }),
    EleventyFetch(`${baseUrl}/youtube/api/live`, { duration: "1m", type: "json" }),
  ]);

  return {
    channel: channel.channel,
    videos: videos.videos,
    isLive: live.isLive,
    liveStream: live.stream,
  };
}

API Response Examples

GET /youtube/api/live

{
  "isLive": true,
  "isUpcoming": false,
  "stream": {
    "videoId": "abc123",
    "title": "Live Stream Title",
    "thumbnail": "https://i.ytimg.com/vi/abc123/mqdefault.jpg",
    "url": "https://www.youtube.com/watch?v=abc123"
  },
  "cached": true
}

GET /youtube/api/videos

{
  "videos": [
    {
      "id": "abc123",
      "title": "Video Title",
      "thumbnail": "https://i.ytimg.com/vi/abc123/mqdefault.jpg",
      "duration": 3661,
      "durationFormatted": "1:01:01",
      "viewCount": 12345,
      "publishedAt": "2024-01-15T10:00:00Z",
      "url": "https://www.youtube.com/watch?v=abc123",
      "isLive": false
    }
  ],
  "count": 10,
  "cached": true
}

Options

| Option | Default | Description | |--------|---------|-------------| | mountPath | /youtube | URL path for the endpoint | | apiKey | - | YouTube Data API key | | channelId | - | Channel ID (UC...) | | channelHandle | - | Channel handle (@...) | | cacheTtl | 300000 | Cache TTL in ms (5 min) | | liveCacheTtl | 60000 | Live status cache TTL in ms (1 min) | | limits.videos | 10 | Number of videos to fetch |

Quota Efficiency

YouTube Data API has a daily quota (10,000 units by default). This plugin is optimized:

| Operation | Quota Cost | Method | |-----------|------------|--------| | Get videos | 2 units | Uses uploads playlist (not search) | | Get channel | 1 unit | Cached for 24 hours | | Check live status | 2 units | Checks recent videos (efficient) | | Full live search | 100 units | Only when explicitly requested |

With default settings (5-min cache), you'll use ~600 units/day for video checks.

Requirements

• Indiekit >= 1.0.0-beta.25
• YouTube Data API v3 enabled
• Valid API key with YouTube Data API access

License

MIT