@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

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, mergeScriptableBanner } from '@scriptables/manifest';

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

const banner = generateScriptableBanner(manifest);

// Update 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 [newBanner, updatedScript] = mergeScriptableBanner(script, manifest);

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',
});

extractScriptableManifest()

Extracts manifest settings from a script.

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

Example with error handling:

try {
  const manifest = extractScriptableManifest(script);
  console.log(manifest.iconColor); // 'red'
} catch (error) {
  console.error('Failed to extract manifest:', error);
}

mergeScriptableBanner()

Updates a script's manifest with new settings.

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

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

Types

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

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

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

Advanced Usage

Working with Share Sheet Inputs

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

const banner = generateScriptableBanner(manifest);

Merging Multiple Scripts

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

console.log('Old script');`;

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

console.log('New script');`;

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

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, script] = mergeScriptableBanner(sourceScript, {
    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