Skip to content

Developer Guide

Instructions for developing and contributing to Image Cloud.

Build Scripts

The project includes comprehensive build automation:

# Development
npm run dev              # Start dev server
npm run serve            # Serve on http://localhost:8080
npm run type-check       # Check types only

# Building
npm run build            # Full production build
npm run build:prod       # Build with validation
npm run build:watch      # Watch mode
npm run clean            # Remove dist/

# Releasing - this will only be done by the project owner
npm run release:patch    # 0.1.0 → 0.1.1
npm run release:minor    # 0.1.0 → 0.2.0
npm run release:major    # 0.1.0 → 1.0.0

See scripts/README.md for detailed documentation.

Testing

npm test                 # Run Playwright tests
npm run test:headed      # Run tests with browser visible
npm run test:ui          # Run tests with Playwright UI

Project Structure

src/
├── ImageCloud.ts        # Main gallery class
├── index.ts             # Public exports
├── auto-init.ts         # Auto-initialization from data attributes
├── config/
│   ├── types.ts         # TypeScript interfaces
│   ├── defaults.ts      # Default configuration
│   └── adapter.ts       # Legacy config adapter
├── engines/
│   ├── LayoutEngine.ts  # Position calculations
│   ├── AnimationEngine.ts
│   ├── ZoomEngine.ts
│   ├── EntryAnimationEngine.ts
│   └── PathAnimator.ts  # Entry path animations (bounce, elastic, wave)
├── layouts/             # Layout algorithms
│   ├── RadialPlacementLayout.ts
│   ├── GridPlacementLayout.ts
│   ├── SpiralPlacementLayout.ts
│   ├── ClusterPlacementLayout.ts
│   ├── WavePlacementLayout.ts
│   ├── HoneycombPlacementLayout.ts
│   └── RandomPlacementLayout.ts
├── loaders/
│   ├── GoogleDriveLoader.ts
│   ├── StaticImageLoader.ts
│   ├── CompositeLoader.ts
│   └── ImageFilter.ts   # File extension filtering
└── utils/
    └── styleUtils.ts    # CSS style generation helpers

Code Style

  • TypeScript with strict mode enabled
  • CSS classes prefixed with fbn-ic-
  • ESM modules (type: "module" in package.json)
  • Vite for bundling (UMD and ESM outputs)

Documentation (MkDocs)

The docs are built with MkDocs using the Material theme. Source files are in docs/, config is in mkdocs.yml.

Prerequisites

pip3 install mkdocs-material

Local preview

python3 -m mkdocs serve
# Open http://127.0.0.1:8000/

MkDocs watches docs/ and mkdocs.yml for changes and hot-reloads automatically.

Build

python3 -m mkdocs build   # outputs to site/

Notes

  • docs/plans/ is intentionally excluded from the nav (internal planning docs)
  • The published site is at https://frybynite.github.io/image-cloud/
  • The configurator/ and examples/ directories are published alongside the MkDocs site via the GitHub Pages workflow
  • Versions are pinned in requirements.txt (mkdocs==1.6.1, mkdocs-material==9.7.3) — MkDocs 2.0 is incompatible with Material for MkDocs

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Run tests: npm test
  5. Submit a Pull Request

To Do

Restrict Release Scripts to Project Owner

Currently, release scripts can be run by anyone with repo access. Consider implementing one of these approaches:

  • Rely on npm permissions - Only the owner has the npm token to publish
  • Add user check in script - Validate git user against allowed list
  • GitHub branch protection - Restrict who can push tags matching v*
  • GitHub Actions workflow - Create a release workflow with environment protection rules
  • Keep scripts local - Remove release scripts from repo, maintain locally only