A boilerplate for creating remote-updatable Scriptable widgets. Includes setup, components, utils and examples to develop in the comfort of TypeScript.
Makes creating iOS widgets with the Scriptable App even more fun!
Note: This is a work in progress
Scriptable TS Boilerplate Website →
This boilerplate consists of two separate packages widgets and scriptable-api.
Houses the dependencies, rollup config and code to write hot-loading widgets in TypeScript.
All created WidgetModules
are currently build to be loaded and bootstrapped by the WidgetLoader
.
A Nextjs project to serve the compiled WidgetModules
and WidgetLoader
. Also houses the demo website and can also be used to create custom data endpoints for the widgets.
The only way data is shared between the two is through the compilation process of widgets: this outputs compiled js files into a subdirectory of scriptable-api.
Start with creating a new widgetModule in ./widgets/code/widget-module
that complies to the following convention:
import { IWidgetModule } from "code/utils/interfaces";
const widgetModule: IWidgetModule = {
createWidget: async (params) => {
const widget = new ListWidget()
// await data
// do something with `params.widgetParameter`
// create the widget
return widget
}
}
module.exports = widgetModule;
Compile your widget by running either yarn build
or yarn watch
in ./widgets
(any file ending with WidgetModule.ts
will automatically be picked up).
Read the awesome official Scriptable Documentation.
Serve your widget by running yarn dev
in ./scriptable-api
.
Your compiled widget should now be available on YOUR_LOCAL_DNS_NAME:3000/compiled-widgets/widget-modules/camelCasedName.js
.
The demo page is also available on YOUR_LOCAL_DNS_NAME:3000
(without your widget, that requires some additional steps).
Paste a compiled WidgetLoader
(can be found in ./scriptable-api/public/compiled-widgets/widgetLoader.js
, or on the demo site) into Scriptable with the following argsConfig
and press play.
const argsConfig = {
fileName: "camelCasedNameEndingOnWidgetModule",
rootUrl: "http://macbook-pro.local:3000/compiled-widgets/widget-modules/",
defaultWidgetParameter: "",
downloadQueryString: "",
};
Note that the widgetParameter
is the default parameter to be sent into createWidget
, this parameter can be overruled by filling it into the setting of a widget.
With yarn watch
running in ./widgets
and yarn dev
running in ./scriptable-api
you'll now always run the latest code on your device:
yarn watch
compiles the .ts into a public .js widgetyarn dev
will serve this new version of the widget with a new ETagWidgetLoader
wil notice to ETag change on run and pull in the new version of the codeDeployment to Vercel is easiest for the Nextjs app:
scriptable-api
If people installed widgets with the WidgetLoader
pointing to your deployed instance, simply pushing code to the main
branch would already let them have the updated code again on next refresh of their device.