DOCSEARCHbyAlgolia
Submit Docs

Finicky Documentation

repository·main·Indexed 26 days ago

https://github.com/johnste/finicky

A macOS application that acts as a programmable default browser, allowing users to route specific URLs to different browsers or applications using custom JavaScript/TypeScript matching rules and URL rewriting logic. Includes documentation for the config-api, finicky-ui, CLI flags, and the rules.json schema.

Tokens
4K
Snippets
10
Records
38
Agent score
90%

What's inside Finicky

  2. Overview of the Config API

    main

    The config-api package provides the core logic for Finicky's URL handling. It is responsible for two primary tasks:

    1. Validating URLs: Ensuring URLs conform to expected formats.
    2. Evaluating URLs: Determining which browser should be opened based on the provided URL and configuration rules.

  3. Install Finicky on macOS

    main

    You can install Finicky using Homebrew or by downloading the latest release manually.

    To install via Homebrew:

    brew install --cask finicky

    After installation, start Finicky from your Applications folder or via Spotlight/Alfred/Raycast and allow it to be set as your default browser.

    brew install --cask finicky

  4. Install Finicky browser extensions

    main
    Finicky provides browser extensions for Chrome and Firefox. These extensions add an "open with Finicky" option to links and allow you to alt-click links to open them directly through Finicky.

  6. Configure basic routing and URL rewriting

    main

    Use the defaultBrowser, rewrite, and handlers keys in your ~/.finicky.js to control how URLs are processed.

    • defaultBrowser: The fallback browser if no handlers match.
    • rewrite: An array of objects to modify URLs (e.g., changing hosts or removing parameters) before they are opened.
    • handlers: An array of objects that match specific URL patterns to specific browsers.
    // ~/.finicky.js
export default {
  defaultBrowser: "Google Chrome",
  rewrite: [
    {
      // Redirect all x.com urls to use xcancel.com
      match: "x.com/*",
      url: (url) => {
        url.host = "xcancel.com";
        return url;
      },
    },
  ],
  handlers: [
    {
      // Open all bsky.app urls in Firefox
      match: "bsky.app/*",
      browser: "Firefox",
    },
    {
      // Open google.com and *.google.com urls in Google Chrome
      match: [
        "google.com/*", // match google.com urls
        "*.google.com*", // also match google.com subdomains
      ],
      browser: "Google Chrome",
    },
  ],
};

  7. Configure ConfigOptions

    main

    The ConfigOptions object allows you to tune the Finicky application behavior:

    • urlShorteners: An array of strings.
    • logRequests: Boolean. If true, logs requests to a file on disk.
    • checkForUpdates: Boolean. Enables/disables update checks.
    • keepRunning: Boolean. Determines if the app stays running.
    • hideIcon: Boolean. Hides the app icon.

  8. Configure the Finicky configuration object

    main

    The full Finicky configuration (typically defined in ~/.finicky.js) is represented by the Config type. It allows you to define a default browser, global options, URL rewrite rules, and browser handlers.

    Key top-level properties:

    • defaultBrowser: A BrowserSpecification used when no other handler matches.
    • options: A ConfigOptions object for application behavior.
    • rewrite: An array of RewriteRule objects to modify URLs.
    • handlers: An array of HandlerRule objects to select specific browsers/apps.
    export default = {
  defaultBrowser: "Google Chrome",
  options: {
    logRequests: false
  },
  handlers: [{
    match: "example.com*",
    browser: "Firefox"
  }]
}

  9. Define the Finicky rules.json schema

    main

    The Finicky configuration is stored in a rules.json file. The schema consists of global defaults, application options, and a list of matching rules.

    Top-level structure

    • defaultBrowser: (string) The fallback browser identifier (e.g., com.apple.Safari).
    • defaultProfile: (string, optional) The default browser profile to use.
    • options: (object, optional) Global application settings.
    • rules: (array of objects) A list of rules to match URLs to specific browsers.

    Global Options

    • keepRunning: (boolean) Whether to keep the application running.
    • hideIcon: (boolean) Whether to hide the application icon.
    • logRequests: (boolean) Whether to log requests.
    • checkForUpdates: (boolean) Whether to check for updates.

    Rule Object

    Each rule in the rules array contains:

    • match: (string or array of strings) A pattern or list of patterns to match against URLs. If only one pattern is provided, it can be a single string.
    • browser: (string) The browser identifier to use when a match occurs.
    • profile: (string, optional) A specific browser profile to use for this rule.

  10. Configure BrowserConfig

    main

    A BrowserConfig object provides granular control over how an application is launched:

    • name: The name of the application.
    • appType: One of "appName", "bundleId", "path", or "none".
    • openInBackground: Boolean. Whether to open the app in the background.
    • profile: String. The profile name to use.
    • args: An array of strings representing command-line arguments.