Developers

User scripts

Scripts are your own JavaScript and CSS, written in Pulsar’s editor or imported from a file or a link. Nothing to sign, nothing to package: save it and it runs on the sites you chose.

What user scripts are

They live in the Scripts extension (Extensions › Scripts), which comes with Pulsar. Tap + to write one, or import one.
A script is JavaScript or CSS, a list of sites it Runs on, and when it Runs when.
Each JavaScript script runs in its own sandbox: it sees the page like any page script, plus one object, pulsar.
CSS is added to every page it runs on, before the page shows.
Scripts are not extensions: no manifest, no signing, no store. They are for you, on your phone. To share your work with others, build a Lite extension or a full extension.

Import a script

Import from a file or an https link. The editor opens with the script filled in; check it and tap Save.

File	What Pulsar reads
.user.js	The code, and these lines of its header: `@name`, `@match`, `@include` (when it is a match pattern) and `@run-at`.
.js	The code. You choose the sites and the timing.
.css, .user.css	A style. You choose the sites.

bigger-text.user.js

// ==UserScript==
// @name        Bigger text on news.example
// @match       https://news.example/*
// @match       https://*.news.example/*
// @run-at      document-end
// ==/UserScript==

document.documentElement.style.fontSize = "112%";

GM_* functions and @require aren’t available. Put everything the script needs into the script itself.

Runs on

One or more sites, separated by commas. Pulsar checks them as you type.

You write	It runs on
news.example/*	That site, with or without `www.`
.example/	The site and every subdomain
news.example/world/*	Part of a site
https://news.example/*	A full match pattern
*	Every site

No ports, and * only at the start of a host name.

Runs when

In the editor	run_at	When
Page start	document_start	Before the page’s own code; the document is still empty.
Page loaded	document_end	Once the page’s HTML is there (DOMContentLoaded).
Page idle	document_idle	A little later, when the page has settled.

The pulsar object

Call	Does
pulsar.toast(text)	A short message at the bottom of Pulsar’s window, on the tab on screen. At most one every 2 seconds.
pulsar.storage.get(key, fallback)	A value this script saved, or `fallback`. Instant: the values come with the script.
pulsar.storage.set(key, value)	Saves any JSON value for this script. At most 64 KB per script in all. Pages loaded later see it.
pulsar.storage.remove(key)	Removes one value.
pulsar.storage.keys()	The keys this script saved.
pulsar.id, pulsar.name	This script.
console.log / info / warn / error	Shown in the editor’s Console with the page they came from, at most 300 lines per page. Errors your script throws while it starts show there too.

Test on page

Test on page in the editor runs your code once on the current tab, without saving it.
JavaScript: the page reloads and the script runs there exactly as a saved one would, with the same sandbox and pulsar object.
CSS: the style is added to the page as it is.
Open the Console to see your console lines and errors.

Where scripts never run

On the Pulsar Store website, whatever they match.
In private tabs, unless you allow it (Extensions › Scripts › Run in private tabs).
On sites where you switched the Scripts extension off.
Anywhere, while the Scripts extension is off or removed, or switched off by Pulsar.

Examples

Count your visits · Runs on news.example/* · Page loaded

const n = pulsar.storage.get("visits", 0) + 1;
pulsar.storage.set("visits", n);
pulsar.toast(`Visit number ${n}`);
console.log("Hello from", location.host);

Open external links in a new tab · Runs on *.example/* · Page idle

for (const a of document.querySelectorAll("a[href^='http']")) {
  if (new URL(a.href).host !== location.host) {
    a.target = "_blank";
    a.rel = "noopener";
  }
}

Remember where you were · Runs on docs.example/* · Page loaded

const key = "scroll:" + location.pathname;
const y = pulsar.storage.get(key, 0);
if (y > 0) {
  window.scrollTo(0, y);
  pulsar.toast("Back where you left off");
}
let t;
addEventListener("scroll", () => {
  clearTimeout(t);
  t = setTimeout(() => pulsar.storage.set(key, Math.round(scrollY)), 500);
}, { passive: true });

Calmer reading · Runs on blog.example/*

article {
  max-width: 38rem;
  margin-inline: auto;
  line-height: 1.7;
}
.newsletter-popup, .cookie-wall { display: none !important; }

#What user scripts are

#Import a script

#Runs on

#Runs when

#The pulsar object

#Test on page

#Where scripts never run

#Examples