jxa-userland

The jxa-userland project provides tools to improve the developer experience for JavaScript for Automation (JXA). Key packages include:

• @jxa/run: Allows running JXA code from Node.js.
• @jxa/repl: Provides a REPL environment for JXA.
• @jxa/types: Provides TypeScript types for JXA.
• @jxa/global-type: Enables TypeScript autocomplete and typing for JXA in editors.
• @jxa/sdef-to-dts: Converts SDEF (Scripting Definition) files to TypeScript definition files.

To build and run the provided example project, use the following commands in your terminal:

1. Install dependencies: yarn
2. Build the project: yarn run build
3. Execute the CLI: node lib/cli.js

Install the TypeScript definitions for JXA core using npm.

npm install @jxa/types

Install the @jxa/sdef-to-dts package via npm to convert Scripting definition files (.sdefs) to TypeScript definition files (.d.ts).

npm install @jxa/sdef-to-dts

Install the @jxa/global-type package via npm to enable JXA typing and editor auto-complete for your scripts.

npm install @jxa/global-type

To get TypeScript definitions and autocomplete for JXA APIs in your editor, import @jxa/global-type. This provides the necessary .d.ts definitions for the JXA global environment. Ensure your editor supports TypeScript.

// Your .ts file require @jxa/global-type
import "@jxa/global-type";

// your JXA application
const userName = Application("System Events").currentUser().name();

You can start the JXA REPL using npx without a global installation, or use the jxa-repl command if you have installed it globally. Once started, you can execute JXA (JavaScript for Automation) commands directly in the terminal.

# Using npx
npx @jxa/repl

# Or if installed globally
jxa-repl

# Example interaction
> Application("System Events").currentUser().name();

To run the test suite, install the development dependencies and execute the test command using npm:

npm i -d && npm test

Install the @jxa/repl package globally using npm to use the jxa-repl command.

Requirement:

• Node.js 10 or higher

npm install -g @jxa/repl

You can inject JXA types (like Application) into the global scope by adding a top-level import of @jxa/global-type in your TypeScript file.

import "@jxa/global-type";

// your JXA application
var userName = Application("System Events").currentUser().name();

Install the @jxa/run package using npm.

Requirement:

• macOS 10.10 or later.

npm install @jxa/run