Register a user-script utility

User-Script utilities are re-usable functions that can be imported into user-scripts.

info

Registering user-script utilities is an experimental feature. The API may change in future releases.

Setting up

In a Terminal window, navigate to the directory where your source code will live and run the following command:

npm init foxglove-extension@latest myExtensionName

This uses create-foxglove-extension to create a myExtensionName directory containing source code for an example message converter.

Registering a utility

The index.ts file in your project's src folder is the entry point for your extension source code. It must export an activate function that accepts a single extensionContext argument which provides methods to register extension features.

To register a user-script utility, call registerUserScriptUtility on the extensionContext argument and provide the name and TypeScript source code of the utility.

import { Experimental, Immutable } from "@foxglove/extension";

const myUtilitySourceCode = `
export function addTwo(arg: number): number {
  return arg + 2;
}
`;

export function activate(extensionContext: Experimental.ExtensionContext): void {
  extensionContext.registerUserScriptUtility({
    name: "my_utility.ts",
    source: myUtilitySourceCode,
  });
}

Testing

Package and install the extension. Then open the user-script panel and create a new script. In your script you can now import the addTwo function from the utility.

import { addTwo } from "./my_utility.ts";

type Output = { value: number };

export const inputs = ["/imu"];
export const output = "/imu_plus_two";

export function script(event: Input<"/imu">): Output {
  return { value: addTwo(event.message.acceleration) };
}

You can view the source code of your utility by clicking the "Utilities" tab and finding your utility, "my_utility.ts", under the "Extension Utilities" section.

---

Advanced usage: keep source code in a separate file

note

You need v1.1.0 or later of create-foxglove-extension in your package.json to use this feature.

As your utility grows, it may make sense to keep the source code in a separate file in your extension project. This allows you to have editor syntax highlighting and write tests for your utility. To achieve this, make a file named my_utility.ts alongside your extension's index.ts file and put your utility code in there.

my_utility.ts

export function addTwo(arg: number): number {
  return arg + 2;
}

info

Your utility module source code must be self-contained. It cannot rely on other npm modules or files in your project. It can rely on other utilities you register.

Teach typescript the type of ?raw imports

Add the following to a file called raw.d.ts alongside the my_utility.ts file.

// Tell typescript that any import using the `?raw` syntax is a string.
declare module "*?raw" {
  const rawFileContent: string;
  export default rawFileContent;
}

Importing the source code

In your index.ts file, import the source code from the separate file using the ?raw import syntax. This will import the source code as a string rather than as a module.

import { Experimental, Immutable } from "@foxglove/extension";

import myUtilitySourceCode from "./my_utility.ts?raw";

export function activate(extensionContext: Experimental.ExtensionContext): void {
  extensionContext.registerUserScriptUtility({
    name: "my_utility.ts",
    source: myUtilitySourceCode,
  });
}