Skip to main content

​
Overview

The watch command monitors input directories for file changes and automatically repacks the atlas whenever sprites are added, modified, or deleted. This is ideal for iterative development workflows.

​
Basic usage

fastpack watch [INPUT...] [OPTIONS]

​
Examples

fastpack watch sprites/

​
Arguments and options

The watch command accepts all the same arguments and options as fastpack pack. See the pack reference for complete documentation of available flags.
The watch command shares the exact same configuration options as pack. The only difference is that watch runs continuously and monitors for file changes.

​
Key options

​
INPUT
path[]
Input directories or files to watch for changes. When using --project, this argument is optional.
​
--project
path
Load settings from a .fpsheet project file. The watcher monitors both the input directories and the project file itself.
​
--output
path
default:"output"
Output directory for the generated atlas and data file.
​
--name
string
default:"atlas"
Base name for output files (without extension).
For all other options (layout, trimming, formats, etc.), see fastpack pack.

​
Behavior

​
File monitoring

The watcher monitors:
  • All input directories recursively
  • The project file (when using --project)
  • New files added to watched directories
  • Modifications to existing sprite files
  • Deletions of sprite files

​
Automatic repacking

When a change is detected:
  1. The watcher waits briefly for additional changes (debouncing)
  2. A new pack operation runs with the current settings
  3. Output files are regenerated
  4. Statistics are printed to the console

​
Continuous operation

The watch command runs indefinitely until:
  • You press Ctrl+C to stop it
  • A fatal error occurs (e.g., invalid project file)

​
Example output

$ fastpack watch sprites/ --output dist/
Watching sprites/ for changes...

[12:34:56] Change detected: sprites/player.png
Packed 147 sprites (23 aliases) → 1024×1024 atlas → dist/atlas.png (342.5 KB)
Saved dist/atlas.json (8451 bytes)

[12:35:23] Change detected: sprites/enemy.png
Packed 148 sprites (23 aliases) → 1024×1024 atlas → dist/atlas.png (345.1 KB)
Saved dist/atlas.json (8502 bytes)

​
Use cases

​
Game development

# Watch sprites while developing
fastpack watch assets/sprites/ --output game/dist/
Your game automatically picks up atlas changes as you add or modify sprites.

​
With build tools

# Run watch in a separate terminal
fastpack watch --project production.fpsheet

# Or integrate with package.json
{
  "scripts": {
    "watch:atlas": "fastpack watch --project atlas.fpsheet",
    "dev": "concurrently 'npm:watch:atlas' 'npm:dev:server'"
  }
}

​
Hot reload development

Combine with file system watchers to hot-reload atlases in your development environment: 
# Terminal 1: Watch and repack sprites
fastpack watch sprites/ --output public/assets/

# Terminal 2: Run dev server with hot reload
npm run dev

​
Tips

If you’re using a project file, the watcher will automatically repack when you save changes to the .fpsheet file itself. This makes it easy to iterate on packing settings.
Large sprite sets may take several seconds to repack. The watcher debounces changes to avoid running multiple packs when you save several files at once.

​
Performance considerations

​
Watch performance

  • The watcher uses efficient file system events, not polling
  • Only changed files trigger a full repack
  • Memory usage remains constant during watch operation

​
Repack performance

Packing speed depends on:
  • Number of sprites (100s = fast, 1000s = moderate)
  • --pack-mode setting (fast < good < best)
  • Image sizes and complexity
  • Trim and extrude settings

​
See also

Build docs developers (and LLMs) love

Get started for freeTalk to us