What is Witchcraft?
Think Greasemonkey for developers.
It works by matching the current page domain against script file names available in the scripts folder. For instance, if one navigates to https://www.google.com, Witchcraft will try to load and run google.com.js and google.com.css. For the screenshot above, those are:
Script changes are seamless
Whenever you edit or create new scripts, there's no need to reload anything other than the page where the scripts are supposed to run. This is what makes Witchcraft special and different from other popular scripting tools, like Greasemonkey or Tampermonkey;
Since Witchcraft runs as a Chrome extension, it is also cross-platform. It has been tested on Windows, MacOS and Linux;
Runs on all frames
Witchcraft is listening for pages loading everywhere, not just on the top frame. This means it will run even on pages loaded inside other pages.
How to use
Once your environment is ready (see installation instructions), simply start creating your scripts and adding them to the scripts folder. If you'd like to run some script every time you enter, say, github.com, just go ahead and create github.com.js. Then head to github.com (or refresh the page if it's already open) and the script will run immediately.
Domain level scripts
Witchcraft also looks for scripts on all domain levels. For instance, if one accesses https://gist.github.com, it will try to load all domain levels for which there are existing scripts, in this very order:
- _global.js (see next section for more details)
- _global.css (see next section for more details)
Every script found is directly executed in the current page's context.
If present, _global.js and _global.css scripts (added in version 2.3.0) will load for every web site, independently of the host name. Useful if you have some setup routine common to all your scripts.
Starting with version 2.5.0, Witchcraft also tries to match path segments. For example, going to https://github.com/luciopaiva/witchcraft will yield the following sequence of script loading attempts:
Notice that path segments are mapped to local folders in your scripts directory.
Also important to notice is that, if the host name begins with www, it must be part of the directory structure as well. This is important because modern browsers tend to hide the www part, giving the false impression that it is not there.
Including other scripts
It is possible to include remote scripts as well:
Useful for loading scripts from gists, for example.
Included scripts can also @include scripts of their own; the parser will recursively iterate through them. Dependency cycles (e.g., foo.js includes bar.js, which includes foo.js) will be automatically resolved and each script won't be loaded more than once.
This directive may be useful for including third-party libraries, like jQuery.