sb-edit

sb-edit is a javascript library for manipulating Scratch project files.

🚧 Warning!

sb-edit is still a work-in-progress. Not everything will work, and the API will probably change drastically. Don't get too comfortable the way things are. ;)

Importing and exporting

sb-edit allows importing and exporting a variety of Scratch project file types:

File Format	Import	Export
Scratch 3.0 (.sb3)	✅ Yes	✅ Yes
Scratch 2.0 (.sb2)	🕒 Planned	🕒 Planned
Leopard	❌ No	✅ Yes
scratchblocks	👻 Maybe!	🚧 In progress

Editing

sb-edit can also be used to modify Scratch projects. A few things you can/will be able to do with sb-edit:

	Add	Edit	Delete
Sprites	🕒 Planned	✅ Yes	✅ Yes
Stage	❌ No	✅ Yes	❌ No
Scripts	🕒 Planned	🕒 Planned	🕒 Planned
Costumes and sounds	🕒 Planned	🕒 Planned	🕒 Planned

CLI Examples

To use the sb-edit CLI, first install it globally using the following command:

$ npm i -g sb-edit

Convert .sb3 project to Leopard

$ sb-edit --input path/to/project.sb3 --output path/to/output-folder

Convert .sb3 project to Leopard .zip

$ sb-edit --input path/to/project.sb3 --output path/to/output-folder.zip

Code Examples

Import an .sb3 file in Node

const { Project } = require("sb-edit");
const fs = require("fs");
const path = require("path");

const file = fs.readFileSync(path.join(__dirname, "myProject.sb3"));
const project = await Project.fromSb3(file);

console.log(project);

Export an .sb3 file in Node

const { Project } = require("sb-edit");
const fs = require("fs");
const path = require("path");

const project = /* Get yourself a `Project`... */;

const saveLocation = path.join(__dirname, "myProject.sb3");
fs.writeFileSync(saveLocation, Buffer.from(await project.toSb3()));

// `project` is now saved at ./myProject.sb3

Get Leopard code for project

const project = /* Get yourself a `Project`... */;

console.log(project.toLeopard({ printWidth: 100 })); // Optionally pass a Prettier config object!

Development

If you want to help develop the sb-edit package, you'll need to follow these steps:

Step 1: Download sb-edit and prepare to use

> git clone https://github.com/PullJosh/sb-edit.git
> cd sb-edit
> npm link # Allow using sb-edit in another local project

Step 2: Add sb-edit as dependency in another project

> cd my-cool-project
> npm init # This should be a node project
> npm link sb-edit # Similar to `npm install` but uses local version

Step 3: Modify sb-edit

If you make any changes to the sb-edit source code, you'll have to rebuild the package. Here's how:

> cd sb-edit # Cloned from Github and then edited
> npm run build # Build the new version!
> npm run watch # Watch files and rebuild automatically when code is changed

You can also run the Jest tests to make sure you didn't break anything:

> cd sb-edit # You're probably already here ;)
> npm test # Run Jest tests
> npm run lint # Check code for style problems

And finally, make sure everything is pretty:

> cd sb-edit
> npm run format # Format code to look nice with Prettier