moon-cycle/.github/wiki/guides/advanced.md

Advanced Usage

Pinning to a specific git tag

Pass a ref argument to cdnUrl to lock images to a specific git tag. This prevents image updates from affecting your app after a dataset refresh:

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

const filename = cycleMonth(new Date());
const url = cdnUrl(filename, 'mm', 256, 75, 'v2.0.0');
// 'https://cdn.jsdelivr.net/gh/acamarata/moon-cycle@v2.0.0/mm-256-75/354.webp'

Choosing between cycleMonth and cycleYear

The two mapping functions use different algorithms:

Function	Dataset	Images	Use when
cycleMonth	Monthly (synodic)	708	Showing the current lunar phase accurately
cycleYear	Yearly (calendar)	8,760	Showing what the moon looked like at a specific date and time in 2023

cycleMonth uses an IAU synodic mean period anchor and repeats the same 708 images every ~29.5 days. The images show all phases of a single synodic cycle. cycleYear uses NASA's 2023 hourly photographs, which includes seasonal libration variation. Neither is "more accurate" — they are different representations.

Using imageFolder directly

import { imageFolder } from 'moon-cycle';

const folder = imageFolder('mm', 512, 85); // 'mm-512-85'
// Use this to construct local paths if you self-host
const imgPath = `/public/moon/${folder}/${filename}`;

Self-hosting images

Clone the repo and copy the image folders to your static assets directory:

git clone https://github.com/acamarata/moon-cycle.git /tmp/moon-cycle
cp -r /tmp/moon-cycle/mm-256-75 /your-project/public/moon/

Then construct local paths instead of CDN URLs:

import { cycleMonth, imageFolder } from 'moon-cycle';

const folder = imageFolder('mm', 256, 75);
const filename = cycleMonth(new Date());
const src = `/moon/${folder}/${filename}`;

TypeScript

import { cycleMonth, cdnUrl } from 'moon-cycle';
import type { ImageSet, ImageSize, ImageQuality } from 'moon-cycle';

function getMoonUrl(date: Date, set: ImageSet, size: ImageSize, quality: ImageQuality): string {
  const filename = set === 'mm' ? cycleMonth(date) : cycleYear(date);
  return cdnUrl(filename, set, size, quality);
}

React usage

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

function MoonPhase({ date }: { date: Date }) {
  const filename = cycleMonth(date);
  const src = cdnUrl(filename, 'mm', 256, 75);
  return <img src={src} alt="Moon phase" width={256} height={256} />;
}