pxt.json Manual Page

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

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

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

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

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

    icon?: string;                // url to icon -- support for built-in packages 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 package was compiled against

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

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

    gistId?: string;

dependencies (on other packages)

Simple packages generally just depend on their own target’s core package:

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

A number of targets use pxt-common-packages and specialize them to fit their target’s needs. For example, the Adafruit Circuit Playground Express package is the union of a number of packages.

    "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 packages 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 package in the target pxt-adafruit is defined in terms of the button package 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.