Introduction to JXA

Introduction to JXA

Requirements#

You should have some prior knowledge of JavaScript. There many online and offline resources for the language. The Mozilla Development Network (MDN) provides some introductory information and references for all JavaScript objects and methods.

Getting object information#

The only way to find out which properties and methods an object (or an application, which is just an object) provides, is to open the corresponding “Function Library” in Script Editor. Make sure to set the language selector at the top toolbar to “JavaScript”!

The only source for information on objects is the Function
Library in Script Editor

Writing scripts#

To write the scripts, you can use Apple’s Script Editor that comes pre-installed with macOS. However, I’d suggest that you also install a proper code editor with syntax highlighting and online syntax checking. For example, CodeRunner (not free) is very useful as is Visual Studio Code (free).

Running scripts#

You can run scripts directly from Script Editor. Alternatively, you can use the command line tool osascript that is part of macOS like so

osascript -l JavaScript scriptFile arg1 arg2 arg3 …

The arguments arg1 etc. are simple strings. They are automatically passed to a function named run in the script.

Thirdly, you could run your code from within CodeRunner by defining a new JavaScript runtime environment. In the CodeRunner settings, select the “Language” tab and duplicate the entry for “JavaScript (node)” by clicking first on it and then on the circle with the three dots at the bottom of the language listing and selecting “Duplicate”. Rename the copy to “JavaScript (OSA)” (or whatever you want), select it and change the “Run Command” to osascript -l JavaScript $filename.

Defining a JXA runtime in CodeRunner

If you want to use Visual Studio Code, there’s an AppleScript and JXA extension available for it.

Fourthly, adding #! /usr/bin/osascript -l JavaScript as first line to your script and making it executable by chmod +x script.js in Terminal allows you to run it directly from the command line with ./script.js.

Debugging scripts#

The very short answer to the debugging question is: you can’t.

The slightly longer answer is: use console.log().

The even longer answer is: you can add the line debugger anywhere in your script to open Safari’s web developer console with your script and stop at this line. At least in theory. In practice, I found it worked less often then not.

The longest answer is: debugging JXA scripts does not make sense beyond the most basic things (like what console.log() can print). Safari (nor any other app) knows zilch about applications and their objects. Therefore, the JavaScript engine can’t offer any insights into the structure of objects and their content.

JXA Resources#

As said before, JXA is old and not maintained. The same is true for most of the online resources available. I’ll list the more useful ones here, but don’t expect too much.

Occasionally, JXA questions arise on StackExchange and are (sometimes) answered there.