JavaScript actions

JavaScript actions run code in PopClip's own JavaScript environment, which gives them access to PopClip's internal state and lets them interact with PopClip itself.

Module-based extensions

For more complex functionality, JavaScript module-based extensions are a flexible and powerful alternative to JavaScript actions.

Properties

A JavaScript action is defined by the presence of either a javascript or javascript file field, as follows:

Key	Type	Description
javascript	String	A JavaScript text string to load.
javascript file	String	Path to a JavaScript (.js) or TypeScript (.ts) file in the package directory.

Script format

The script's entry point is at the top level of the file. Internally, PopClip loads the provided script and wraps it as a function. When the action is run, PopClip calls the function.

Function wrapper detail

As an example, imagine the following JavaScript is provided in the javascript field:

return "foo";

Internally, this will be wrapped in an async arrow function definition like this:

const main = async () => { 
  return "foo";
}; 

When the action is run, PopClip calls this internal main function with no arguments.

In addition to pure JavaScript, PopClip can load TypeScript from files named with a a .ts extension. See TypeScript support.

Input and output

Scripts take their input from the global popclip object.

If the script exits by returning a string, it will be passed to the after step.

Return type

To return a value to the after step, it must be of type string. If the script returns a value of any other type, such as number or object, PopClip will ignore it.

Indicating errors

Scripts should indicate success by completing normally (either by explicitly returning a value, or implicitly returning undefined) and should indicate failure by throwing an error. PopClip will catch any erros thrown by the script and display the shaking-'X'.

To indicate an error with the user's settings, and pop up the extension's settings UI, throw an error message starting with the specific words settings error or not signed in (not case sensitive). For example:

throw new Error("Settings error: missing API key");

Examples

About these examples

The examples are given as snippets using the inverted syntax.

Uppercase the text:

// # popclip
// name: Uppercase
// icon: square filled AB
// after: paste-result
// language: javascript
return popclip.input.text.toUpperCase();