Features and Support

Main features

• Single-digit binary size with minimal dependencies (except for the browser, of course!)
• Multi-platform. Supports Windows, macOS, and Linux. Even on ARM!
• Two-way IPC.
• Support for both local and remote websites.
• Maximizes performance of whatever browser is chosen, and uses an entirely separate browser profile.

[!NOTE] This library will basically forever and always be intended for low-stakes or experimental use. It's really hard to guarantee working functionality and consistency across a bunch of different browsers, so please keep that in mind!

Browser support

All browser support comes with a few small caveats. You may notice small inconsistencies between, say, your app running in Firefox and in Chrome. Many of these are also not properly tested, so if you find any issues, feel free to submit an issue!

• Chrome/Chromium (stable, beta, dev, canary)
• Edge (stable, beta, dev, canary)
• Firefox (stable, beta, dev, nightly)
• Floorp
• Thorium
• Brave
• Vivaldi
• Librewolf
• Waterfox
• Mercury

Want to see what browsers are detected on your system? Run the browsers example with cargo run --example browsers!

[!TIP] Not seeing your favorite browser? Feel free to submit an issue!

If you have some programming/Rust experience, it's trivial to add new browsers to the supported list.

Usage

More examples can be found in the examples directory. Try them with cargo run --example <example>!

Displaying a remote website

use crowser::{error::CrowserError, RemoteConfig, Window};

fn main() -> Result<(), CrowserError> {
  // Profile directories are specified by you, so put it wherever makes sense!
  let mut profile_dir = PathBuf::from("/path/to/your/app/profiles");

  let config = RemoteConfig {
    url: "https://example.com".to_string(),
  };

  let mut window = Window::new(config, None, profile_dir)?;

  // Make sure the profile is brand-new before launch
  window.clean_profile()?;

  // This will spawn the window and block until it is closed
  window.create()?;

  Ok(())
}

Embedding a local website

use crowser::{error::CrowserError, include_dir, LocalConfig, Window};

fn main() -> Result<(), CrowserError> {
  let mut profile_dir = PathBuf::from("/path/to/your/app/profiles");

  // include_dir is a re-export of the include_dir crate
  let dir = include_dir::include_dir!("/path/to/your/app/dist");

  let config = LocalConfig {
    directory: dir.clone(),
  };

  let mut window = Window::new(config, None, profile_dir.clone())?;

  window.clean_profile()?;

  // Since we're looping, we'll break when we successfully create the window. This will
  // actually block the thread until the window is closed.
  match window.create() {
    Ok(_) => {
      println!("Window created on port {}", port);
      break;
    }
    Err(e) => {
      println!("Error creating window on port {}: {:?}", port, e);
    }
  }

  Ok(())
}

Registering a command

use crowser::{error::CrowserError, ipc::BrowserIpc, RemoteConfig, Window};

fn main() -> Result<(), CrowserError> {
  let mut profile_dir = std::env::current_dir()?;
  profile_dir.push("example_profiles");

  let config = RemoteConfig {
    url: "https://example.com".to_string(),
  };

  let mut window = Window::new(config, None, profile_dir)?;
  let root_ipc = window.get_ipc();

  window.clear_profile().unwrap_or_default();

  std::thread::spawn(move || {
    let mut ipc: BrowserIpc;

    // Wait for IPC to be initialized
    loop {
      std::thread::sleep(std::time::Duration::from_millis(10));

      let mut root_ipc = match root_ipc.try_lock() {
        Ok(val) => val,
        Err(_) => continue,
      };

      if let Some(root_ipc) = root_ipc.as_mut() {
        ipc = root_ipc.clone();
        break;
      }
    }

    ipc
      .register_command(
        "hello",
        Box::new(|_| {
          println!("Got hello command");
          Ok(serde_json::json!("Hello from Crowser!"))
        }),
      )
      .unwrap_or_default();

    std::thread::sleep(std::time::Duration::from_secs(1));

    // Eval some JS that calls that command
    let result = ipc.eval("window.__CROWSER.ipc.invoke('hello')").unwrap_or_default();
    println!("Result: {:?}", result);
  });

  window.create()?;

  Ok(())
}

How does it work?

On a high level, Crowser works by first detecting browser installations on the user's system (using known paths and registry keys). Then, depending on the browser chosen, it will make some specific changes to the browser's CLI arguments, profile directory, or both. For example, for Firefox there is a user.js file in all profiles that can control much of the browser's default behavior. In Chromium-based browsers, there are a stupid amount of command-line arguments that can be used to control the browser's behavior (check out this huge list!).

IPC is facilitated through the Chrome DevTools Protocol. To keep the binary size small, the implementation is custom and therefore a little scuffed, but developers do not have to care about it anyways!

Contributing

Issues, PRs, etc. are all welcome!