Website: https://xnu.app/scriptwidget/

✨ Build iPhone, iPad, and Mac widgets in ScriptWidget Studio—without writing Swift.

ScriptWidget is an open-source widget development platform for building native WidgetKit experiences with JavaScript and JSX-like syntax. Write once, preview on Mac, and run the same package on iPhone, iPad, and Mac—without requiring Swift for widget authoring.

It combines a JavaScriptCore runtime, native SwiftUI rendering, a desktop development environment, secure package sharing, AI-assisted generation, and a GitHub-backed community catalog.

Studio is the primary place to build widgets:

• project file tree with multiple JavaScript/JSON files and package resources;
• CodeMirror 6 editing, schema completions, diagnostics, formatting, autosave, and crash recovery;
• live preview for one or every supported widget family, plus runtime console and timing information;
• Config panel for widget.json, families, permissions, network domains, plugins, and preview parameters;
• AI generation with provider profiles, iterative run/diagnose/refine, and reusable Skills;
• verified Widget & Skills Gallery and a Data Source Lab for testing plugin operations.

The first-launch guide can create a complete tutorial widget and walk a new user from editing through adding it to the desktop in about five minutes.

# Clone the repository
git clone https://github.com/everettjf/ScriptWidget.git
cd ScriptWidget

# iOS app + widget + share extension
open iOS/ScriptWidget.xcodeproj

# macOS app + widget
open macOS/ScriptWidgetMac.xcodeproj

1. Select a scheme (ScriptWidget / ScriptWidgetWidget for iOS, ScriptWidgetMac for macOS)
2. Enable the iCloud.ScriptWidget container and group.everettjf.scriptwidget app group so script storage works
3. Press Cmd + R to build and run
4. Browse the bundled example scripts under Shared/ScriptWidgetRuntime/Resource/Script.bundle/ (api/, component/, template/)

ScriptWidget/
├── Shared/
│   └── ScriptWidgetRuntime/   # Core runtime: JavaScriptCore host, JSX→SwiftUI
│       ├── AI/                # Provider settings, agent loop, evals, Skills
│       ├── Common/            # Script storage, Package 2.0, cache & imports
│       ├── Gallery/           # Verified GitHub catalog, cache & installer
│       ├── Plugin/            # Declarative Data Source Plugin runtime
│       ├── Widget/Runtime/    # JS engine setup, Babel transform, execution
│       ├── Widget/API/        # JS APIs ($device, $file, $storage, ...)
│       ├── Widget/Component/  # Element → SwiftUI view mapping
│       └── Resource/          # Babel bundle + bundled example scripts
├── iOS/
│   ├── ScriptWidget/          # iOS app (editor, settings)
│   ├── ScriptWidgetWidget/    # Widget, Live Activity, Control Widget
│   └── ScriptWidgetShare/     # Share extension
├── macOS/
│   ├── ScriptWidgetMac/       # macOS app
│   └── ScriptWidgetMacWidget/ # macOS widget
├── Editor/editorfe/           # Vite + CodeMirror 6 editor frontend
├── Gallery/                   # Curated Widget & Skills Gallery index
├── Tests/                     # Shared runtime, execution, cache & security tests
├── docs/                      # User, API, package, Skills & release documentation
├── Resource/                  # Marketing assets, screenshots
└── README.md

A script's entry point is the $render(...) call, which takes a JSX tree built from runtime tags (vstack, hstack, zstack, text, image, gauge, chart, ...).

$render(
  <vstack frame="max">
    <text font="title">Hello, ScriptWidget! 👋</text>
  </vstack>
);

const result = await fetch("https://jsonplaceholder.typicode.com/todos/1");
const model = JSON.parse(result);

$render(
  <vstack>
    <text font="title">{model.title}</text>
  </vstack>
);

Package 2.0 widgets using network access must declare the network permission and matching hosts in widget.json.

const weather = await $dataSource.request(
  "app.scriptwidget.datasource.open-meteo",
  "forecast",
  { latitude: "37.7749", longitude: "-122.4194" }
);

$render(
  <vstack frame="max" padding="16">
    <text font="caption">San Francisco</text>
    <text font="largeTitle">{weather.current.temperature_2m}°</text>
  </vstack>
);

The package must declare the plugin identifier, network permission, and the plugin host. Plugins are declarative HTTPS request mappings—not executable native extensions.

$storage.setString("greeting", "Hello ScriptWidget");
const greeting = $storage.getString("greeting");

$render(
  <vstack frame="max" background="#0f172a">
    <text font="caption" color="#94a3b8">Storage</text>
    <text font="title3" color="#e2e8f0">{greeting}</text>
  </vstack>
);

• Xcode 27+ for the current development branch
• macOS 26+ for ScriptWidget Studio
• iOS 16+ (for iOS widgets)

# Clone and setup
git clone https://github.com/everettjf/ScriptWidget.git
cd ScriptWidget

# Open in Xcode (pick the platform you want)
open iOS/ScriptWidget.xcodeproj      # iOS
open macOS/ScriptWidgetMac.xcodeproj # macOS

# Build and run (Cmd + R)

The editor frontend (React + CodeMirror) lives in Editor/editorfe:

cd Editor/editorfe
npm install
npm start   # dev server at http://localhost:3000
npm test
npm run build
npm run release # rebuild and copy StudioEditor.bundle into both apps

Run the same repository gates used by CI:

./Scripts/release-readiness.sh
./Scripts/ipad-icloud-tests.sh

1. Open ScriptWidget Studio on Mac (or ScriptWidget on iPhone/iPad) and create a script from a template, AI prompt, or blank project
2. Write your widget in main.jsx and call $render(...) with a JSX tree
3. Use the live preview to iterate, then add the widget from the Home Screen

Each widget is stored under Scripts/<PackageName>/ and synced through iCloud/app-group storage. New projects use Package 2.0:

My Widget/
├── widget.json
├── main.jsx
├── lib/
│   └── format.js
└── image/
    └── background.png

widget.json is the authoritative, versioned manifest. It declares the entry point, supported families, permissions, allowed network hosts, and Data Source Plugins. Legacy main.jsx/meta.json packages remain readable and migrate during supported import/export flows.

Start with the documentation hub or build your first widget in ScriptWidget Studio.

• Entry point - call $render(<tree/>) to draw the widget
• Components - vstack, hstack, zstack, text, image, gauge, chart, shapes, ...
• Styling - element attributes such as font, color, background, frame, padding
• Widget sizes - read $getenv("widget-size") (small / medium / large / accessory…)
• Interactions - buttons and links via App Intents

The native JSX component switch is the runtime authority. Studio keeps static completion metadata in scriptWidgetAPI.js, checks it against the native switch, and generates the Runtime API reference from it.

Widget packages, Gallery content, Skills, and Data Source Plugins are treated as untrusted input:

• Package 2.0 rejects unknown fields and unsupported versions.
• Archive imports reject traversal, absolute paths, symlinks, encrypted entries, case collisions, malformed ZIP metadata, and oversized payloads.
• Package file access remains package-relative; storage is package-namespaced and bounded.
• Package 2.0 networking requires explicit permission and a matching host declaration; generic fetches are limited to public HTTP(S), while Data Source Plugins require HTTPS. Private/local hosts and oversized responses are rejected.
• Gallery files are restricted to the curated GitHub trust root and verified by exact byte count and SHA-256 before installation.
• Skills are prompt-only and cannot execute code, access secrets, or grant runtime permissions.
• Data Source Plugins are declarative request mappings and cannot load arbitrary native code.

See Package 2.0, modern WidgetKit features, Skills 1.0, Gallery, and Data Source Plugins for the complete contracts.

Contributions are welcome! Please read our Contributing Guide for details.

• 🐛 Report bugs
• 💡 Suggest features
• 🔧 Submit pull requests
• 📝 Write documentation
• 🎨 Share your widgets
• 🧠 Share focused AI Skills

See the public roadmap, governance model, and Gallery submission guide. Every pull request runs the same release-readiness checks used locally.

The source code in this repository is released under the MIT License.

The ScriptWidget name, logos, screenshots, and App Store marketing materials are not licensed under the MIT License. All rights to those brand and marketing assets are reserved by their respective owners.

Built with:

• JavaScriptCore - Apple's JavaScript engine
• SwiftUI - Modern UI framework
• Xcode Gen - Project generation

Inspired by:

• React - Component-based UI
• React Native - Mobile development
• WidgetKit - Apple's widget framework