esbuild-plugin-scriptable

An ESBuild plugin for developing Scriptable iOS app scripts with modern JavaScript tooling.

Requirements

• Node.js 14 or later
• esbuild 0.24 or later
• Scriptable iOS app with iCloud Drive sync enabled

Features

• Automatically adds Scriptable metadata banner to output files
• Supports manifest files for script configuration
• Uses manifest name as output filename (if specified)
• Handles deployment to iCloud Drive with auto-detection
• Full TypeScript support with type definitions
• File filtering with glob pattern matching
• Custom manifest path mapping
• Configurable warning behaviors
• Continues building even when deployment fails (configurable)
• Detailed deployment logging options

Installation

1npm install esbuild-plugin-scriptable --save-dev

1pnpm add esbuild-plugin-scriptable --save-dev

1yarn add esbuild-plugin-scriptable --dev

Basic Usage

1import {build} from 'esbuild';
2import {scriptableBanner, scriptableDeploy} from 'esbuild-plugin-scriptable';
3
4await build({
5  entryPoints: ['src/widget.ts'],
6  outfile: 'dist/widget.js',
7  bundle: true,
8  plugins: [
9    scriptableBanner({
10      warnOnMissingManifest: true,
11      patterns: '**/*.widget.ts',
12    }),
13    scriptableDeploy({
14      logLevel: 'verbose',
15      patterns: '**/*.widget.ts',
16    }),
17  ],
18});

Configuration

Banner Plugin Options

• manifestExtensions: Custom manifest file extensions (default: ['.manifest.json', '.manifest', '.json'])
• warnOnMissingManifest: Show warning when manifest file is missing (default: true)
• warnOnInvalidManifest: Show warning when manifest file is invalid (default: true)
• warnOnMissingEntry: Show warning when no matching entry point is found (default: true)
• getManifestPath: Custom manifest file path mapping function
• patterns: Source file patterns to match entry points (default: ['**/*.{ts,tsx,js,jsx}'])
  • Can be a string or array of strings
  • Supports glob patterns with negation (! prefix)
  • Examples:
    • '**/*.widget.ts' - only process widget source files
    • ['**/*.ts', '!**/*.test.ts'] - exclude test files
• logLevel: Control logging detail (default: 'auto')
  • 'auto': Use esbuild's logLevel
  • 'silent': No logs
  • 'error': Only errors
  • 'warn': Errors and warnings
  • 'info': Normal output
  • 'verbose': Detailed output

Deploy Plugin Options

• logLevel: Control deployment logging detail (default: 'normal')
  • 'silent': No logs
  • 'normal': Basic deployment info
  • 'verbose': Detailed deployment info
  • 'debug': All deployment details
• continueOnError: Continue building when deployment fails (default: true)
• scriptableDir: Custom Scriptable directory path (default: auto-detect in iCloud Drive)
• patterns: Source file patterns to match entry points (default: ['**/*.{ts,tsx,js,jsx}'])
  • Can be a string or array of strings
  • Supports glob patterns with negation (! prefix)
  • Examples:
    • '**/*.widget.ts' - only deploy widget source files
    • ['**/*.ts', '!**/*.test.ts'] - exclude test files
• addBanner: Whether to add Scriptable banner from manifest (default: true)
• manifestExtensions: Custom manifest file extensions (default: ['.manifest.json', '.manifest', '.json'])

Manifest Configuration

The manifest file can be used to configure both the script metadata and the output filename:

1{
2  "name": "weather-widget",
3  "alwaysRunInApp": true,
4  "shareSheetInputs": ["file-url", "url"],
5  "iconColor": "blue",
6  "iconGlyph": "cloud",
7  "version": "1.0.0",
8  "description": "A weather widget for Scriptable"
9}

When a manifest includes a name property:

• The deploy plugin will use this name for the output file (e.g., weather-widget.js)
• If no name is specified, the original filename will be used
• The banner plugin will still use all manifest properties to generate the script metadata

Advanced Usage

1import {build} from 'esbuild';
2import {scriptableBanner, scriptableDeploy} from 'esbuild-plugin-scriptable';
3
4await build({
5  entryPoints: ['src/widget.ts'],
6  outfile: 'dist/widget.js',
7  bundle: true,
8  plugins: [
9    scriptableBanner({
10      warnOnMissingManifest: true,
11      patterns: ['**/*.ts', '!**/*.test.ts'],
12      getManifestPath: entryPath => {
13        return entryPath.replace(/\.ts$/, '.manifest.json');
14      },
15    }),
16    scriptableDeploy({
17      logLevel: 'verbose',
18      addBanner: true,
19      patterns: ['**/*.ts', '!**/*.test.ts'],
20      scriptableDir: '/custom/path/to/Scriptable',
21    }),
22  ],
23});

Banner Behavior

The banner can be added in two stages:

1. Build stage (via scriptableBanner plugin):

   • Adds banner to the build output files
   • Banner is part of the compiled result

2. Deploy stage (via scriptableDeploy plugin's addBanner option):

   • Does not affect build output files
   • Only adds banner to the deployed files in Scriptable directory
   • Will update/override any existing banner in the target file

When using both plugins:

• scriptableBanner will add banner to build output
• scriptableDeploy with addBanner: true will update/override the banner in deployed files
• scriptableDeploy with addBanner: false will keep the existing banner (if any)

1// Example 1: Banner in both build output and deployed files
2plugins: [
3  scriptableBanner({...}),  // Adds banner to build output
4  scriptableDeploy({
5    addBanner: true   // Updates banner in deployed files
6  })
7]
8
9// Example 2: Banner only in deployed files
10plugins: [
11  scriptableDeploy({
12    addBanner: true   // Adds banner only to deployed files
13  })
14]
15
16// Example 3: Banner only in build output
17plugins: [
18  scriptableBanner({...}),  // Adds banner to build output
19  scriptableDeploy({
20    addBanner: false  // Keeps existing banner in deployed files
21  })
22]

The addBanner option in scriptableDeploy:

• Only affects the files in Scriptable directory
• Does not modify the build output files
• When true, will ensure the latest banner from manifest is used in deployed files
• When false, will preserve any existing banner in the files

License

Apache-2.0