{"id":13683329,"url":"https://github.com/jasperhartong/scriptable-ts-boilerplate","last_synced_at":"2025-04-30T13:30:39.087Z","repository":{"id":42488165,"uuid":"308977084","full_name":"jasperhartong/scriptable-ts-boilerplate","owner":"jasperhartong","description":"A boilerplate for creating remote-updatable Scriptable widgets. Includes setup, components, utils and examples to develop in the comfort of TypeScript.","archived":false,"fork":false,"pushed_at":"2022-11-16T11:52:09.000Z","size":8262,"stargazers_count":58,"open_issues_count":0,"forks_count":6,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-08-02T13:35:20.053Z","etag":null,"topics":["nextjs","rollup","scriptable-app","typescript"],"latest_commit_sha":null,"homepage":"https://scriptable-ts-boilerplate.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jasperhartong.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"license.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-10-31T21:43:56.000Z","updated_at":"2024-07-10T13:15:37.000Z","dependencies_parsed_at":"2023-01-21T15:48:07.416Z","dependency_job_id":null,"html_url":"https://github.com/jasperhartong/scriptable-ts-boilerplate","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jasperhartong%2Fscriptable-ts-boilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jasperhartong%2Fscriptable-ts-boilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jasperhartong%2Fscriptable-ts-boilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jasperhartong%2Fscriptable-ts-boilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jasperhartong","download_url":"https://codeload.github.com/jasperhartong/scriptable-ts-boilerplate/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224212125,"owners_count":17274363,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["nextjs","rollup","scriptable-app","typescript"],"created_at":"2024-08-02T13:02:07.739Z","updated_at":"2024-11-12T03:30:59.840Z","avatar_url":"https://github.com/jasperhartong.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# Scriptable TS Boilerplate\n\nMakes creating iOS widgets with the [Scriptable App](https://scriptable.app/) even more fun!\n\n- 🔥 Hot-loading widgets served by Next.js\n- 🔨 The safety of TypeScript\n- 🍭 Build, compile, rollup and other configs\n- 🚀 Deploy to Vercel with ease\n- ✨ Roll out updates to live widgets automatically\n\n_Note: This is a work in progress_\n\n**[Scriptable TS Boilerplate Website →](https://scriptable-ts-boilerplate.vercel.app)**\n\n## Project structure\n\nThis boilerplate consists of two separate packages **widgets** and **scriptable-api**. \n\n### Widgets\n\nHouses the dependencies, rollup config and code to write hot-loading widgets in TypeScript.\n\nAll created `WidgetModules` are currently build to be loaded and bootstrapped by the `WidgetLoader`.\n\n### Scriptable-api\n\nA 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.\n\n### Data exchange between projects\n\nThe 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**.\n\n\n# Local development\n\n## Writing and compiling a new widget\n\nStart with creating a new widgetModule in `./widgets/code/widget-module` that complies to the following convention:\n\n```js camelCasedNameEndingOnWidgetModule.ts\nimport { IWidgetModule } from \"code/utils/interfaces\";\n\nconst widgetModule: IWidgetModule = {\n    createWidget: async (params) =\u003e {\n        const widget = new ListWidget()\n        // await data\n        // do something with `params.widgetParameter`\n        // create the widget\n        return widget\n    }\n}\n\nmodule.exports = widgetModule;\n```\n\nCompile your widget by running either `yarn build` or `yarn watch` in `./widgets` (any file ending with `WidgetModule.ts` will automatically be picked up).\n\nRead the awesome [official Scriptable Documentation](https://docs.scriptable.app).\n\n## Serving the widget\n\nServe your widget by running `yarn dev` in `./scriptable-api`.\n\nYour compiled widget should now be available on `YOUR_LOCAL_DNS_NAME:3000/compiled-widgets/widget-modules/camelCasedName.js`.\n\nThe demo page is also available on `YOUR_LOCAL_DNS_NAME:3000` (without your widget, that requires some additional steps).\n\n## Loading the widget on your device for the first time\n\nPaste 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.\n```js\nconst argsConfig = {\n    fileName: \"camelCasedNameEndingOnWidgetModule\",\n    rootUrl: \"http://macbook-pro.local:3000/compiled-widgets/widget-modules/\",\n    defaultWidgetParameter: \"\",\n    downloadQueryString: \"\",\n};\n```\n\nNote 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.\n\n## Iterating the widget\n\nWith `yarn watch` running in `./widgets` and `yarn dev` running in `./scriptable-api` you'll now always run the latest code on your device:\n\n- `yarn watch` compiles the .ts into a public .js widget\n- `yarn dev` will serve this new version of the widget with a new ETag\n- the `WidgetLoader` wil notice to ETag change on run and pull in the new version of the code\n\n# Deployment\n\nDeployment to Vercel is easiest for the Nextjs app:\n\n- Clone this project\n- Link Github to Vercel and make the new project available to Vercel\n- During setup pick the subdirectory `scriptable-api`\n- Done!\n\n## Updating widgets\n\nIf 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.\n\n\n# Credits\n\n- The [Scriptable App](https://scriptable.app/) of course\n- The idea of bootstrapping widgets: https://gitlab.com/sillium-scriptable-projects/universal-scriptable-widget\n- The Sticky example https://github.com/drewkerr/scriptable/blob/main/Sticky%20widget.js\n- The Covid19 example: https://gist.github.com/planecore/e7b4c1e5db2dd28b1a023860e831355e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjasperhartong%2Fscriptable-ts-boilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjasperhartong%2Fscriptable-ts-boilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjasperhartong%2Fscriptable-ts-boilerplate/lists"}