@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:

``js
// 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

`bash
npm install @scriptables/manifest

or

yarn add @scriptables/manifest

or

pnpm add @scriptables/manifest

or

bun add @scriptables/manifest
`

Quick Start

`typescript
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

$3

#### generateScriptableBanner()

Generates a new manifest banner.

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

Example:

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

#### parseScriptableManifest()

Parses a script to extract its manifest settings and content.

`typescript
function parseScriptableManifest(script: string): {
manifest: Partial | null;
rawHeader: string;
content: string;
};
`

Example:

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

#### mergeScriptableBanner()

Updates a script's manifest with new settings.

`typescript
function mergeScriptableBanner(
script: string,
manifestOrOldScript?: Partial | string,
): {
banner: string;
content: string;
};
`

Example:

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

$3

- 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

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

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

Advanced Usage

$3

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

const banner = generateScriptableBanner(manifest);
`

$3

The library supports different key formats for manifest properties:

`typescript
// 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:

`typescript
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