OpenScript

A lightweight, modern user script manager built for Chrome Manifest V3 using the native chrome.userScripts API.

---

⚡ Prerequisites

To run user scripts in Chrome MV3:

1. Open chrome://extensions in your browser.
2. Click Details on the OpenScript extension card.
3. Enable the "Allow User Scripts" toggle.

---

📖 Writing Scripts Tutorial

OpenScript uses standard Tampermonkey-compatible metadata headers with built-in secret injection.

1. The Metadata Block

Every user script begins with a // ==UserScript== block that tells OpenScript when and where to run:

// ==UserScript==
// @name         GitHub Notification Cleaner
// @version      1.0.0
// @description  Hides read notifications automatically
// @author       YourName
// @match        https://github.com/*
// @run-at       document_idle
// @grant        none
// ==/UserScript==

(function() {
  'use strict';
  console.log('OpenScript running on GitHub!');
})();

Supported Header Directives

Directive	Description	Example
@name	Script title shown in OpenScript popup list	@name My Custom Tool
@version	Version badge displayed in popup list	@version 1.2.0
@description	Summary shown under the script title	@description Auto-clicks accept buttons
@author	Author metadata	@author Alice
@match / @include	URL patterns where script runs (supports multiple)	@match https://*.example.com/*
@run-at	Injection timing: document_idle (default), document_start, document_end	@run-at document_start
@grant	Compatibility header (e.g. none)	@grant none

Note on @match normalization: OpenScript automatically normalizes bare URLs (e.g., github.com/* becomes *://github.com/* and https://github.com becomes https://github.com/*).

---

2. Execution Timing (@run-at)

Control when your script executes relative to page lifecycle:

• document_idle (Default): Runs after the page DOM is fully built and subresources have finished loading. Best for DOM manipulation and button clicks.
• document_start: Runs before any DOM elements are constructed or external page scripts execute. Best for early theme injection, ad/tracker blockers, or prototype overrides.
• document_end: Runs right as the DOM content is parsed (DOMContentLoaded), before images and stylesheets finish loading.

(Both hyphenated document-idle and underscore document_idle formats are supported).

---

3. Using Synced Secrets & Environment Variables

OpenScript allows you to store sensitive API tokens or passwords in the Secrets tab. Secrets are synced across your devices via chrome.storage.sync and injected into every active user script.

Accessing Secrets in Code

You can read secrets using any of these 3 equivalent syntaxes:

// 1. Direct OpenScript namespace
const token = OpenScript.env.GH_PAT;

// 2. Shorthand env global
const token = env.GH_PAT;

// 3. Standard Tampermonkey GM_getValue polyfill
const token = GM_getValue('GH_PAT', 'default_value');

Complete Example: GitHub API Fetcher with Secrets

// ==UserScript==
// @name         GitHub Repo Stats
// @version      1.0.0
// @description  Fetches repository star count with personal token
// @match        https://github.com/*
// @run-at       document_idle
// ==/UserScript==

(async function() {
  'use strict';

  // Retrieve secret saved in OpenScript "Secrets" tab
  const token = env.GH_PAT;
  if (!token) {
    console.warn('[OpenScript] Please configure GH_PAT in OpenScript Secrets tab.');
    return;
  }

  const [, owner, repo] = location.pathname.split('/');
  if (!owner || !repo) return;

  const res = await fetch(`https://api.github.com/repos/${owner}/${repo}`, {
    headers: { Authorization: `Bearer ${token}` }
  });
  const data = await res.json();
  console.log(`[OpenScript] ${data.full_name} has ${data.stargazers_count} stars!`);
})();

---

4. Boilerplate Template

When you click + New in the extension popup, OpenScript gives you this clean starter template:

// ==UserScript==
// @name         New Userscript
// @version      1.0.0
// @description  try to take over the world!
// @author       You
// @match        *://*/*
// @grant        none
// ==/UserScript==

(function() {
    'use strict';

    // Access secrets via OpenScript.env or env:
    // console.log(OpenScript.env);
})();

---

🛠️ Development & Building

# Install dependencies
npm install

# Run Vite dev server
npm run dev

# Run unit tests
npm test

# Generate icons from master v2 logo
npm run build:icons

# Build and package Chrome Web Store zip
npm run zip

---

🔒 Privacy

OpenScript does not track users, log data, or contact external servers. All user scripts are stored locally on your machine. See our Privacy Policy.