@fermyon/knitwit

@fermyon/knitwit

This package provides a way to package npm packages that depend on the wasi imports to be built using ComponentizeJS. This repository includes a library and two node executable (knitwit and knitwit-postinstall).

knitwit.json

This configuration file plays a central role in defining how the knitwit tool interacts with your project. The file specifies the packages, their corresponding wit paths, and the world names necessary for building with wasi imports. This file is edited by the postinstall executable and read by the library. The schema for this file is defined using yup for validation and looks like this:

interface PackageConfig {
    witPath: string;
    world: string;
}

interface ProjectConfig {
    witPaths?: string[];
    worlds?: string[];
}

interface KnitWitConfig {
    version: number;
    project: ProjectConfig;
    packages: Record<string, PackageConfig>;
}

Fields of knitwit.json

• version - It is the version which describes the format of the config file
• project - This contains the project specific witPaths and worlds
• packages - This field contains information about the different npm packages installed.

Here's an example of what a knitwit.json file might look like:

{
  "version": 1,
  "project": {},
  "packages": {
    "example-package-1": {
      "witPath": "path/to/example1.wit",
      "world": "exampleWorld1"
    },
    "example-package-2": {
      "witPath": "path/to/example2.wit",
      "world": "exampleWorld2"
    }
  }
}

The knitwit Executable

It can be found in bin/knitwit.mjs. This is used to parse the knitwit.json to get the combined wit output. This needs to be run after a npm install which may install packages that may have dependencies on wasi. It also needs to be run after any changes in the project field. This can be added to the postinstall script in package.json to automate updating based on package installs.

The knitwit-postinstall Executable

It can be found in bin/knitwit-postinstall.js, this can be used in the postinstall scripts of packages that use wasi imports to update the knitwit.json. The executable uses configuration provided in the package.json to update knitwit.json.

The following field needs to be added to the config key of the package.json :

• knitwit.witPath - The relative path to the wit file/folder from the main entrypoint of the package.
• knitwit.world - The name of the world that contains all the names required for the package.

An example of how the configuration will look is as below:

{
    ...
    "config": {
        "knitwit": {
            "witPath": "<relative path to wit from entrypoint>",
            "world": "<world with all imports>"
        }
    }
    ...
}

The executable needs to be added to the postinstall script after adding the @fermyon/knitwit package to the dependency list. The post install script takes in 2 arguments for --wit-path and --world optionally which it uses to update the configuration. If the values are not provided, it defaults to attempting to parse it of the package.json

{
    ...
    "scripts": {
        "postinstall": "knitwit-postinstall --wit-path <path_to_wit> --world <default_world>"
    }
    ...
}

Note: The postinstall script should not include npx as that will alter the environment variables which the executable relies on to run in the context of the consumer.

Library and Usage

The @fermyon/knitwit package provides a function knitWit to parse knitwit.json, merging packages and their required worlds into a unified output package.

The library exposes one function knitWit which has the following signature:

interface knitWitOptions {
    witPaths?: string[];
    worlds?: string[];
    outputWorld?: string;
    outputPackage?: string;
    outDir?: string;
}
export declare function knitWit(opts?: knitWitOptions, ignoreConfigFile?: boolean): Promise<void>;

• witPaths and worlds in opts are concatenated with those parsed from knitwit.json.
• Additional options in opts include:
  • outputWorld: Name of the world in the generated wit package (default: "combined").
  • outputPackage: Package specifier in the generated wit package (default: "local:combined").
  • outDir: Directory where the generated wit package is saved (default: "combined-wit").

To ignore parsing the config file, set ignoreConfigFile to true.

usage

import { knitWit } from '@fermyon/knitwit';

knitWit({ worlds: ["additionalWorld1", "additionalWorld2"] });

The output generated by the above can then be used as input to ComponentizeJS.