moon-cycle

Maps dates and times to NASA SVS moon phase imagery. 8,760 hourly frames covering a full year, delivered via jsDelivr CDN.

Overview

The NASA Scientific Visualization Studio publishes annual moon phase video sequences — one frame per hour for an entire year, showing the Moon from Earth's perspective with accurate libration, phase illumination, and orientation.

moon-cycle provides a TypeScript API to map any date/time to the correct frame index and generate a CDN URL for that image.

GitHub: github.com/acamarata/moon-cycle

Installation

pnpm add moon-cycle

API

cycleMonth

Returns an array of frame descriptors for every hour of a given month.

cycleMonth(options: { year: number; month: number }): MoonFrame[]

import { cycleMonth, cdnUrl } from 'moon-cycle'

const frames = cycleMonth({ year: 2025, month: 3 })
console.log(frames.length)  // 744 (31 days × 24 hours)

const firstFrame = frames[0]
console.log(firstFrame.date)   // 2025-03-01T00:00:00Z
console.log(firstFrame.index)  // frame index in the NASA dataset
console.log(cdnUrl(firstFrame)) // jsDelivr CDN URL

cycleYear

Returns frame descriptors for every hour of a full year (8,760 frames for non-leap years, 8,784 for leap years).

cycleYear(options: { year: number }): MoonFrame[]

import { cycleYear, cdnUrl } from 'moon-cycle'

const frames = cycleYear({ year: new Date().getFullYear() })
const now = new Date()
const hourIndex = Math.floor((now.getTime() - new Date(now.getFullYear(), 0, 1).getTime()) / 3_600_000)
const currentFrame = frames[hourIndex]

const imageUrl = cdnUrl(currentFrame)
// Use in an <img> tag or Next.js <Image> component

cdnUrl

Returns the jsDelivr CDN URL for a given frame.

cdnUrl(frame: MoonFrame): string

CDN delivery

The ~438 MB NASA image dataset is hosted on jsDelivr via the moon-cycle-data npm package. jsDelivr serves all npm package files from their global CDN at no cost.

// https://cdn.jsdelivr.net/npm/moon-cycle-data@2025/frames/2025-03-15-14.jpg

Images are 512×512 JPEG, approximately 20–40 KB each. They show the Moon against a black background with accurate libration (wobble), phase illumination, and orientation relative to the horizon.

Dataset details

NASA publishes a new annual sequence each year. The moon-cycle-data npm package is updated annually with the new dataset.