@scriptables/manifest NPM

@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);
}