Scriptable TS Boilerplate

Scriptable TS Boilerplate is a boilerplate project for creating remote-updatable iOS widgets for the Scriptable app using TypeScript, Next.js, and Rollup.

What is Scriptable TS Boilerplate?

Scriptable TS Boilerplate is a two-package boilerplate that gives developers a TypeScript-based workflow for building widgets for the iOS Scriptable app. The input is a TypeScript widget module that exports an IWidgetModule with an async createWidget function; the output is a compiled JavaScript file served by a Next.js app, which a WidgetLoader script running inside Scriptable can fetch and execute. The project is publicly available on GitHub with 66 stars, is marked as a work in progress, and explicitly credits the Scriptable App, the universal-scriptable-widget project, and two example widgets for inspiration.

Key Features

• Hot-loading development — Run yarn watch in the widgets package to automatically compile any file ending with WidgetModule.ts into public .js files; the Next.js dev server serves them with fresh ETags so the WidgetLoader pulls updates on every run.
• TypeScript safety — Widget code is written inside IWidgetModule objects, keeping the guarantee of static types while still targeting Scriptable's ListWidget API.
• Two-package structure — The widgets package holds dependencies and Rollup config; the scriptable-api package is a Next.js app that serves the compiled artifacts, hosts a demo website, and can be extended to serve custom data endpoints.
• Remote update mechanism — After deploying the scriptable-api package, pushing new code to the main branch makes all widgets installed via the WidgetLoader update on their next refresh.
• Straightforward Vercel deployment — Deploy by cloning the repo, connecting GitHub to Vercel, and setting the project root to the scriptable-api subdirectory.
• Demo site included — The Next.js app includes a demo page at the root URL for previewing and testing compiled widgets.

Who is it for?

• iOS widget developers who prefer TypeScript over plain JavaScript and want a preconfigured Rollup build pipeline instead of writing their own.
• Developers who distribute widgets to others — the built-in WidgetLoader with ETag-based updating eliminates the need for users to manually install each new version.
• Developers building data-driven widgets — the scriptable-api Next.js app can serve custom JSON data endpoints that widget modules fetch via their async createWidget function.

What can you do with it?

• Create a new widget — Add a camelCasedNameEndingOnWidgetModule.ts file in ./widgets/code/widget-module, implement the createWidget method returning a ListWidget, and compile with yarn build or yarn watch.
• Develop locally with live updates — With yarn watch in widgets and yarn dev in scriptable-api, the WidgetLoader will pull the latest code whenever the ETag changes.
• Load the result on an iPhone — Copy the compiled widgetLoader.js from scriptable-api/public/compiled-widgets into Scriptable, set the argsConfig values (fileName, rootUrl, defaultWidgetParameter, downloadQueryString), and run it.
• Deploy and update remotely — Point Vercel at the scriptable-api directory, push to main, and all installed widgets will receive updates automatically.

How does it work?

The workflow has four steps: write a widget module in TypeScript, compile it with yarn build or yarn watch, serve it with the Next.js app, and run the WidgetLoader in Scriptable. The WidgetLoader checks the ETag of the compiled JavaScript file; when the served ETag differs from the cached one, it downloads the new file and executes it to render the widget.

Alternatives

• universal-scriptable-widget — A GitLab project cited in the credits that explored bootstrapping Scriptable widgets and inspired the bootstrapping idea for this boilerplate.

FAQ

How do I load a widget on my device?

Paste the compiled widgetLoader.js (available at scriptable-api/public/compiled-widgets/widgetLoader.js) into the Scriptable app, set argsConfig with values for fileName, rootUrl, defaultWidgetParameter, and downloadQueryString, then run the script.

How do I create a new widget?

Create a file in ./widgets/code/widget-module ending with WidgetModule.ts. Export an object that conforms to IWidgetModule and contains an async createWidget function returning a ListWidget. Run yarn build or yarn watch, and the file will be automatically compiled.

How do I update a widget that users already installed?

If the WidgetLoader on their device points to your deployed Vercel instance, simply push new code to the main branch. The WidgetLoader will detect the changed ETag and fetch the updated version on the next refresh.

What is the difference between the widgets and scriptable-api packages?

widgets is the development package containing TypeScript sources, Rollup configuration, and the compilation step. scriptable-api is the Next.js serving app that hosts compiled files, the demo website, and optional custom data endpoints.