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”!
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
.
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.
- Apple: Release notes for macOS 10.10
- Apple: Release notes for macOS 10.11
- Apple: Some basic tasks explained in AppleScript and JavaScript
- JXA notes by galvanist
- JXA Cookbook Wiki
Occasionally, JXA questions arise on StackExchange and are (sometimes) answered there.