JavaScript
Tokens cover the common values. For anything else, add a small JavaScript file. Its update(context) function returns values, and each one becomes a {script.<name>} token.
A first script
Section titled “A first script”Your widget must be a package (a .atsuraewidget folder) with the script inside:
Greeting.atsuraewidget/├── widget.json└── script.jsTell widget.json about the script:
"script": { "file": "script.js", "updateEvery": "minute" }Write update:
function update(context) { const hour = context.now.getHours(); const greeting = hour < 12 ? "Good morning" : hour < 18 ? "Good afternoon" : "Good evening"; return { greeting };}Use the value:
{ "text": "{script.greeting}" }That’s the whole model: Atsurae calls update with what it knows, you return an object, and the object’s values fill {script.*} tokens.
update(context)
Section titled “update(context)”Your script must define a function called update. Atsurae passes it a context object:
{ now: Date, // the current date and time options: { // this placement's option values, as strings use24Hour: "true", name: "Sam", }, screen: { width: 1512, height: 982 }, // the main display, in points battery: { present: true, level: 0.82, charging: false }, cpu: { level: 0.12 }, // 0...1 memory: { used: 8700000000, total: 17179869184, level: 0.51 }, // bytes; level 0...1 track: { title: "Song", artist: "Artist", playing: true }, weather: { // or null before it loads or if it's unavailable temperature: 21, high: 24, low: 15, feelsLike: 20, unit: "°C", // °F on Macs set to Fahrenheit condition: "Partly Cloudy", humidity: 0.62, location: "Cupertino", },}Values that aren’t known yet are null, e.g. battery.level on a Mac without a battery, or cpu.level in the first few seconds. Check before using them. The Script API reference describes every field.
What you can return
Section titled “What you can return”Return a plain object. Each property becomes a token:
| You return | Token shows |
|---|---|
"Hello" |
Hello |
42 |
42 |
0.4375 |
0.4375 |
true / false |
true / false |
null or undefined |
(empty) |
| an array or object | its JSON, e.g. ["a","b"] |
Numbers come through as written, so format them in JavaScript (n.toFixed(1)) or with modifiers ({script.n|round}, {script.p|percent}). Numbers from 0 to 1 work directly as progress values. Booleans work with visibleWhen.
Return everything every time. Values you stop returning disappear.
When it runs
Section titled “When it runs”updateEvery sets the schedule:
updateEvery |
Runs |
|---|---|
"minute" (default) |
just after every new minute |
"second" |
every second |
a number, like 300 |
every that many seconds (at least 1) |
It also runs right away when the widget appears or its files change, and whenever the battery, the playing song or the weather changes. See When widgets update.
Use the slowest schedule that works. Always compute from context.now rather than counting runs.
Keeping state
Section titled “Keeping state”Your script stays loaded while the widget is on, so variables outside update keep their values between runs:
let runs = 0;const quotes = ["…", "…"]; // built once
function update(context) { runs += 1; return { runs };}State resets when the widget’s files change, the widget is turned off, or Atsurae restarts. Don’t store anything you can’t recompute.
The sandbox
Section titled “The sandbox”Scripts run in JavaScriptCore, the engine in Safari, with modern JavaScript: let/const, arrow functions, template strings, classes, destructuring, Map/Set, regular expressions, Math, JSON, Date and Intl (dates, numbers and plural rules in any locale and time zone).
To keep shared widgets safe, scripts have no access to the outside world:
- no network (
fetch,XMLHttpRequest,WebSocket) - no files, no
requireorimport - no timers (
setTimeout,setInterval); useupdateEvery - no access to other widgets, the app, or your Mac
The only things Atsurae adds are console and the context passed to update.
Each run can take at most 0.25 seconds. A script that takes longer is stopped. That’s very generous: typical updates take well under a millisecond.
Logging
Section titled “Logging”console.log, console.info and console.warn print to the Problems & Console pane in Customize Widgets; console.error prints in red. Objects are printed as JSON:
console.log("battery:", context.battery);// battery: {"present":true,"level":0.82,"charging":false}The console keeps the last 200 lines per widget.
Errors
Section titled “Errors”If the script throws, takes too long, or doesn’t return an object, Atsurae stops running it and shows the error on the widget’s card and in Problems & Console:
Script error: TypeError: undefined is not an object (evaluating ‘context.wether.temperature’) (line 3)
The error stays until you save a change to the widget’s files, which starts the script fresh. See Errors and warnings for every message.
To avoid errors, guard values that can be null:
const temp = context.weather ? Math.round(context.weather.temperature) + "°" : "";Recipes
Section titled “Recipes”Time in another city:
const time = context.now.toLocaleTimeString("en-US", { timeZone: "Asia/Tokyo", hour: "2-digit", minute: "2-digit", hour12: false });Days until a date:
const target = new Date(2027, 0, 1); // months start at 0const today = new Date(context.now.getFullYear(), context.now.getMonth(), context.now.getDate());const days = Math.round((target - today) / 86400000);Pick something by day, the same on every Mac:
const day = Math.floor(context.now.getTime() / 86400000);const pick = items[day % items.length];Plurals:
const label = days === 1 ? "day" : "days";Numbers in the user’s language:
const formatted = new Intl.NumberFormat(undefined, { maximumFractionDigits: 1 }).format(value);Relative time:
const rtf = new Intl.RelativeTimeFormat(undefined, { numeric: "auto" });rtf.format(-1, "day"); // "yesterday"Examples
Section titled “Examples”- Greeting: text that depends on the time of day and an option
- Countdown: dates, options and error handling
- World Clock:
Intltime zones and multiple values - Quotes: rotating content
