Skip to content
AtsuraeDownload

Development sign-in

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

Packages

A widget is either a single .json file or a package: a folder whose name ends in .atsuraewidget.

A widget that only uses text, shapes and progress bars can be one file:

~/Library/Application Support/Atsurae/Widgets/
└── Big Clock.json

The file name doesn’t matter; the id and name inside do.

A widget with a script, images or fonts must be a package:

World Clock.atsuraewidget/
├── widget.json required
├── script.js if "script" is set
├── images/ images used by "src"
│ └── globe.svg
├── fonts/ .ttf or .otf files, available by family name
│ └── Inter-Regular.ttf
└── LICENSE.txt licenses for fonts and images you include
  • widget.json must be at the top of the folder, with exactly that name.
  • The folder can have any name ending in .atsuraewidget. Finder shows the extension like a file type.
  • images and fonts are conventions for images, and a requirement for fonts: Atsurae loads fonts only from fonts/.
  • Anything else in the folder (licenses, a README, source files for your images) is ignored by Atsurae but kept when you share the widget.

Even a widget that doesn’t need a package can be one; the examples on this site all are.

  1. Make a folder called My Widget.atsuraewidget.
  2. Move your .json file into it and rename it to widget.json.
~/Library/Application Support/Atsurae/Widgets/
├── Big Clock.json
├── World Clock.atsuraewidget/
└── Community/ widgets you got from Discover (managed by Atsurae)

Atsurae loads every .json file and .atsuraewidget folder at the top of this folder. Subfolders that aren’t packages are ignored, except Community, which holds widgets downloaded from the community. Don’t edit those; changes are lost when the widget is reinstalled. Copy one out to the main folder to make your own version, and give it a new id.

Any of these work:

  • Drag a .atsuraewidget folder, a .json file or a .zip onto the Widgets section of your Library.
  • Library ▸ Widgets ▸ Add ▸ Import Widget… and choose one.
  • Copy it into the widgets folder yourself.

Imported widgets are copied into the widgets folder (zips are unpacked first) and turned on. If the name is taken, Atsurae adds a number.

Right-click its card in the Library and choose Move to Trash, or delete it from the widgets folder. Atsurae keeps the widget’s position and settings, so putting it back restores them.

To send a widget to a friend, zip the package (right-click ▸ Compress) and send the zip. They drop it on their Library. To share with everyone, publish it to the community.

The id is how Atsurae tells widgets apart. It must be unique among all your widgets, using lowercase letters, numbers and dashes:

"id": "world-clock"
  • Two widgets with the same id can’t both load; the second one shows an error.
  • A user widget can’t use a built-in’s ID (day, date, time, now-playing, system, custom-text).
  • Placement, size, color and option values are stored by id. Keep it the same across versions of your widget, and pick something distinctive (sam-world-clock) if you plan to share it.