Write JXA using typescript 🚀!
Freely use ES features which typescript supports and provide nice basic development experience.
Thanks to JXA-Cookbook.
It's OS X automation, using Javascript.
Since OS X 10.10 (Yosemite), Javascript (called Javascript for Automation, or JXA) is also supported for app automation. This is great news, especially for Javascript developers who want to automate workflows on their Mac.
But by default, JXA only provides some primitive functionalities for development. For example, if you what to modularizing your code, the only way is Using Script Library which is apple officially recommended but it's cumbersome. And, you can't use any of your favorite node modules like lodash.
So, ts-jxa was born, aiming to make building JXA application more efficient and elegant.
ts-jxa is a development tool for building JXA program.
It let you use a lot of typescript features like arrow function/const && let/promise and most importantly, static type check.
And it gives you a nice development experience by auto rebuild, elegant output, and compression for production.
yarn add ts-jxa or npm i ts-jxa
If you want to install it globally, you can add global flag as follows:
yarn global add ts-jxa or npm i -g ts-jxa
ts-jxa provide two ways to use which are CLI and Programming Interface.
Each usage uses the same options, but has slight differences which I will highlight in the following sections.
-
file(required): path to your entry typescript file
-
options(optional):
-
-r|--run: run bundled JXA file after each bundling process
-
-w|--watch: watch typescript files for changes
-
-c|--compress: compress bundled JXA file
-
-o|--output : output bundled JXA file to specified folder
-
--dev: a shorthand for options
-rw --no-disk, default is false -
--no-disk: not write bundled JXA file to disk
Note that this option is different between CLI and Programming interface, the former is --no-disk which default value is false, and the latter is disk which default value is true.
-
--prod: an alias for options
-cCurrently, it might not a necessary option, but since it has
--dev, it might be more intuitive for beginners to have a comparative options. Further more, there may be more features in production mode in the future. -
-h|--help: show help message
-
If you installed it global, you can use it by command ts-jxa. Following are some examples:
-
default usage:
ts-jxa path-to-tsfile, will generate a bundled .scpt file at current working directory -
auto run:
ts-jxa -r path-to-tsfile, will generate a .scpt file at current working directory and run it -
watch for modification:
ts-jxa -w path-to-tsfile, will automatically rebuild when file changes -
specify output folder:
ts-jxa path-to-tsfile -o path-to-output_folder -
compose of options:
ts-jxa -rw path-to-tsfile, will watch for modification and run it after each bundling process -
dev mode:
ts-jxa --dev path-to-tsfile, which is a shortcut forts-jxa -rw --no-disk path-to-tsfile
You can also import ts-jxa using import(ES module) or require(commonjs).
The default export is a function, like following:
import TsJXA from 'ts-jxa';
TsJXA(entryFilePath, { opts... });First argument is the path to the entry file, which I demonstrated in the API section.
Second argument is an object with the corresponding properties in the API sction's options part.
Following is some examples:
Auto run bundled JXA file:
import TsJXA from 'ts-jxa';
TsJXA(entryFilePath, {
run: true
});You can also compose multiple options:
import TsJXA from 'ts-jxa';
TsJXA(entryFilePath, {
watch: true,
run: true,
disk: false
});Under the hood, ts-jxa uses browserify to bundle and compile typescript code to a single .scpt file.
Thanks to JXA-Cookbook's tip again.
The CLI uses commander to parse command line arguments.
If anybody wants to contribute, feel free to open a pull request😁.
There are sparse documentation about JXA and applescript. So, hope ts-jxa can make a difference in promoting JXA popularization.