Codakey
Play
← Back to FelisCatus/SwitchyOmega

How to Deploy & Use FelisCatus/SwitchyOmega

SwitchyOmega Deployment & Usage Guide

⚠️ Project Status: SwitchyOmega is no longer actively maintained. Critical bugs may not be fixed. Consider forks or alternatives for production use.

1. Prerequisites

  • Node.js with npm 2.x (Critical: npm 3+ is not supported)
  • Git
  • Google Chrome, Chromium, or Firefox (for testing)
  • Global npm packages: 
    sudo npm install -g grunt-cli@1.2.0 bower

2. Installation

Clone the repository and install dependencies:

git clone https://github.com/FelisCatus/SwitchyOmega.git
cd SwitchyOmega/omega-build

# Install dependencies in all modules
npm run deps

# Optional: Set up local development links (may require sudo)
npm run dev

3. Configuration

Build Configuration

No pre-build configuration is required. The build system automatically compiles CoffeeScript and packages assets.

Extension Configuration

Proxy profiles and switch rules are configured after installation via the extension's options page in your browser. No config files need manual editing before deployment.

Translations

To contribute translations, use the Weblate project. Do not manually edit translation files in the repository.

4. Build & Run

Build the Extension

# In omega-build directory
grunt

The compiled extension will be available at:

omega-chromium-extension/build/

Run in Chrome/Chromium

  1. Open chrome://extensions/
  2. Enable Developer mode (toggle in top-right)
  3. Click Load unpacked
  4. Select the omega-chromium-extension/build/ directory
  5. The extension icon will appear in the toolbar

Run in Firefox (Experimental)

Requirements: Firefox Nightly >= 56.0 (Stable and Beta channels are not supported)

  1. Open about:debugging
  2. Click This Firefox → Load Temporary Add-on
  3. Select any file in the omega-chromium-extension/build/ directory
  4. The extension will load for the current session only

Note: PAC Profiles do not work in Firefox due to Mozilla Add-on review policies.

Development Mode

Enable auto-rebuild on file changes:

grunt watch

Run this in the omega-build directory to watch all modules.

5. Deployment

Chrome Web Store

  1. Build the project: grunt
  2. Zip the contents of omega-chromium-extension/build/ (not the folder itself)
  3. Upload to Chrome Developer Dashboard
  4. Submit for review

Firefox Add-ons (AMO)

  1. Build the project: grunt
  2. Package omega-chromium-extension/build/ as a .zip file
  3. Rename the .zip to .xpi
  4. Upload to Mozilla Add-on Developer Hub
  5. Important: Note in the submission that PAC scripts are generated locally and do not use remote URLs (required for AMO policy compliance)

GitHub Releases (Offline Installation)

  1. Build: grunt
  2. Package omega-chromium-extension/build/:
    • For Chrome: Create .crx using Chrome's "Pack extension" tool
    • For Firefox: Create .xpi (zip with renamed extension)
  3. Upload to GitHub Releases page with version tag

Enterprise Deployment

For managed Chrome/Edge environments:

  1. Build and pack the extension as .crx
  2. Use Group Policy (Windows) or Managed Preferences (macOS/Linux) to force-install:
    • Extension ID: padekgcemlokbadohgkifijomclgjgif
    • Update URL: Your internal update server or Chrome Web Store

6. Troubleshooting

Build Issues

Error: npm version incompatible

  • Ensure you are using npm 2.x: npm --version
  • If using npm 3+, downgrade or use nvm to switch Node versions

Error: Permission denied during npm run dev

  • Run with sudo: sudo npm run dev
  • Or fix npm permissions: sudo chown -R $(whoami) ~/.npm

Error: grunt command not found

  • Install globally: sudo npm install -g grunt-cli@1.2.0

Error: bower components missing

  • Run bower install in the omega-web directory if assets are missing

Runtime Issues

Extension not loading in Chrome

  • Ensure Developer Mode is enabled
  • Check that you selected the build folder, not the parent directory
  • Look for errors in chrome://extensions/ → "Errors" button

Firefox: "This add-on could not be installed"

  • Ensure you are using Firefox Nightly >= 56
  • Stable and Beta channels are explicitly unsupported
  • Try using "Load Temporary Add-on" instead of drag-drop installation

PAC Profiles not working in Firefox

  • This is a known limitation due to AMO review policies
  • Use Switch Profiles or Direct connections instead
  • No workaround available for Firefox release builds

Settings not persisting

  • Check browser storage permissions
  • Ensure you are not in Private/Incognito mode (settings may not persist)
  • Check for errors in the background page console (Chrome: chrome://extensions/ → "background page")

Development Issues

Changes not reflecting

  • Ensure grunt watch is running in omega-build
  • Hard refresh the extension options page (Ctrl+F5 or Cmd+Shift+R)
  • Reload the extension from chrome://extensions/ after code changes

CoffeeScript compilation errors

  • Check syntax in .coffee files
  • Ensure consistent indentation (significant whitespace)
  • Run grunt without watch to see full error traces
← Project overviewView alternatives to FelisCatus/SwitchyOmega →