Scriptable

Welcome to my Scriptable repository!

You'll discover a curated collection of scripts and widgets designed to enhance your iOS and MacOS experience. Whether you're looking to streamline your daily tasks, fetch specific data, or add a personal touch to your device, this repository serves as a treasure trove of Scriptable solutions.

Get started by downloading the Scriptable app, follow the simple setup instructions, and explore the array of scripts available to transform your interaction with your device. Whether you're a seasoned programmer or a curious newbie, this repository offers the tools and guidance to unlock the full potential of Scriptable.

Getting started

1. Download Scriptable for iOS / MacOS from the App Store.
2. Install ScriptDude using the instructions on their website (this is how we easily install and update our scripts).
3. Install a Script from the list below!

Scripts

Script	Description	Install
Redirect Me	Redirect a URL from the Share Sheet to another location.
Prayer Time	See the upcoming Islamic prayer times for the day.
Days Until	Display a countdown to a specific date.
Cantonese Romanisation	Transform Chinese into Cantonese romanisation.

Contents

• Scriptable
  • Getting started
  • Scripts
  • Developing
    • Setting up environment
    • Repository navigation
    • Compiling from TypeScript to JavaScript
    • Export script to Scriptable (iCloud directory)
    • npm
      • Init
      • Export
      • Export module
      • Build
      • Build and watch
      • Open
    • VSCode tasks
    • Notes
  • Related projects
  • Thanks

Developing

Setting up environment

How to start developing scriptable apps with VSCode:

1. Download Scriptable for MacOS
2. Enable iCloud sync for Scriptable
3. Download VSCode
4. Clone this repository: git clone https://github.com/Elliott-Liu/scriptable
5. Open VSCode in the repo: code .
6. Run command to initialize a build folder symlink to the iCloud Scriptable folder: npm run init
7. Install npm dependencies npm install --include=dev

Repository navigation

path	description	comments
./src	source code	.ts and readme.md files
./dist	production code	.js Scriptable files
./scripts	development scripts	additional scripts for compiling .ts to .js
./build	symbolic link to iCloud Scriptable folder	initialised with npm run init, excluded from git comm

Compiling from TypeScript to JavaScript

1. Open a TypeScript file in VSCode.
2. Run a task - I'd recommend: Build, link, and open current script (this will build the file to the dist folder, symlink it to the build folder and open it in Scriptable)

Export script to Scriptable (iCloud directory)

For scripts use:

npm run export

For modules use:

npm run export_module

npm

The following commands are for the symbolic linking of files:

Init

npm run init

Export

npm run export

Export module

npm run export_module

These commands are for compiling from TypeScript to JavaScript and running the script in Scriptable. Each should be followed by an argument, either:

• the name of the script (surrounded in quotation marks if it contains spaces): e.g. "Hello World" or Hello_World
• the relative path of the script with file extension (surrounded in quotation marks if it contains spaces): e.g. "./src/Hello World/Hello World.ts" or ./src/Hello_World/Hello_World.ts

Build

npm run build

Build and watch

npm run build-watch

Open

npm run open

VSCode tasks

These are defined in the .vscode/tasks.json, they allow you to run a command directly from the current script you're working on.

The default shortcut to run tasks is ⌘ + SHIFT + B.

The tasks are relatively self-explanatory and simply pass in the required arguments for the npm commands:

• Open current script in Scriptable
• Build current script
• Build and watch current script
• Build, export, and open current script

Notes

When developing in this environment, there are a few things to keep in mind:

• When compiling from TypeScript using the npm run build or npm run build-watch, the resulting JavaScript file will be placed in the dist folder with the same name (with .js as the file extension).

  Ensure that you actually intend to overwrite any existing files in here before running, or/and ensure that files are already backed up to git before running this command.

Related projects

• https://github.com/schl3ck/ios-scriptable-types

  Scriptable Typescript type definitions

• https://github.com/jsloat/scriptable-utils

  Scriptable utilities to make building interactive elements easier

• https://github.com/gebeto/scriptable-vscode

  VSCode plugin that should replace scriptable.sh when it's finished (work in progress).

Thanks

• gebeto for the starting environment: scriptable (scriptable development environment)
• jsloat for TypeScript development environment: scriptable-utils
• schl3ck for Scriptable types definition: ios-scriptable-types