shooting-stars-meme-generator: Instructions file for Claude Code

CLAUDE.md

This file gives guidance to Claude Code (claude.ai/code). Read it before you work with code in this repository.

What this is

This project is a single-page site. It recreates the "shooting stars" meme. A background video plays. Up to 6 images fly across the screen. The images move in time with fixed animation keyframes. The user uploads the images. The site shows the default doge image when the user uploads nothing.

The site can also export the animation as a video file. The server renders it with a native canvas and ffmpeg. It uses no headless browser. The output is MP4, WebM, or GIF. See server/CLAUDE.md.

Commands

Docker is the preferred workflow. Use just. Run just --list for the recipes. Run just check and just test before a pull request. Both run in the dev container.

Configuration

Copy .env.dist to .env to change APP_PORT, HASH_LENGTH, UPLOADS_DIR, or UPLOAD_RETENTION_DAYS.

Compose reads these variables in two different ways:

• HASH_LENGTH and UPLOAD_RETENTION_DAYS go through the env_file: key in docker-compose.yml. Compose puts them in the process.env of the container. server.ts reads them. scripts/clean_old_uploads.sh reads them too.
• APP_PORT and UPLOADS_DIR never reach the container. Compose itself reads them when it parses docker-compose.yml. Compose expands them as plain shell ${VAR} text. APP_PORT sets the port map on the host. UPLOADS_DIR sets the path of the uploads bind mount. The bun, bun-dev, and cleanup services share that mount.

Both mechanisms read the same .env file. They are separate Compose features in every other way.

The listening port of the application is fixed on purpose. server.ts hardcodes 9595. This is true for bun server/server.ts. It is also true inside a container. Only the publish port on the host can differ. APP_PORT sets that port. Its default value is 9595.

.env is optional. The project still works without it. server.ts then uses its own default values. Compose then uses its own ${VAR:-default} values. The current default for UPLOADS_DIR is /tmp/shooting-stars-uploads. This is a dedicated subfolder, not bare /tmp. A bare /tmp would pull unrelated host files into the bind mount. Point UPLOADS_DIR at a real persistent host path for production. Docker creates the directory on the first up. You need no manual setup. The cleanup service prunes that directory by age, like any other path. No other lifecycle work is necessary.