Skip to content
AtsuraeDownload

Development sign-in

Only on a local server with DEV_AUTH. Enter any account name.

Editors and tools

Any editor that saves plain text works. Atsurae reloads your widget every time the file is saved, wherever it was saved from.

VS Code is free and checks widget.json files against the Atsurae JSON Schema out of the box. You get:

  • Autocomplete for every field, with descriptions, as you type
  • Allowed values, e.g. weight suggests ultraLight … black
  • Red squiggles under mistakes, like a misspelled field, an ID with capital letters, or an image without a size
  • Hover help on any field

All it needs is the $schema line at the top of the file, which New Widget… adds for you:

{
"$schema": "https://atsurae.app/docs/schema/widget.schema.json",
"formatVersion": 2,
...
}

Open the widget’s folder in VS Code (File ▸ Open Folder…, or drag the .atsuraewidget folder onto VS Code’s icon). The JavaScript file gets syntax highlighting and basic checks too.

  • Zed, Sublime Text, Nova, BBEdit, JetBrains editors: all support $schema in JSON files, or do with a JSON plugin.
  • TextEdit: works, but first choose Format ▸ Make Plain Text and turn off Edit ▸ Substitutions ▸ Smart Quotes. Curly quotes (“ ”) break JSON.
  • Xcode: opens JSON and JavaScript files fine, but has no schema support.
  • In Atsurae: Library ▸ Widgets ▸ Add ▸ Show Widgets Folder, or Settings ▸ Widgets ▸ Show Folder
  • In Finder: press ⇧⌘G and paste ~/Library/Application Support/Atsurae/Widgets
  • In Terminal: open ~/Library/Application\ Support/Atsurae/Widgets

To show a package’s files in Finder, right-click it and choose Show Package Contents, or open it in your editor directly. In the Library, right-click a widget and choose Show in Finder.

The schema works with any JSON Schema validator. For example, with Node.js:

Terminal window
npx ajv-cli validate --spec=draft2020 -s widget.schema.json -d widget.json

(Download the schema from /docs/schema/widget.schema.json first.) Atsurae also checks things a schema can’t, like whether your images and fonts exist, so the final word is the Problems & Console pane. See Testing and debugging.

Widget scripts run in JavaScriptCore, the same engine as Safari. To try an expression, use Safari’s JavaScript console (Develop ▸ Show JavaScript Console) or Terminal:

Terminal window
osascript -l JavaScript -e 'new Date().toLocaleTimeString("en-US", { timeZone: "Asia/Tokyo" })'

Or just console.log from your widget’s script and watch the Problems & Console pane.