vite-plugin-aseprite-live-sync

English | 日本語

Draw. Save. Play.

A Vite plugin that auto-exports Aseprite files.

Whenever you save .aseprite / .ase files, the plugin exports PNG / JSON automatically via Aseprite, so you can remove manual export steps from your workflow. It can also emit a Vite custom HMR event, which you can optionally handle in your app for no-reload asset replacement.

Good Fit For

• Projects built with Vite
• Teams that keep Aseprite files as source assets
• Workflows that need PNG / JSON generated on every save
• Apps that may optionally react to HMR asset update events

Features

• Runs on Vite dev server (serve), no extra command required
• Watches .aseprite / .ase add / change / unlink events
• Rebuilds only changed files via Aseprite
• Preserves input directory structure in output by default
• Auto-detects Aseprite executable
• Emits HMR custom event after export (enabled by default, disable with hmr: false)

Install

npm install -D vite-plugin-aseprite-live-sync

Aseprite must be installed to use this plugin. The plugin tries automatic detection first. If not found, set asepriteExecutable in aseprite-live-sync.config.ts.

Quick Start

1. Register in vite.config.ts

import { defineConfig } from "vite";
import { asepriteLiveSync } from "vite-plugin-aseprite-live-sync";

export default defineConfig({
  plugins: [asepriteLiveSync()],
});

2. Create input directory

Create only the input directory for Aseprite source files manually. The output directory is created automatically on first export based on your outputDir setting.

mkdir -p src-assets/aseprite

3. Start dev server

npm run dev

Aseprite Live Sync starts together with the Vite dev server.

Recommended Folder Layout

your-app/
  public/                      # Public assets served by app
    assets/
      build/                   # PNG / JSON output generated by plugin
        characters/
          player.png
          player.json
        tiles/
          grass.png

  src/                         # App source code
    scenes/
    main.ts

  src-assets/                  # Editable source assets
    aseprite/                  # Input directory for Aseprite files
      characters/
        player.aseprite
      tiles/
        grass.aseprite

  vite.config.ts               # Vite plugin registration
  aseprite-live-sync.config.ts # Plugin settings
  package.json

Recommended: keep editable .aseprite / .ase files outside public, and output only generated PNG / JSON into public/assets/build.

Config File

Config file is optional. If omitted, defaults are used (for example inputDir: "src-assets/aseprite", outputDir: "public/assets/build", exportMode: "auto").

To customize behavior, create one of these files in project root:

• aseprite-live-sync.config.ts
• aseprite-live-sync.config.js

import { defineAsepriteLiveSyncConfig } from "vite-plugin-aseprite-live-sync";

export default defineAsepriteLiveSyncConfig({
  inputDir: "src-assets/aseprite",
  outputDir: "public/assets/build",
  publicPath: "/assets/build",

  exportMode: "auto",
  preserveStructure: true,

  buildOnStartup: true,
  watch: true,

  include: ["**/*.aseprite", "**/*.ase"],
  exclude: ["_old/**", "backup/**", "wip/**", "**/*.tmp.aseprite"],

  rules: [
    { match: "characters/**", exportMode: "auto" },
    { match: "tiles/**", exportMode: "png-only" },
    { match: "effects/**", exportMode: "png-json" },
  ],

  deleteSync: true,
  debounceMs: 300,
  awaitWriteFinishMs: 500,

  asepriteExecutable: undefined,
  hmr: true,
  verbose: true,
});

Config Options

• inputDir
  • Directory for editable Aseprite source files
  • Default: src-assets/aseprite
• outputDir
  • Output directory for generated PNG / JSON
  • Default: public/assets/build
• publicPath
  • Base URL used to reference exported assets in browser
  • Set a public path that corresponds to outputDir
  • Default: /assets/build
• exportMode
  • auto | png-only | png-json
  • Default: auto
  • auto: generates PNG + JSON first, then removes JSON if meta.frameTags is empty
  • png-only: always generate PNG only
  • png-json: always generate PNG + JSON (--format json-array)
• preserveStructure
  • Preserve input subdirectory structure in output
  • Default: true
• buildOnStartup
  • Convert existing files when Vite starts
  • Default: true
• watch
  • Enable file watching during dev server
  • Default: true
• include
  • Include glob patterns
  • Default: ["**/*.aseprite", "**/*.ase"]
• exclude
  • Exclude glob patterns
  • Default: []
• rules
  • Override exportMode per match pattern
  • First matched rule wins
  • If omitted or [], one exportMode applies to all files that pass include/exclude
  • Example: { match: "characters/**", exportMode: "auto" }
• deleteSync
  • Delete generated files when source is deleted
  • Default: true
• debounceMs
  • Debounce for rapid consecutive saves
  • Default: 300
• awaitWriteFinishMs
  • Avoid reading incomplete files right after save
  • Default: 500
• asepriteExecutable
  • Explicit path to Aseprite executable
  • Auto-detected when omitted
• hmr
  • Sends Vite custom event (aseprite-live-sync:update) after export
  • When true, output directory is excluded from Vite watcher to reduce full reloads
  • Default: true
• verbose
  • Verbose logs
  • Default: false

Optional: Consume HMR Event

By listening to aseprite-live-sync:update in your app, you can trigger texture reload or replacement logic after each export.

import type { AsepriteLiveSyncHmrPayload } from "vite-plugin-aseprite-live-sync";

if (import.meta.hot) {
  import.meta.hot.on(
    "aseprite-live-sync:update",
    (payload: AsepriteLiveSyncHmrPayload) => {
      console.log("updated:", payload.outputs.pngPublicPath);
      // Add your own reload / replacement logic here
    },
  );
}

Even without this listener, automatic export still works.

Aseprite Detection Order

1. asepriteExecutable from config file
2. aseprite on PATH
3. OS-specific fallback candidates
   • macOS:
     • /Applications/Aseprite.app/Contents/MacOS/aseprite
     • ~/Applications/Aseprite.app/Contents/MacOS/aseprite
     • ~/Library/Application Support/Steam/steamapps/common/Aseprite/Aseprite.app/Contents/MacOS/aseprite
   • Windows:
     • %ProgramFiles%\Aseprite\Aseprite.exe
     • %ProgramFiles(x86)%\Aseprite\Aseprite.exe
     • %LocalAppData%\Programs\Aseprite\Aseprite.exe
     • %ProgramFiles%\Steam\steamapps\common\Aseprite\Aseprite.exe
     • %ProgramFiles(x86)%\Steam\steamapps\common\Aseprite\Aseprite.exe
   • Linux:
     • /usr/bin/aseprite
     • /usr/local/bin/aseprite
     • /snap/bin/aseprite
     • /var/lib/flatpak/exports/bin/com.aseprite.Aseprite
     • ~/.local/bin/aseprite
     • ~/.local/share/Steam/steamapps/common/Aseprite/aseprite
     • ~/.steam/steam/steamapps/common/Aseprite/aseprite

If not found, this error is shown:

[Aseprite Live Sync] Aseprite executable was not found. Please install Aseprite or set asepriteExecutable in aseprite-live-sync.config.ts.

Log Example

[Aseprite Live Sync] Aseprite detected: /Applications/Aseprite.app/Contents/MacOS/aseprite
[Aseprite Live Sync] Watching: src-assets/aseprite
[Aseprite Live Sync] Exported: characters/player.aseprite -> public/assets/build/characters/player.png + player.json (auto)
[Aseprite Live Sync] Exported: tiles/grass.aseprite -> public/assets/build/tiles/grass.png (auto - no tags)
[Aseprite Live Sync] Deleted: public/assets/build/characters/slime.png

Usage Example

Phaser loading example

Static image:

this.load.image("grass", "/assets/build/tiles/grass.png");

Aseprite animation:

this.load.aseprite(
  "player",
  "/assets/build/characters/player.png",
  "/assets/build/characters/player.json",
);

Troubleshooting

• Aseprite not found
  • Set asepriteExecutable in aseprite-live-sync.config.ts
  • On macOS, verify /Applications/Aseprite.app/Contents/MacOS/aseprite exists
• Saved file does not export
  • Check include / exclude patterns
  • Check watch: true
  • Check inputDir path
• JSON not generated
  • With exportMode: auto, JSON is deleted if no tags exist
  • Use png-json to always generate JSON