Quick Start

This guide covers the most common use cases in moon-cycle.

Distribution

moon-cycle is not published to npm (the image dataset exceeds the registry size limit). Use one of these options:

# Clone the full repo (code + images)
git clone https://github.com/acamarata/moon-cycle.git

# Install code-only via git
pnpm add github:acamarata/moon-cycle

For most web use cases, you do not need to install anything. Use cdnUrl() to serve images from jsDelivr.

Map a date to a monthly (synodic) image

import { cycleMonth } from 'moon-cycle';

const filename = cycleMonth(new Date(2024, 0, 15));
// e.g. '354.webp'

cycleMonth maps the date to one of 708 hourly images covering one complete synodic cycle. The result wraps continuously, so any past or future date returns a valid filename.

Map a date to a yearly image

import { cycleYear } from 'moon-cycle';

const filename = cycleYear(new Date(2024, 0, 15));
// e.g. '0360.webp'

cycleYear maps to one of 8,760 hourly images from the 2023 calendar year. The mapping repeats annually.

Build a CDN URL

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

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

cdnUrl returns a jsDelivr URL served from the GitHub repository. No server or npm installation needed.

Serve images from a cloned repo

If you cloned the repository, images are in the root-level folders:

mm-256-75/   # monthly, 256x256, quality 75
mm-256-85/   # monthly, 256x256, quality 85
mm-512-75/   # monthly, 512x512, quality 75
mm-512-85/   # monthly, 512x512, quality 85
my-256-75/   # yearly, 256x256, quality 75
...

Reference them relative to wherever you serve the repo:

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

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

CommonJS

const { cycleMonth, cdnUrl } = require('moon-cycle');

const filename = cycleMonth(new Date());
const url = cdnUrl(filename, 'mm', 256, 75);
console.log(url);

Next steps

API Reference for all function signatures and constants
Architecture for how the two algorithms (synodic and yearly) differ

2.4 KiB Raw Blame History