$3

By: {video.data.channelTitle}

Published: {video.data.publishedAt.toLocaleDateString()}

Duration: {video.data.duration}

Views: {video.data.viewCount}

{videos?.map((video) => (

/videos/${video.id}}>

{video.data.title}

{video.data.channelTitle}

{new Date(video.data.publishedAt).toLocaleDateString()}





))}


`astro
---
// src/pages/videos/[id].astro
import { getLiveEntry } from 'astro:content';
import Layout from '../../layouts/Layout.astro';

export const prerender = false; // Required for live content

const { id } = Astro.params;
const { entry: video, error } = await getLiveEntry('latestVideos', id!);

if (error || !video) {
return Astro.redirect('/videos');
}
---

{video.data.title}

Watch on YouTube →

`

#### Live Loader Options

The liveYouTubeLoader supports various filtering options:

`typescript
liveYouTubeLoader({
type: "search",
apiKey: process.env.YOUTUBE_API_KEY,
query: "javascript tutorials",
defaultMaxResults: 20,
defaultOrder: "relevance",
requestOptions: {
headers: {
"User-Agent": "My Astro Site",
},
},
});
`

#### Filtering Live Collections

You can filter live collections when fetching them:

`typescript
// Get latest 5 videos
const { entries } = await getLiveCollection("latestVideos", { limit: 5 });

// Filter by date range
const { entries } = await getLiveCollection("searchVideos", {
publishedAfter: new Date("2024-01-01"),
publishedBefore: new Date("2024-12-31"),
});

// Filter by duration
const { entries } = await getLiveCollection("searchVideos", {
duration: "medium", // short, medium, or long
limit: 10,
});

// Custom search query (for search-type loaders)
const { entries } = await getLiveCollection("searchVideos", {
query: "react hooks tutorial",
order: "date",
});
`

#### Error Handling

Live YouTube loaders return structured errors that you can handle appropriately:

`typescript
import {
YouTubeAPIError,
YouTubeValidationError,
YouTubeConfigurationError,
} from "@ascorbic/youtube-loader";

const { entries, error } = await getLiveCollection("latestVideos");

if (error) {
if (error instanceof YouTubeAPIError) {
if (error.isQuotaExceeded) {
console.error("YouTube API quota exceeded");
} else if (error.isInvalidAPIKey) {
console.error("Invalid YouTube API key");
} else {
console.error(YouTube API error: ${error.message});
}
} else if (error instanceof YouTubeValidationError) {
console.error(Validation error: ${error.message});
} else if (error instanceof YouTubeConfigurationError) {
console.error(Configuration error: ${error.message});
}
}
`

#### When to Use Live vs Static Loading

Use live loading when:

- You want real-time YouTube data
- Content updates frequently
- You need dynamic search functionality
- You want to avoid rebuilds for new videos
- Building a video discovery interface

Use static loading when:

- You have a fixed set of videos
- Performance is critical (pre-rendered)
- You want build-time optimization
- You need to process video data extensively

API Reference

$3

Static content collections loader for build-time YouTube video processing.

#### Options

- type (required): 'videos' | 'channel' | 'search' | 'playlist'
- apiKey (required): Your YouTube Data API v3 key
- videoIds: Array of video IDs (required when type is 'videos')
- channelId: YouTube channel ID (required when type is 'channel', or channelHandle can be used)
- channelHandle: YouTube channel handle (alternative to channelId for 'channel' type)
- query: Search query (required when type is 'search')
- playlistId: YouTube playlist ID (required when type is 'playlist')
- maxResults: Maximum number of results (default: 25). Note: YouTube API limits this to 50 for most endpoints.
- order: Sort order ('date' | 'rating' | 'relevance' | 'title' | 'videoCount' | 'viewCount'). Applicable for 'channel' and 'search' types.
- publishedAfter: Filter videos published after this date. Applicable for 'channel' and 'search' types.
- publishedBefore: Filter videos published before this date. Applicable for 'channel' and 'search' types.
- regionCode: Region code for localized results. Applicable for 'search' type.
- categoryId: YouTube category ID. Applicable for 'channel' and 'search' types.
- duration: Filter by video duration ('short' | 'medium' | 'long'). Applicable for 'channel' and 'search' types.
- parts: Additional YouTube API parts to include (e.g., ["snippet", "contentDetails"])
- requestOptions: Custom fetch options
- fetchFullDetails: boolean (default: false). If true, the loader will make additional API calls to fetch duration, viewCount, likeCount, and commentCount for videos from channel, search, and playlist types. If false, these properties may be undefined for those types, but it will reduce API quota usage.

$3

Live content collections loader for runtime YouTube video processing.

#### Options

Same as youTubeLoader, plus:

- defaultMaxResults: Default maximum results for live queries
- defaultOrder: Default sort order for live queries
- defaultRegionCode: Default region code for live queries
- fetchFullDetails: boolean (default: false). If true, the loader will make additional API calls to fetch duration, viewCount, likeCount, and commentCount for videos from channel, search, and playlist types. If false, these properties may be undefined for those types, but it will reduce API quota usage.

#### Filter Options (for getLiveCollection)

These options can be passed to getLiveCollection to filter the results. Filters are applied at the API level where supported, otherwise they are ignored.

##### videos type filters

- limit: Maximum number of results to return.

##### channel type filters

- limit: Maximum number of results to return.
- channelId: Override the channel ID specified in the loader options.
- order: Sort order ('date' | 'rating' | 'relevance' | 'title' | 'videoCount' | 'viewCount').
- publishedAfter: Filter videos published after this date.
- publishedBefore: Filter videos published before this date.
- categoryId: Filter by YouTube video category ID.
- duration: Filter by video duration ('short' | 'medium' | 'long').

##### search type filters

- limit: Maximum number of results to return.
- query: Override the search query specified in the loader options.
- channelId: Limit search results to a specific channel ID.
- order: Sort order ('date' | 'rating' | 'relevance' | 'title' | 'videoCount' | 'viewCount').
- publishedAfter: Filter videos published after this date.
- publishedBefore: Filter videos published before this date.
- regionCode: Region code for localized results.
- categoryId: Filter by YouTube video category ID.
- duration: Filter by video duration ('short' | 'medium' | 'long').

##### playlist type filters

- limit: Maximum number of results to return.

$3

Each video entry returned by the loader conforms to the Video type. When fetchFullDetails is false (the default), properties like duration, viewCount, likeCount, and commentCount may be undefined for videos fetched from channel, search, or playlist types.

If fetchFullDetails is set to true, the returned entries will conform to the VideoWithFullDetails type, where these properties are guaranteed to be present.

`typescript
// Base Video type (when fetchFullDetails is false)
{
id: string;
title: string;
description: string;
url: string;
publishedAt: Date;
duration?: string; // ISO 8601 format (e.g., "PT4M13S")
channelId: string;
channelTitle: string;
thumbnails: {
default?: { url: string; width: number; height: number };
medium?: { url: string; width: number; height: number };
high?: { url: string; width: number; height: number };
standard?: { url: string; width: number; height: number };
maxres?: { url: string; width: number; height: number };
};
tags?: string[];
categoryId?: string;
viewCount?: string;
likeCount?: string;
commentCount?: string;
liveBroadcastContent?: string;
defaultLanguage?: string;
}

// VideoWithFullDetails type (when fetchFullDetails is true)
// All optional fields above (duration, viewCount, etc.) are guaranteed to be present.
`

#### Handling fetchFullDetails in your code

When using fetchFullDetails: false, you should handle the possibility of undefined properties. TypeScript's type narrowing can help:

`typescript
import { getCollection } from "astro:content";
import type { Video, VideoWithFullDetails } from "@ascorbic/youtube-loader";

// Example with fetchFullDetails: false (default)
const videos = await getCollection("videos-without-full-details");

videos.map(videoEntry => {
const video = videoEntry.data; // Type: Video
if (video.duration) {
// TypeScript knows video.duration is string here
console.log(Video duration: ${video.duration});
} else {
console.log("Video duration not available.");
}
});

// Example with fetchFullDetails: true
const videosWithFullDetails = await getCollection("videos-with-full-details");

videosWithFullDetails.map(videoEntry => {
const video = videoEntry.data; // Type: VideoWithFullDetails
// TypeScript knows video.duration is string here, no need for check
console.log(Video duration: ${video.duration});
});
`

$3

- YouTubeError: Base error class
- YouTubeAPIError: YouTube API errors (network, quota, authentication)
- YouTubeValidationError: Data parsing/validation errors
- YouTubeConfigurationError: Configuration/setup errors

$3

- fetchYouTubeVideos(): Fetch videos by ID
- searchYouTubeVideos(): Search for videos
- fetchChannelVideos(): Fetch videos from a channel
- transformYouTubeVideoToVideo(): Transform YouTube API response to internal format

Environment Variables

Set your YouTube API key in your .env file:

`bash
YOUTUBE_API_KEY=your_youtube_api_key_here
``

Rate Limits

The YouTube Data API v3 has quota limits:

- Default quota: 10,000 units per day
- Different operations consume different units
- The loader automatically handles caching to minimize API calls
- Consider the quota impact when choosing between live and static loading

Examples

Check out the demo site for complete examples of using the YouTube loader in an Astro project.