vite-texture-packer

English | Русский

vite-texture-packer is a Vite plugin that automatically scans sprite directories and packs them into atlases. The plugin is compatible with Phaser and PixiJS.

Installation

npm i vite-texture-packer

Usage

import { defineConfig } from "vite";
import texturePacker from "vite-texture-packer";

export default defineConfig({
  plugins: [
    texturePacker({
      inputDir: "./textures",
      outputDir: "./public/resources/atlases",
    }),
  ],
});

Each directory inside inputDir is packed independently. For example, for ./textures/ui/buttons the plugin will generate:

• public/resources/atlases/ui/buttons/buttons.png
• public/resources/atlases/ui/buttons/buttons.json

Example Project Structure

public
└── resources
    └── atlases
        └── .gitkeep
textures
├── ui
│   ├── MenuIcons
│   │   ├── AchievementsIcon.png
│   │   ├── Chest.png
│   │   └── SettingsIcon.png
│   ├── SocialIcons
│   │   ├── DiscordIcon.png
│   │   ├── GoogleIcon.png
│   │   └── TelegramIcon.png
│   └── Spinner
│       ├── Spinner_0.png
│       ├── Spinner_1.png
│       ├── Spinner_2.png
│       └── Spinner_3.png
└── weapons
    └── GasterBlaster
        ├── GasterBlaster_0.png
        ├── GasterBlaster_1.png
        ├── GasterBlaster_2.png
        └── GasterBlaster_3.png
vite.config.ts

The plugin will generate atlas file pairs that mirror the source folder structure:

public
└── resources
    └── atlases
        ├── ui
        │   ├── MenuIcons
        │   │   ├── MenuIcons.png
        │   │   └── MenuIcons.json
        │   ├── SocialIcons
        │   │   ├── SocialIcons.png
        │   │   └── SocialIcons.json
        │   └── Spinner
        │       ├── Spinner.png
        │       └── Spinner.json
        ├── weapons
        │   └── GasterBlaster
        │       ├── GasterBlaster.png
        │       └── GasterBlaster.json
        └── .gitkeep

Options

interface TexturePackerOptions {
  inputDir: string;
  outputDir: string;
  maxWidth?: number;
  maxHeight?: number;
  padding?: number;
  cacheFile?: string;
}

Option	Default	Description
inputDir	required	Directory with source images to pack. Each nested folder becomes its own atlas.
outputDir	required	Directory where generated .png and .json files are written, mirroring the inputDir structure.
maxWidth	2048	Maximum allowed width of a single atlas PNG. The plugin tries to fit all images from one folder into an atlas no wider than this.
maxHeight	2048	Maximum allowed height of a single atlas PNG. The plugin tries to fit all images from one folder into an atlas no taller than this.
padding	2	Padding in pixels between sprites inside the atlas.
cacheFile	<vite cache dir>/texture-packer.json	Path to the cache file used to avoid rebuilding unchanged atlases.

Notes

• outputDir cannot be the same as inputDir and cannot be nested inside inputDir.
• Only png, jpg, jpeg, and webp files are packed.
• 2048x2048 is the recommended atlas limit for broad browser and mobile GPU compatibility. Larger atlases are more likely to exceed MAX_TEXTURE_SIZE on older devices, create VRAM spikes during texture uploads, and slow down scene startup.
• If source files are removed from a directory, stale generated atlas files are removed automatically.