@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

npm install @scriptables/manifest

# or
yarn add @scriptables/manifest

# or
pnpm add @scriptables/manifest

# or
bun add @scriptables/manifest

Quick Start

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

// Generate a new manifest banner
const manifest = {
  name: 'my-widget',
  iconColor: 'blue',
  iconGlyph: 'star',
  alwaysRunInApp: true,
};

const banner = generateScriptableBanner(manifest);

// Parse an existing script's manifest
const script = `// Variables used by Scriptable.
// These must be at the very top of the file. Do not edit.
// icon-color: red;

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

const {manifest: parsedManifest, content} = parseScriptableManifest(script);
console.log(parsedManifest); // { iconColor: 'red' }

// Update an existing script's manifest
const {banner: newBanner, content: updatedScript} = mergeScriptableBanner(script, {
  iconColor: 'blue',
  iconGlyph: 'star',
});

API Reference

Core Functions

generateScriptableBanner()

Generates a new manifest banner.

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

Example:

const banner = generateScriptableBanner({
  iconColor: 'red',
  iconGlyph: 'star',
});

parseScriptableManifest()

Parses a script to extract its manifest settings and content.

function parseScriptableManifest(script: string): {
  manifest: Partial<ScriptableManifest> | null;
  rawHeader: string;
  content: string;
};

Example:

const {manifest, content} = parseScriptableManifest(script);
console.log(manifest.iconColor); // 'red'

mergeScriptableBanner()

Updates a script's manifest with new settings.

function mergeScriptableBanner(
  script: string,
  manifestOrOldScript?: Partial<ScriptableManifest> | string,
): {
  banner: string;
  content: string;
};

Example:

const {banner, content} = mergeScriptableBanner(script, {
  iconColor: 'blue',
  iconGlyph: 'star',
});

Helper Functions

• hasBannerManifest(script: string): Checks if a script has a manifest banner
• isStaticBanner(line: string): Checks if a line is part of the static banner
• isManifestBanner(line: string): Checks if a line contains manifest settings
• isScriptableBanner(line: string): Checks if a line is part of any banner type
• normalizeManifest(manifest: object): Normalizes manifest keys to camelCase format

Types

interface ScriptableManifest {
  name?: string;
  alwaysRunInApp?: boolean;
  shareSheetInputs?: ScriptableShareSheetInputs;
  iconColor?: string;
  iconGlyph?: string;
}

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

Advanced Usage

Working with Share Sheet Inputs

const manifest = {
  name: 'file-processor',
  shareSheetInputs: ['file-url', 'images'],
  alwaysRunInApp: true,
};

const banner = generateScriptableBanner(manifest);

Handling Different Key Formats

The library supports different key formats for manifest properties:

// All these are equivalent
const manifest1 = {iconColor: 'red'};
const manifest2 = {'icon-color': 'red'};
const manifest3 = {icon_color: 'red'};

Error Handling

The library throws errors in these cases:

• Invalid manifest format
• Missing required properties
• Invalid share sheet input types

Example with error handling:

try {
  const {banner, content} = mergeScriptableBanner(script, {
    shareSheetInputs: ['invalid-type'], // This will throw an error
  });
} catch (error) {
  console.error('Failed to merge manifest:', error);
}

Contributing

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

Credits

This project draws inspiration from rollup-plugin-scriptable.

License

Apache-2.0