Vimium: The Hacker's Browser - Deployment and Usage Guide

Vimium is a browser extension that provides keyboard-based navigation and control of the web, inspired by the Vim editor.

Prerequisites

To install Vimium from source, you will need:

Node.js: A JavaScript runtime.
npm: Node.js package manager (usually bundled with Node.js).
Git: For cloning the repository.
A compatible browser: Chrome, Edge, or Firefox.

Installation

From Browser Web Stores (Recommended)

The easiest way to install Vimium is directly from your browser's extension store:

Chrome: Chrome Web Store
Edge: Edge Add-ons
Firefox: Firefox Add-ons

From Source

To install Vimium from source, follow these steps:

Clone the repository:

git clone https://github.com/philc/vimium.git
cd vimium

Install dependencies:
```
npm install
```
Build the extension:
```
npm run build
```
This will create a dist directory containing the built extension files.
Load the extension in your browser:
- Chrome/Edge:
  1. Open chrome://extensions (or edge://extensions).
  2. Enable "Developer mode" (usually a toggle in the top right).
  3. Click "Load unpacked".
  4. Navigate to the dist directory within your cloned repository and select it.
- Firefox:
  1. Open about:addons.
  2. Click the gear icon (⚙️) on the top right and select "Debug Add-ons".
  3. Click "Load Temporary Add-on...".
  4. Navigate to the dist directory within your cloned repository and select any file inside it (e.g., manifest.json).

Configuration

Vimium's configuration is managed through its Options page.

Accessing the Options Page

You can reach the Options page in a few ways:

From the help dialog: Type ? in any web page to open the help dialog, then click the "Options" link.
From your browser's extension management page:
- Chrome/Edge: Go to chrome://extensions (or edge://extensions), find Vimium, and click "Extension options" or a similar button.
- Firefox: Go to about:addons, find Vimium, click the three dots (...), and select "Preferences" or "Options".

Custom Key Mappings

You can customize or unmap default key bindings in the "Custom key mappings" section of the Options page.

Enter one mapping statement per line:

map key command: Maps a key to a Vimium command. Example: map <c-d> scrollPageDown
unmap key: Unmaps a key, restoring default browser behavior. Example: unmap <c-d>
unmapAll: Unmaps all default Vimium bindings.

Special Keys:

Modifier keys: <c-*>, <a-*>, <s-*>, <m-*> (e.g., <c-x> for Ctrl+X, <m-x> for Meta/Command+X).
Arrow keys: <left>, <right>, <up>, <down>.
Function keys: <f1> through <f12>.
Other: <space>, <tab>, <enter>, <delete>, <backspace>, <insert>, <home>, <end>.

Comments: Start a line with " or # for comments.

For a full list of commands and options, refer to the Vimium commands documentation.

Build & Run

Vimium is a browser extension, so "running" it involves loading it into your browser.

Development Build

Clone the repository:

git clone https://github.com/philc/vimium.git
cd vimium

Install dependencies:
```
npm install
```
Build:
```
npm run build
```
This command compiles the JavaScript and other assets into the dist directory. The build process uses various modules like lib/utils.js, lib/settings.js, background_scripts/commands.js, content_scripts/mode_visual.js, and lib/dom_utils.js to create the extension's functional components.
Load into browser: Follow the "Load the extension in your browser" steps from the Installation from Source section.

Production Build

The npm run build command generates a production-ready build. There isn't a separate production-specific build command for this project beyond the standard build. The output in the dist folder is what would typically be packaged and submitted to extension stores.

Deployment

Vimium is deployed as a browser extension. The primary deployment method is through the official browser web stores.

Browser Web Store Deployment

To deploy your own modified version or a fork to a browser web store:

Build the extension: Ensure you have a clean, production-ready build in the dist directory.
```
npm run build
```
Package the extension:
- Chrome/Edge: In chrome://extensions (or edge://extensions), with "Developer mode" enabled, click "Pack extension". Point it to your dist directory. This will generate a .crx file (and a .pem key file if it's new).
- Firefox: The dist directory can be zipped, and the .zip file can be submitted as an .xpi file.
Developer Accounts: You will need a developer account for each browser store:
- Chrome Web Store: Requires a one-time registration fee.
- Microsoft Edge Add-ons: Free to register.
- Mozilla Add-ons: Free to register.
Submission: Follow the submission guidelines for each respective store to upload your packaged extension, provide descriptions, screenshots, and privacy policies.

Troubleshooting

Vimium not working on certain pages:
- Issue: Some pages, especially internal browser pages (e.g., chrome://extensions, about:addons), or pages with strict Content Security Policies, may prevent Vimium from running.
- Solution: This is expected behavior due to browser security restrictions. Vimium cannot operate on these pages. Check if the Vimium icon is greyed out.
- Exclusions: If Vimium is not working on a regular website, check your "Excluded URLs" in the Vimium Options page. Ensure the site is not listed there.
Key bindings not responding:
- Issue: After installation or update, key bindings might not work.
- Solution:
  1. Reload the page: Sometimes a simple page reload (r in Vimium, or F5) can fix it.
  2. Restart your browser: Close and reopen your browser.
  3. Check for conflicts: Other extensions might be using the same keyboard shortcuts. Try disabling other extensions temporarily to identify conflicts.
  4. Ensure Vimium is enabled: Verify that Vimium is enabled in your browser's extension manager.
npm install or npm run build errors:
- Issue: Dependency installation or build process fails.
- Solution:
  1. Check Node.js/npm version: Ensure you have a relatively recent version of Node.js and npm.
  2. Clear npm cache: npm cache clean --force
  3. Delete node_modules and package-lock.json: Then run npm install again.
  4. Internet connection: Ensure you have an active internet connection to download dependencies.
Vimium commands are ignored after typing i:
- Issue: Vimium stops responding to commands.
- Solution: You are likely in "Insert Mode". Press <Esc> (or <c-[>) to exit Insert Mode and resume Vimium commands.
Custom key mappings not working:
- Issue: Your custom key mappings in the Options page are not taking effect.
- Solution:
  1. Save changes: Ensure you have saved your changes on the Options page.
  2. Syntax errors: Double-check for typos or incorrect syntax in your mappings. Refer to the Custom Key Mappings section.
  3. Command existence: Verify that the command you are trying to map exists and is spelled correctly (e.g., scrollPageDown vs. scrollpagedown). Refer to the Vimium commands documentation.
Vimium secret token issue:
- Issue: (Less common, more internal) Errors related to vimiumSecret or chrome.storage.session.
- Solution: This is usually handled internally by Vimium. If you encounter such an error, it might indicate a more fundamental issue with the extension's background script. A browser restart or re-installation of the extension might be necessary. (See background_scripts/main.js which generates and sets this token).

How to Deploy & Use philc/vimium