@scriptables/manifest

@scriptables/manifest

Utilities to generate, parse, and update manifest headers in Scriptable scripts.

Overview

Scriptable scripts can include special manifest comments at the top of the file that configure various script behaviors and appearance settings. This library makes it easy to work with these manifests programmatically.

Example manifest:

// Variables used by Scriptable.
// These must be at the very top of the file. Do not edit.
// icon-color: blue; icon-glyph: circle; always-run-in-app: true; share-sheet-inputs: file-url, url;

Installation

Choose your preferred package manager:

# npm
npm install @scriptables/manifest

# yarn
yarn add @scriptables/manifest

# pnpm
pnpm add @scriptables/manifest

# bun
bun add @scriptables/manifest

API

Functions

generateScriptableBanner(manifest?: ScriptableManifest, noDefaults = false): string

Generates a complete Scriptable manifest banner with the specified settings.

const manifest = {
  name: 'weather-widget',
  iconColor: 'red',
  iconGlyph: 'square',
  alwaysRunInApp: true,
  shareSheetInputs: ['file-url', 'url'],
};

const banner = generateScriptableBanner(manifest);

extractScriptableManifest(script: string, attrs?: ScriptableBannerManifestKeys[]): Partial<ScriptableManifest>

Extracts manifest settings from a script's content.

const script = `// Variables used by Scriptable.
// These must be at the very top of the file. Do not edit.
// icon-color: red; icon-glyph: square;

console.log('Hello world');`;

const manifest = extractScriptableManifest(script);
// Result: { iconColor: 'red', iconGlyph: 'square' }

mergeScriptableBanner(script: string, manifestOrOldScript?: Partial<ScriptableManifest> | string): [string, string]

Updates an existing script's manifest with new settings. Returns a tuple of [banner, mergedScript].

const [banner, mergedScript] = mergeScriptableBanner(script, {
  iconColor: 'blue',
  iconGlyph: 'circle',
});

Helper Functions

• hasBannerManifest(script: string): boolean - Checks if a script has a manifest banner
• isStaticBanner(line: string): boolean - Checks if a line is part of the static banner
• isManifestBanner(line: string): boolean - Checks if a line contains manifest settings
• isScriptableBanner(line: string): boolean - Checks if a line is part of any banner type

Types

interface ScriptableManifest {
  /**
   * Script name, used for file naming by build plugins
   * Not included in the banner
   */
  name?: string;

  /**
   * Whether the script should always run in the app
   */
  alwaysRunInApp?: boolean;

  /**
   * Types of inputs the script accepts from the share sheet
   */
  shareSheetInputs?: Array<'file-url' | 'url' | 'plain-text' | 'images'>;

  /**
   * Script icon color in the app
   */
  iconColor?: string;

  /**
   * Script icon glyph in the app
   */
  iconGlyph?: string;
}

type ScriptableShareSheetInputs = Array<'file-url' | 'url' | 'plain-text' | 'images'>;

enum ScriptableBannerManifestKeys {
  'always-run-in-app',
  'share-sheet-inputs',
  'icon-color',
  'icon-glyph',
}

Usage Examples

Basic Usage

import {generateScriptableBanner, mergeScriptableBanner} from '@scriptables/manifest';

// Generate a new banner
const manifest = {
  name: 'weather-widget',
  iconColor: 'red',
  iconGlyph: 'square',
};
const banner = generateScriptableBanner(manifest);

// Update existing script
const script = `// Variables used by Scriptable.
// These must be at the very top of the file. Do not edit.
// icon-color: blue; icon-glyph: circle;

console.log('Hello world');`;

const [newBanner, mergedScript] = mergeScriptableBanner(script, manifest);

Extract and Modify Manifest

import {extractScriptableManifest, mergeScriptableBanner} from '@scriptables/manifest';

// Extract existing manifest
const script = `// Variables used by Scriptable.
// These must be at the very top of the file. Do not edit.
// icon-color: blue; icon-glyph: circle;

console.log('Hello world');`;

const manifest = extractScriptableManifest(script);

// Modify manifest
manifest.iconColor = 'red';
manifest.name = 'my-widget';

// Update script with modified manifest
const [newBanner, mergedScript] = mergeScriptableBanner(script, manifest);

Merge with old script

import {mergeScriptableBanner} from '@scriptables/manifest';

const oldScript = `// Variables used by Scriptable.
// These must be at the very top of the file. Do not edit.
// icon-color: blue; icon-glyph: circle;

console.log('Hello world');`;

const newScript = `// Variables used by Scriptable.
// These must be at the very top of the file. Do not edit.
// icon-color: red; icon-glyph: square;

console.log('Hello world');`;

const [newBanner, mergedScript] = mergeScriptableBanner(newScript, oldScript);

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Credits

This project draws inspiration and references code from:

• rollup-plugin-scriptable

Special thanks to jag-k for their contributions to the Scriptable community.

License

Apache-2.0