# run-jxa

> Run JXAcode and get the result

Latest version **4.0.0** (published 2025-09-09) · MIT license · 0 weekly downloads

## Install

```sh
npm install run-jxa
pnpm add run-jxa
yarn add run-jxa
bun add run-jxa
```

## Health

**Score 40/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.0.0 |
| Published | 2025-09-09 |
| First published | 2016-11-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=20 |
| Dependencies | 4 |
| Unpacked size | 9.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 154 |
| Author | Sindre Sorhus |
| Maintainers | sindresorhus |
| Keywords | macos, jxa, javascript, osascript, run, mac, execute, code, script, automation |

## Links

- npm: https://www.npmjs.com/package/run-jxa
- Repository: https://github.com/sindresorhus/run-jxa
- Homepage: https://github.com/sindresorhus/run-jxa#readme
- Issues: https://github.com/sindresorhus/run-jxa/issues
- Funding: https://github.com/sponsors/sindresorhus
- npm.io page: https://npm.io/package/run-jxa

## Dependencies (4)

- [execa](https://npm.io/package/execa.md) ^9.6.0
- [subsume](https://npm.io/package/subsume.md) ^4.0.0
- [type-fest](https://npm.io/package/type-fest.md) ^4.41.0
- [macos-version](https://npm.io/package/macos-version.md) ^6.0.0

## Alternatives

- [flatbuffers](https://npm.io/package/flatbuffers.md) — 6.0M weekly downloads
- [jwt-simple](https://npm.io/package/jwt-simple.md) — 259.5K weekly downloads
- [@exodus/patch-broken-hermes-typed-arrays](https://npm.io/package/@exodus/patch-broken-hermes-typed-arrays.md) — 28.5K weekly downloads
- [@native-to-anchor/buffer-layout](https://npm.io/package/@native-to-anchor/buffer-layout.md) — 12.2K weekly downloads
- [binary-parser-encoder](https://npm.io/package/binary-parser-encoder.md) — 5.3K weekly downloads

## Recent versions

- 4.0.0 (latest) — 2025-09-09
- 3.0.0 — 2021-08-12
- 2.0.0 — 2019-04-06
- 1.2.0 — 2017-12-06
- 1.1.0 — 2017-03-16
- 1.0.2 — 2017-02-05
- 1.0.1 — 2017-02-03
- 1.0.0 — 2016-11-14

## README

# run-jxa

> Run [JXA](https://github.com/dtinth/JXA-Cookbook) code and get the result

*JXA is JavaScript for Automation on macOS. Requires macOS 10.10 or later.*

## Install

```sh
npm install run-jxa
```

## Usage

Use a function:

```js
import {runJxa} from 'run-jxa';

const result = await runJxa((unicorn, horse) => {
	// This is run in the JXA engine
	return `I love ${unicorn} & ${horse}`;
}, ['🦄', '🐴']);

console.log(result);
//=> 'I love 🦄 & 🐴'
```

Or a string:

```js
import {runJxa} from 'run-jxa';

const result = await runJxa(`
	const [unicorn, horse] = args;
	return \`I love \${unicorn} & \${horse}\`;
`, ['🦄', '🐴']);

console.log(result);
//=> 'I love 🦄 & 🐴'
```

Cancel a long-running script:

```js
import {runJxa} from 'run-jxa';

const controller = new AbortController();

// Cancel after 5 seconds
setTimeout(() => {
	controller.abort();
}, 5000);

try {
	const result = await runJxa(() => {
		// Some potentially long-running operation
		const app = Application('Finder');
		return app.windows.length;
	}, undefined, {signal: controller.signal});
	
	console.log(result);
} catch (error) {
	if (error.name === 'AbortError') {
		console.log('Script was cancelled');
	}
}
```

## API

### runJxa(input, arguments?, options?)

Returns a `Promise` for the value returned from `input`.

### runJxaSync(input, arguments?)

Returns the value returned from `input`.

#### input

Type: `Function | string`

If a function, it's stringified and passed to JXA. It should be [pure](https://en.wikipedia.org/wiki/Pure_function), meaning it doesn't access anything outside its body.

If a string, you can access the specified arguments with `args` array. Use the `arguments` parameter rather than template interpolation so you don't have to do escaping.

You can `console.log` inside `input`. It will be forwarded to stdout. Useful for debugging.

Note: The JXA context is completely synchronous, so asynchronous functions like `setTimeout` are not available.

#### arguments

Type: `unknown[]`

Arguments to pass to the JXA context.

Items should be serializable (`JSON.stringify`'able).

#### options

Type: `object`

##### signal

Type: `AbortSignal`

An [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that can be used to cancel the JXA execution.

Only supported by the async `runJxa()` function, not the sync version.

## Related

- [is-jxa](https://github.com/sindresorhus/is-jxa) - Check if your code is running in a JXA environment

---
_Source: https://npm.io/package/run-jxa · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._