{"id":15115703,"url":"https://github.com/shinzlet/oildrop","last_synced_at":"2025-07-03T09:10:34.809Z","repository":{"id":50236648,"uuid":"342992536","full_name":"shinzlet/oildrop","owner":"shinzlet","description":"A tiny (~600 sloc) userscript manager that you can self-audit and fully trust.","archived":false,"fork":false,"pushed_at":"2021-08-10T23:27:46.000Z","size":44887,"stargazers_count":8,"open_issues_count":4,"forks_count":3,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-01-18T03:31:33.406Z","etag":null,"topics":["audit","javascript","userscripts"],"latest_commit_sha":null,"homepage":"https://addons.mozilla.org/en-CA/firefox/addon/oildrop/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shinzlet.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-02-28T01:01:59.000Z","updated_at":"2025-01-01T20:49:49.000Z","dependencies_parsed_at":"2022-09-16T05:02:34.493Z","dependency_job_id":null,"html_url":"https://github.com/shinzlet/oildrop","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/shinzlet/oildrop","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shinzlet%2Foildrop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shinzlet%2Foildrop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shinzlet%2Foildrop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shinzlet%2Foildrop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shinzlet","download_url":"https://codeload.github.com/shinzlet/oildrop/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shinzlet%2Foildrop/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263296638,"owners_count":23444499,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audit","javascript","userscripts"],"created_at":"2024-09-26T01:43:58.262Z","updated_at":"2025-07-03T09:10:34.786Z","avatar_url":"https://github.com/shinzlet.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# Oildrop\nOildrop is a userscript manager for Firefox. It was designed to be audited by anyone in less than\n30 minutes, does not communicate with a server, and can be easily modified to suit your needs.\n\n## Table of Contents\n- [Features](#features)\n- [Screenshots](#screenshots)\n- [Installation Instructions](#installation)\n- [Usage Instructions](#usage)\n- [How to Audit Oildrop](#how-to-audit-oildrop)\n- [Development Instructions](#development)\n- [Limitations](#limitations)\n- [Contributors](#contributors)\n- [Licensing Info](#licensing)\n\n## Features\n- Sleek, modern interface\n- Manage scripts and styles in one extension\n- Dark and light theme\n- Import / Export your scripts with JSON\n- GPLv3 License\n- Less than 600 lines of code (no golfing required)\n- Easy to tweak to your needs\n- Designed with accessibility in mind\n\n## Screenshots\n### Main UI\n\u003cimg src=\"https://raw.githubusercontent.com/shinzlet/oildrop/media/oildrop-hero.png\" alt=\"An image showing Oildrop in light and dark mode. Several scripts are listed in its overview panel.\"\u003e\nOildrop is invoked via the browser icon by default. Shown here is the script overview in both light and dark mode, which can be toggled easily.\n\n### Full-page View\n\u003cimg src=\"https://raw.githubusercontent.com/shinzlet/oildrop/media/fullscreen_windows.png\" alt=\"Oildrop's data management window and full-screen popup shown in a browser.\"\u003e\nOildrop can be opened in a full page for ease-of-use if a popup is not desirable. Also shown is Oildrop's data management page, which allows you to import and export scripts.\n\n### Editor and Settings Menu\n\u003cimg src=\"https://raw.githubusercontent.com/shinzlet/oildrop/media/menu_demos.png\" alt=\"A preview showing the editor and settings menu in oildrop.\"\u003e\nThis preview shows a script being edited in Oildrop on the left, and the settings menu on the right.\n\n## Installation\nOildrop can be installed via several means, the easiest of which is the\n[Firefox Addon Store](https://addons.mozilla.org/en-CA/firefox/addon/oildrop/).\n\nYou can also [download the latest signed release from GitHub](https://github.com/shinzlet/oildrop/releases),\nwhich is easier to audit. this is what I'd reccommend doing. Unlike the first\nmethod, you will not receive automatic updates. If you go this route, see\n[\"How to Audit Oildrop\"](#how-to-audit-oildrop). Once you audit the release,\nyou can install it by typing `about:addons` in the address bar, clicking the\ngear next to \"Manage Your Extensions\", and then selecting \"Install Add-on From\nFile...\" in the context menu. From there, navigate to the `.xpi` file you\ndownloaded, and click `Open`.\n\nIf you want to modify Oildrop for your needs, instructions are available below for\n[development](#development), [building, and self-signing](#building-and-signing) the\nextension.\n\n## Usage\n### Opening Oildrop\nOnce you have Oildrop installed, you will be able to access it via the icon in your\nbrowser's toolbar. If you can't see it, you can drag it onto your toolbar by right\nclicking on the toolbar, then selecting `Customize Toolbar`.\n\n### Main UI Overview\nAlmost every UI element in Oildrop has an informative tooltip, which you can see\nby holding your mouse cursor still atop it. A description of the user interface\nis offered below, if you'd prefer.\n\nWhen the popup opens, you'll see Oildrop's main interface. At the top right corner,\nbuttons are present which allow you to toggle between colorschemes and open settings,\nleft to right.\n\nJust below is the main overview panel. Clicking the play/pause button to the left allows you\nto control Oildrop's behaviour at a global level - by pausing Oildrop, all scripts\nwill be temporarily disabled. By re-enabling Oildrop, scripts with a checkmark to the\nleft of their name will be enabled. You can tell if Oildrop is enabled or disabled\nby the bar at the bottom of the interface, which will be red if paused, and green\nif enabled. Hovering over the bar with a mouse cursor will display a message with\nthat same information.\n\nTo the left of the play/pause button is the filter dropdown. By changing the setting\ndisplayed, you'll be able to show or hide scripts depending on their current relevance.\nHere is a key to what the options mean:\n- \"All Scripts\": Every script that Oildrop has saved will be shown.\n- \"Active Scripts\": Every script whose url matches the current page will be\n   shown. For example, if the current tab is open to `https://google.com`, a\n   script that matches `\u003call_urls\u003e` will be displayed, but a script that matches\n   `*://*youtube.com/*` will not.\n- \"Inactive Scripts\": This is the opposite of the \"Active Scripts\" option. Only\n  scripts that are not able to run on the current page will be shown.\n\nNote that \"activity\" is not an indicator of wether a script actually *is* running. A\nscript will only run on a page if it has a checkmark next to its name, and if Oildrop\nis globally enabled with the play/pause button described above.\n\nTo the right of the filter bar is the self-explanatory \"new script\" button, which will\nopen the script editor. By default, the script will match the current tab's URL.\n\nBelow the filter bar is the main overview, which shows all scripts matching the filter\nrule. They can be enabled or disabled by checking the box to the left of their name.\nEach script item will show some information about itself, like its name, the pages\nit matches, wether it is CSS (has a blue badge to the left of the name) or JavaScript\n(which has a red badge), and when it was made. Additionally, each script has a button\nthat allows you to edit or delete it.\n\n### Editor Overview\nThe editor, which can be opened via the \"new script\" button or an edit button next\nto an existing script, allows you to modify userscripts. Each field has a tooltip,\nwhich can be displayed by mousing over the question mark to the right of the field\nlabel. These fields are mostly unsurprising, so only a brief rundown is included here:\n- Name: The name of the script. This is only used for display purposes, so you can put\n  whatever you'd like here.\n- Run On: A comma-separated list of [match patterns](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns).\n- Code: The code (be it JavaScript or CSS) that the userscript will run.\n- Language: The langauge your code is written in.\n- Runtime: When, during page load, your script should be injected. See the\n  `run_at` field [here](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts) for more info.\n\nPressing the \"Save\" button will save your changes and close the editor. Pressing\n\"Close\" will discard your changes and close the editor.\n\n### Settings Overview\nThe settings menu has a few important things within. The first is a checkbox that\nallows you to enable or disable tab-key indentation in the code editor. This may seem\ntrivial, but is important for accessibility purposes. If you rely on the tab key\nfor form navigation, I advise you to turn this checkbox off, which will allow you\nto exit the code editor by pressing the tab key.\n\nNext are two buttons that will open a new tab. The first one takes you to the\ndata management page, which allows you to import or export Oildrop's configuration\nand scripts.\n\nSecondly is a button that opens the Oildrop window itself in a new tab. This is useful\nwhen you're developing a longer script, or just don't want the popup to go away when you\nclick outside of it (as is the default behaviour for browser extensions).\n\n### Questions?\nIf you have a question about Oildrop, need usage help, or have a feature request,\nfeel free to open an [issue](https://github.com/shinzlet/oildrop/issues/new).\n\n## How to Audit Oildrop\nUnderstanding how a peice of software functions can be daunting, and this section aims\nto help guide you through Oildrop's internals.\n\nTo start, a little exposition. The `.xpi` file you downloaded in the releases\nsection is a compressed archive of Oildrop's source code which was signed by Mozilla.\nIn order to audit the code within, we'll first have to decompress that archive. You can\ndo this either by renaming it from `oildrop-xxx.xpi` to `oildrop-xxx.zip` (where `xxx`\nis a version number), or by running `unzip oildrop-xxx.xpi -d oildrop` at the command\nline.\n\nOnce you've done this, you'll see a carbon copy of this repository. The one difference\nis the addition of a `META-INF` folder, which is what Mozilla added.\n\nNow that you've opened up Oildrop, you can feel free to inspect any files you'd like.\nThe only executable code that Oildrop includes is in the `js` folder. Here's a rundown\nof what you'll find there:\n\n- `oildrop.js`: Contains helper functions that are used everywhere throughout Oildrop.\n- `background.js`: Interfaces with Firefox's `userScripts` api, which is what actually injects your userscripts into websites.\n- `ui.js`: Connects Oildrop's main user interface to the background script, which allows you to create, edit, and view your scripts.\n- `code_editor.js`: Allows indenting and un-indenting in Oildrop's code editor.\n- `manage.js`: Implements data management functions and connects them to the `Import / Export Data` page (accessible via Oildrop's settings).\n\nAdditionally, feel free to make sure that the HTML and CSS do not reference any remote\nfiles. As far as I'm aware, HTML and CSS cannot be used maliciously when only local\nassets are used, which is the case in Oildrop.\n\nThis should be enough help to get started, but I hope to make a full walkthrough\nof the source code soon. If you have any questions, feel free to open an issue!\n\n## Development\nOildrop is written in plain HTML and JavaScript, but uses sass to accelerate styling.\nIf you're tweaking Oildrop for personal use, you can edit the compiled CSS and ignore\nthe build process. However, if you want to contribute to or fork Oildrop, you'll want\nto use the Sass pipeline. To do so, [install dart-sass](https://sass-lang.com/install),\nthen run `make watch`. This will automatically watch and compile your scss into the `css` folder.\n\nTo test the extension, you will need to have [`web-ext`\ninstalled](https://extensionworkshop.com/documentation/develop/getting-started-with-web-ext/).\nThen, invoke `make run` to open a development browser with Oildrop loaded.\n\n### Building and Signing\nOildrop can be built and signed using the `web-ext` CLI. For documentation about this process,\nsee https://extensionworkshop.com/documentation/develop/getting-started-with-web-ext/.\n\n## Limitations\n- Oildrop only works in Firefox. Adding the neccessary polyfills to make it cross-platform would have easily doubled the codebase. That being said, porting it would not be a monumental challenge, and forks are welcomed.\n- Oildrop's editor is good enough for quick scripting, but is not intended to replace your editor of choice. For complicated scripts, you should write code elsewhere and import it into Oildrop.\n- Because it isn't needed for most tasks, the GreaseMonkey `GM_` API is not implemented in Oildrop. Increasing compatibility with other userscript managers is something I'd like to look into, however.\n\n## Contributors\n- [Seth Hinz](https://github.com/shinzlet), [sethhinz@me.com](mailto:sethhinz@me.com)\n    + Concept, programming\n- [Chiara Colangelo](https://dribbble.com/ChiaraColangelo), [chiara.colangelo@ninjabit.com](mailto:chiara.colangelo@ninjabit.com)\n    + UI Designer\n\n## Licensing\nAll of Oildrop's source code is licensed under GPLv3. Some of the fonts and\nicons used are under different licenses.  Their respective licenses are stored\nin the assets folder.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshinzlet%2Foildrop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshinzlet%2Foildrop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshinzlet%2Foildrop/lists"}