FAQ

These are some of the most frequently asked questions.

Where should I put my Witchcraft scripts?

You can choose any folder on your local machine to store your scripts. Just make sure to start a local web server to serve that folder (see How to install).

Why do I need a local web server?

Chrome extensions are not allowed to read files directly from your file system for security reasons. By using a local web server, Witchcraft can fetch your scripts over HTTP, which is a secure and supported way to load resources in a browser extension.

Witchcraft performs GET requests to your local web server to check if a script exists for the current page. If the script is found, it is injected into the page.

How to add third-party libraries to my scripts?

Use the @include directive as described here. You can either download the library and include it locally or reference it via a CDN URL. Example:

// @include https://cdnjs.cloudflare.com/ajax/libs/dayjs/1.11.13/dayjs.min.js

Can’t Witchcraft spawn its own local web server?

Unfortunately, no. See question above.

When exactly my script gets loaded?

As of v3.3.0, it is loaded at document_start via a content script. This is the earliest moment you can inject a script into a page. At this point, the DOM is not fully built yet, so your script should not rely on DOM elements being present. If you need to wait for the DOM to be ready, you can listen for the DOMContentLoaded event inside your script, but first check document.readyState to see if the event has already fired:

if (document.readyState === 'loading') {
    // DOM is still loading, so let's wait for it
    document.addEventListener('DOMContentLoaded', () => {
        // DOM is ready now
    });
} else {
    // DOM is already ready
}

My script seems to be loading multiple times. What is wrong?

Your page probably has frames/iframes in it. By design, Witchcraft loads itself into every frame it can find. If you want to run your script in a specific frame, you need to enforce that inside your script. For instance, you may want your script to run only in the top frame. In that case, just check if window.self === window.top. More details here.

How to load Witchcraft only in the topmost window?

See question above.

How do I inject scripts into `localhost`?

In case you are developing a web page and testing it using a local web server, you can inject code in it by naming your script localhost.js/localhost.css. If you’re running multiple web servers on different ports and need to tell them apart, do it by checking the port inside your script (check the location.port property). See an example here.

How can I inject scripts when accessing a website via an IP address instead of a domain name?

Just name your script using the IP address. For instance, if you want to load a script when accessing http://10.0.0.1, name your script 10.0.0.1.js.

Can I install Witchcraft from sources instead?

Yes, you can install Witchcraft directly from sources instead of downloading it from the Chrome store. Look for the extension source under the folder /chrome-extension and manually load it as an unpacked extension. Check the Chrome documentation here.

Is Google Analytics being used? Why?

Yes. It is being used to track actions performed inside the Witchcraft pop-up window (.e.g: “user clicked the report issue button”) and to collect anonymous statistics (e.g.: how many times was a JS include directive triggered) in order to help improve the extension.

Code is carefully tailored to make sure no user-identifiable information is sent to GA. For instance, URLs being accessed and script names are not sent to GA in any way. People are encouraged to verify the code themselves and also load the extension right from the sources if they don’t trust the Chrome Web Store package.

How can I load other resources in my scripts, like images?

There are three proposed ways to do it here.

Why is my script not updating when I reload the page?

Reloading the page should be enough to update the script. If that’s not the case, check if your HTTP server might be caching it on the server side. Try some of the recommended ways to run a local web server to see if it solves the problem.