@sa-community/addons-data

This repository contains the script used to auto-generate @sa-community/addons-data.

Usage

The package exports an array of objects { addonId: string, manifest: AddonManifest }[]. For example, to get all addon manifests with the forums tag:

import addons from "@sa-community/addons-data";

addons.filter((addon) => addon.manifest.tags.includes("forums")).map((addon) => addon.manifest);

Addon IDs are not included in the manifest itself. To get them:

import addons from "@sa-community/addons-data";

addons.filter((addon) => addon.manifest.tags.includes("forums")).map((addon) => addon.addonId);

@sa-community/addons-data uses CommonJS, meaning that it can also be used via require:

const addons = require("@sa-community/addons-data");

addons.filter((addon) => addon.manifest.tags.includes("forums")).map((addon) => addon.manifest);

Versioning

This package is versioned based off Scratch Addons itself. The versioning schema is SA major + SA minor (3-digit zero-padded) + "." + SA patch + "." + data patch. In other words, for SA version 1.2.3, you would install @sa-community/addons-data@~1002.3.0, or for SA version 1.40.0, you would install @sa-community/addons-data@~1040.0.0.

Please note that in version 1.41.0 and prior, the version number of this package was identical to that of Scratch Addons instead.

Types

The package is fully typed, including all addon manifests. The addon manifest typedef is based off manifest-schema, and I try to keep them as similar as possible.

All addon manifests on Scratch Addons's master branch are typechecked against that typedef every 12 hours. If there are any errors, an issue is automatically created. Issues indicate either that the typedef needs to be updated or a mistake in an addon manifest.

I try my best to keep the typedef updated. However, only the latest released is guaranteed to be accurate. If mistakes with a version's types are found only once it is no longer the latest version, I will not retroactively rerelease.

Typedef vs JSON Schema

Everything the typedef checks is also checked by the JSON Schema, but there are a few small things the typedef can't check easily:

• Patterns for colors, links, and IDs
• Minimums for numerical values
• Minimum lengths for string values
• Minimum item counts for array values
• Minimum property counts for record values
• No extraneous properties
• Every addon having one of the "main" tags (community, editor, player, popup)

Ease of maintenance is the typedef's main advantage over the schema for manifest verification. TypeScript typedefs are also more portable and could be used in more contexts than a JSON schema could be.

Importing a single addon's data

You can also import just one addon by its ID:

import addon from "@sa-community/addons-data/addons/semicolon";

console.log(addon.name); // Semicolon glitch
console.log(addon.credits[0].name); // GrahamSH

Note that while the package is typed, each addon is typed generically to prevent breaking changes. Meaning, the type of each addon is the generic AddonManifest, and the types do not define specific keys for specific addons.

Importing the manifest

This package also exports the extension manifest:

import manifest from "@sa-community/addons-data/manifest.json" with { type: "json" };

console.log(manifest.version); // 1.42.0
console.log(manifest.homepage_url); // https://scratchaddons.com