pxt.json Manual Page

A PXT extension lives in its own directory, locally under libs/ in a PXT target. A extension is described by the pxt.json file. To show a real example, here is the pxt.json file for the pxt-neopixel extension.

The pxt.json is described by the interface PackageConfig in pxtpackage.d.ts:

Packages are now referred to as extensions. The use of the package name in identifiers implies extension.

interface PackageConfig {
    name: string;                 // public:true -> name must match ^[a-z][a-z0-9\-_]+
    description?: string;         // longer description of extension
    license?: string;             // name of license (as found on github)
    authors?: string[];      

    files: string[];              // files to be included and compiled in the extension
    additionalFilePath?: string;  // another directory to find files from

    dependencies: Map<string>;    // extension dependencies (see below for more)
    public?: boolean;             // set true to enable the extension to be published (to cloud),
                                    // in support of publishing user scripts

    icon?: string;                // url to icon -- support for built-in extensions only
    card?: CodeCard;
    documentation?: string; // doc page to open when loading project

    // semver description for support target version
    version?: string;
    installedVersion?: string;
    targetVersions?: TargetVersions; // versions of the target/pxt the extension was compiled against

    testFiles?: string[];
    testDependencies?: string[];
    simFiles?: string[];

    binaryonly?: boolean;
    platformio?: PlatformIOConfig;
    yotta?: YottaConfig;


    gistId?: string;
}

dependencies (on other extensions)

Simple extensions generally just depend on their own target’s core extension:

    "dependencies": {
        "core": "file:../core"
    }

A number of targets use pxt-common-packages and specialize them to fit their target’s needs. These are a base set of extensions for use in a target. For example, the Adafruit Circuit Playground Express extension is the union of a number of extensions.

    "dependencies": {
        "base": "file:../base",
        "core": "file:../core",
        "buttons": "file:../buttons",
        "accelerometer": "file:../accelerometer",
        "lightsensor": "file:../lightsensor",
        "thermometer": "file:../thermometer",
        "music": "file:../music",
        "light": "file:../light",
        "switch": "file:../switch",
        "infrared": "file:../infrared",
        "microphone": "file:../microphone",
        "touch": "file:../touch"
    }

Each of the above extensions is local to the target but inherits code from pxt-common-packages, which it can then override or specialize, as the target needs. For example, the button extension in the target pxt-adafruit is defined in terms of the button extension from pxt-common-packages using the additionalFilePath field:

{
    "description": "Button A and B drivers",
    "additionalFilePath": "../../node_modules/pxt-common-packages/libs/buttons"
}

The additionalFilePath field refers to the node_modules directory of the target. The pxt.json file need to only specify what’s changed (in the example above description) with respect to the pxt.json in additionalFilePath.

The additionalFilePath is recursive or multi-level - the pxt.json in the referenced directory might have another additionalFilePath and it will work as expected.