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.
Visual Studio Code (recommended)
Section titled “Visual Studio Code (recommended)”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.
weightsuggestsultraLight…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.
Other editors
Section titled “Other editors”- Zed, Sublime Text, Nova, BBEdit, JetBrains editors: all support
$schemain 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.
Opening the widgets folder
Section titled “Opening the widgets folder”- 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.
Checking a file without Atsurae
Section titled “Checking a file without Atsurae”The schema works with any JSON Schema validator. For example, with Node.js:
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.
Trying JavaScript quickly
Section titled “Trying JavaScript quickly”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:
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.
