Registry / serialization / scratch-parser

scratch-parser

library6.0.0jsnpmunverified

scratch-parser is a Node.js module designed for parsing and validating Scratch project files, including `.sb2` and `.sb3` formats. Its current stable version is 6.0.0. The library provides programmatic access to the internal structure of Scratch projects, enabling developers to inspect sprites, scripts, assets, and metadata. It has an active development cycle, with bug fixes and dependency updates released periodically, though major versions are less frequent. Key differentiators include its direct integration with the Scratch ecosystem, offering reliable parsing for official Scratch project formats, and its focus on providing a structured JavaScript object representation of the project data.

serialization data

npm install scratch-parser

github ↗package ↗

INSTALL

IMPORT

SIG · SCRATCH-PARSER

scratch-parser

serializationjavascriptv6.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parser

✓ import parser from 'scratch-parser';

✗ const parser = require('scratch-parser');

While CommonJS `require` is shown in older examples, modern Node.js environments should prefer ESM `import`.

parser

✓ const parser = require('scratch-parser');

This CommonJS import style is explicitly demonstrated in the README's 'Basic Use' section.

Demonstrates how to read a Scratch project file from disk and parse it using the `scratch-parser` library, handling potential errors and logging basic project information.

import fs from 'fs'; import parser from 'scratch-parser'; const projectBuffer = fs.readFileSync('/path/to/project.sb3'); // Or .sb2 parser(projectBuffer, false, (err, project) => { if (err) { console.error('Error parsing Scratch project:', err); // Depending on the error, you might want to log more details // or return a default project structure. return; } console.log('Successfully parsed Scratch project!'); console.log('Project title (if available):', project._meta ? project._meta.name : 'N/A'); console.log('Number of targets:', project.targets ? project.targets.length : 0); // Example: Accessing a specific property or a sprite's data // console.log('First sprite name:', project.targets[1] ? project.targets[1].name : 'No sprites'); // Further processing of the 'project' object can happen here. });

Debug

Known issues

breakingThe license of `scratch-parser` changed to AGPL-3.0-only. This is a significant breaking change for applications that cannot comply with the AGPLv3 license terms.

fix

Review your project's licensing compatibility with AGPL-3.0-only. If incompatible, you may need to remain on an older version or find an alternative.

affects: >=6.0.0

breakingSupport for gzipped Scratch 2.0 (SB2) files was removed. The parser no longer handles `.gz` compressed inputs directly.

fix

Ensure that any SB2 files provided to the parser are not gzipped. If you previously handled gzipped files, you must decompress them manually before passing the buffer to `scratch-parser`.

affects: >=5.0.0

gotchaThe parser expects specific buffer formats. Incorrectly formatted or corrupted project files will result in parsing errors.

fix

Always validate the input buffer for integrity if it originates from an untrusted source. Implement robust error handling around parser calls.

affects: >=4.0.0

gotchaProject `info` metadata, such as `flashVersion` or `userAgent`, may not always be present depending on how the Scratch project was saved or created.

fix

When accessing `project.info` fields, always check for their existence before using them (e.g., `project.info?.flashVersion`).

affects: >=4.0.0

gotchaThere was a fix for backslash handling that removed backslashes followed by 'b' incorrectly. This could affect certain string literals within Scratch projects.

fix

Ensure you are on the latest version to benefit from bug fixes related to character parsing. If on an affected version, be aware that strings like `\b` might be misparsed.

affects: >=5.1.1 <6.0.0

Errors

Common errors & fixes

Error: Not a valid SB2 or SB3 file.

The input buffer provided to the parser is not a correctly formatted Scratch project file (either SB2 or SB3). This could be due to a corrupted file, an unsupported format, or incorrect file reading.

fix

Verify the integrity and format of the input file. Ensure it's a `.sb2` or `.sb3` file and that the buffer correctly contains its contents. Check that gzipped SB2 files are decompressed before passing them to the parser (v5.0.0+).

TypeError: Cannot read property 'length' of undefined

This often occurs when trying to access properties of the `project` object (e.g., `project.targets`) immediately after a parsing error or if the parsed project structure is unexpected/incomplete.

fix

Implement robust error handling around the parser callback and defensively check for the existence of properties before accessing them (e.g., `if (project && project.targets) { ... }`).

Error: ENOENT: no such file or directory, open '/path/to/project.sb2'

This is an underlying Node.js `fs` error, indicating that the file path provided to `fs.readFileSync` (or similar) does not exist.

fix

Double-check the file path and ensure the file exists at the specified location. Use absolute paths or correctly resolve relative paths.

Upgrade

Version history

6.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

24 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/scratchfoundation/scratch-parser ↗

packagehttps://www.npmjs.com/package/scratch-parser ↗