{"id":12833,"library":"ase-parser","title":"Aseprite File Parser","description":"The `ase-parser` library provides a pure JavaScript solution for parsing Aseprite `.aseprite` files into a structured object, enabling programmatic access to sprite data like frames, layers, cels, slices, tilesets, and palettes. Currently at version `0.0.18`, it's actively maintained with a focus on adding support for newer Aseprite features like Aseprite 1.3 fields, tilesets, tilemap layers, and linked cels. It ships with TypeScript types, facilitating its use in modern TypeScript projects. A key differentiator is its minimal footprint, having no runtime dependencies for the core parsing functionality. While examples might utilize libraries like `sharp` for image manipulation, `ase-parser` itself focuses solely on data extraction. The `0.0.x` versioning suggests ongoing development, with feature additions and bug fixes released as needed, and implies that breaking changes could occur in minor versions.","status":"active","version":"0.0.18","language":"javascript","source_language":"en","source_url":"https://github.com/TheCyberRonin/ase-parser","tags":["javascript","Aseprite","parser","ase","typescript"],"install":[{"cmd":"npm install ase-parser","lang":"bash","label":"npm"},{"cmd":"yarn add ase-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add ase-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The main Aseprite class is a default export in ESM environments.","wrong":"import { Aseprite } from 'ase-parser';","symbol":"Aseprite","correct":"import Aseprite from 'ase-parser';"},{"note":"CommonJS import for the Aseprite class. This is equivalent to the default ESM import.","symbol":"Aseprite","correct":"const Aseprite = require('ase-parser');"},{"note":"Imports specific types (like AsepriteFrame) are named exports, typically used with `import type`.","wrong":"import { AsepriteFrame } from 'ase-parser';","symbol":"AsepriteFrame","correct":"import type { AsepriteFrame } from 'ase-parser';"}],"quickstart":{"code":"import Aseprite from 'ase-parser';\nimport * as fs from 'fs';\n\n// Create a dummy Aseprite file buffer for demonstration\n// In a real scenario, replace this with fs.readFileSync('./path/to/your.aseprite')\nconst createDummyAsepriteBuffer = (): Buffer => {\n  // This is a minimal, non-functional placeholder buffer.\n  // A real Aseprite file is a complex binary structure.\n  // For actual testing, you would need a valid .aseprite file.\n  const dummyHeader = Buffer.from([\n    0x00, 0x00, 0x00, 0x00, // file size\n    0x01, 0x00, // magic number\n    0x01, 0x00, // frames\n    0x10, 0x00, // width\n    0x10, 0x00, // height\n    // ... many more bytes for a valid Aseprite file ...\n  ]);\n  return dummyHeader;\n};\n\nconst filePath = './my_chocobo.aseprite';\ntry {\n  const buff = fs.readFileSync(filePath);\n  const aseFile = new Aseprite(buff, filePath);\n\n  aseFile.parse();\n  console.log(`Successfully parsed Aseprite file: ${aseFile.name}`);\n  console.log(`Number of frames: ${aseFile.numFrames}`);\n  console.log(`Sprite dimensions: ${aseFile.width}x${aseFile.height}`);\n  if (aseFile.frames.length > 0) {\n    console.log(`First frame cels: ${aseFile.frames[0].cels.length}`);\n  }\n} catch (error) {\n  if ((error as NodeJS.ErrnoException).code === 'ENOENT') {\n    console.error(`Error: Aseprite file not found at ${filePath}. Please create one or update the path.`);\n  } else {\n    console.error(`Failed to parse Aseprite file: ${error instanceof Error ? error.message : String(error)}`);\n  }\n}\n","lang":"typescript","description":"This quickstart demonstrates how to instantiate and parse an Aseprite file using `ase-parser`, logging basic sprite information. It includes a placeholder for reading a file and basic error handling for file not found."},"warnings":[{"fix":"Pin exact versions (e.g., `\"ase-parser\": \"0.0.18\"`) or thoroughly test updates before deploying to production.","message":"The package is in `0.0.x` versioning, which means breaking changes may occur in minor or patch releases without strictly adhering to SemVer principles. Always review changelogs when updating.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Only install `sharp` (`npm install sharp`) if your application explicitly needs image processing capabilities. If not, omit it from your `package.json`.","message":"The `sharp` library is frequently used in README examples for image processing after parsing. It is NOT a direct dependency of `ase-parser` itself. Installing `sharp` is optional and only required if you intend to perform image manipulation (e.g., generating PNGs from raw pixel data).","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Update to `ase-parser@0.0.16` or newer to resolve issues with ICC color profile data processing. This fix improved parsing robustness for certain file types.","message":"Earlier versions (`<0.0.16`) had a bug that could lead to an 'out of range read' error when processing Aseprite files containing specific ICC color profiles, potentially causing crashes during parsing.","severity":"gotcha","affected_versions":"<0.0.16"},{"fix":"Ensure `aseFile.parse();` is called immediately after instantiating `new Aseprite(buffer, name);` and before accessing any parsed data.","message":"The `parse()` method must be explicitly called on the `Aseprite` instance before attempting to access any properties (like `numFrames`, `width`, `height`, `frames`). Forgetting to call `parse()` will result in `undefined` values or errors.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"For ESM, use `import Aseprite from 'ase-parser';`. For CommonJS, use `const Aseprite = require('ase-parser');`. Ensure you are calling `new Aseprite(...)` to create an instance.","cause":"The Aseprite class was not correctly imported as a default export in an ESM context, leading to the `Aseprite` variable not being the class constructor itself, or `parse` was accessed before instantiation.","error":"TypeError: aseFile.parse is not a function"},{"fix":"After creating `const aseFile = new Aseprite(buff, name);`, you must call `aseFile.parse();` to populate its properties from the Aseprite file data.","cause":"The `parse()` method was not called on the Aseprite instance before attempting to access parsed properties like `width`, `height`, or `numFrames`.","error":"Error: Cannot read properties of undefined (reading 'width')"},{"fix":"Run `npm install ase-parser` or `yarn add ase-parser` to install the package. Verify your `import` or `require` statement matches the package name.","cause":"The `ase-parser` package is not installed, or the import/require path is incorrect, or your module resolver cannot find it.","error":"Error: Cannot find module 'ase-parser'"},{"fix":"Verify that the file path in `fs.readFileSync('./your_file.aseprite')` is correct and the file exists at that location relative to where your script is run.","cause":"The file path provided to `fs.readFileSync()` does not point to an existing Aseprite file.","error":"Error: ENOENT: no such file or directory, open './somefile.aseprite'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null}