An application (Epichrome.app) and Chrome extension (Epichrome Helper) to create and use Chrome-based SSBs on Mac OSX.
Shell JavaScript AppleScript Python CSS HTML Makefile

README.md

Epichrome 2.1.16

If you've been using version 2.1.13 or earlier, please see important note below!

Epichrome is made up of two parts: an AppleScript-based Mac application (Epichrome.app) and a companion Chrome extension (Epichrome Helper). Epichrome.app creates Chrome-based site-specific browsers (SSBs) for Mac OSX (Chrome must be installed in order to run them, but they are full Mac apps, each with its own separate Chrome profile).

Each app automatically installs Epichrome Helper, which uses rules to decide which links the app should handle itself, and which should be sent to the default web browser.

Note: due to the way Chrome updates itself, it is *not** recommended to turn on "Set Up Automatic Updates for All Users" in Chrome. This could cause fatal errors in Epichrome apps when a Chrome update is applied.*

You can find out if this is on by checking if your system contains the directory /Library/Google/GoogleSoftwareUpdate. If you find this directory, the surest way to disable this option is by *first** removing the directory from your system (you'll need administrator privileges), then deleting Chrome and reinstalling the latest release from Google. In rare cases, you may also need to delete your user-specific directory at ~/Library/Google/GoogleSoftwareUpdate before running the reinstalled Chrome.*

Download the binary release here.

See CHANGELOG.md for the latest changes.

IMPORTANT NOTE ON UPDATING

If you're running any version earlier than 2.1.14, please update to the latest version as soon as possible. Prior versions have potentially serious problems where updates could break Epichrome apps permanently, so they'd have to be deleted and recreated.

Obviously this is a huge problem, so I've create a workaround. When you open the DMG, you'll see two new icons, a README file and a shell script. Please read the README and follow the directions to install and then run the shell script if need be. This will help make the update as smooth as possible by working around the problems in versions 2.1.13 and earlier.

If you don't use the shell script, updating your apps will very likely fail, and possibly render your existing apps unusable.

Note: In general, it's a good idea to keep a backup of your Epichrome apps in case updates do break them. The epichrome_fix.sh script now included in the DMG is the easiest way to do this. Otherwise, you can just right-click on each app in the Finder and select Compress. Then if anything goes wrong, you can always delete the app and double-click the zip archive to recreate it intact.

New in version 2.1.16.

Note: I'm currently only addressing bugs at the moment. My day job has gotten very busy, so I probably won't have time to work on new features or major updates for the foreseeable future.

Version 2.1.14 changes the way Epichrome apps update themselves. They now attempt to update to the latest Epichrome engine before updating themselves to the latest version of Chrome. Doing it the other way around was causing problems if people had installed a current version of Epichrome but hadn't updated their apps before a new version of Chrome was installed. Thanks to gnyrd and everyone else who noticed and helped diagnose this problem.

2.1.14 also has brand-new icon-creation code, now able to handle JPG, GIF and other input file formats with indexed color or without alpha channels. And as a bonus, it also creates custom document icons based on the custom app icon. Thanks to io41 and freewind for identifying the shortcomings with the old icon code.

In 2.1.15 the code that checks github for new versions will no longer insist that there's a new version on github even though the app just been updated to that new version.

Finally, 2.1.16 finally squashes the bug that caused those failed Chrome updates to destroy the entire app. From now on, even if a Chrome update fails, the app should stay intact.

See CHANGELOG.md for more details.

New in version 2.1

(The main change in this release is the addition of Epichrome Helper.)

  • Apps now automatically install Epichrome Helper, a companion Chrome extension that handles link redirection so each app can have rules for which links it handles itself and which should be sent to the default browser. Rules are set up on the extension's options page, available from the Chrome extensions page. It should pop up a welcome message when first installed. (Thanks to treyharris for first bringing up the idea, and to phillip-r and cbeams for more thoughts on how it might work.)
  • Profile directories have moved to ${HOME}/Library/Application Support/Epichrome/Apps/. Existing profile directories will be automatically migrated when each app is updated.
  • Renamed the project Epichrome, mostly because I found MakeChromeSSB very annoying to say and write.

Technical Information/Limitations

Built and tested on Mac OS X 10.11.6 with Chrome version 54.0.2840.71 (64-bit).

Apps built with Epichrome are self-updating. Apps will notice when Chrome has been updated and update themself. And if you install a new version of Epichrome.app on your system, the next time you run one of the apps, it will find the new version and update its own runtime engine.

The Chrome profile for an app lives in: ${HOME}/Library/Application Support/Epichrome/Apps/

It's not currently easy to "edit" an app.

Simple method

In order to change an app, you'll need to first make sure Spotlight indexing is on for the root volume. Delete the old app (and empty trash so it's completely gone), then create a new app with the exact same name as the old one. If you keep the name identical, the new app will end up with the same ID (this will only work if Spotlight indexing is on; otherwise Epichrome always tries to create a unique-looking ID). If all goes well, the new app will use the existing Chrome profile and you won't need to re-create your settings.

Alternately (or if you don't want Spotlight indexing on), you can always copy existing profile folders to a new name to copy settings between apps.

Advanced method (change app URL)

Warning: Only try this if you're comfortable editing shell scripts and understand what you're doing inside an app bundle. If you make a mistake with this method, it is possible to render your Epichrome app unusable.

If you primarily want to change the URL, browse to the folder containing your app. Ctrl-click and choose Show package contents. Open /Contents > Resources > Scripts > config.sh/ in a text editor such as TextEdit or Atom. On the final line, you'll see something like:

SSBCommandLine=( --app=https://www.example.com )

Change the part after --app to your desired new destination. It is not recommended to change the entire app website unless you know what you're doing, but this is a good method to correct minor mistakes.

Issues

On certain webside, buttons (or other non- tag items) open links. The way Chrome handles these, the helper extension doesn't currently catch them, so can't redirect them. I'm looking at ways around this, but for now such links just open in the Epichrome app. If you're experiencing this, there's an open issue where you can add your input.

If you notice any other bugs, or have feature requests, please open a new issue. I'll get to them as soon as I can.

Future Development

These are my thoughts on where to take the project next, roughly in order of priority. I'm not committed to any of these specifically, but would love to hear from people using Epichrome as to which, if any, of these would improve your experience. And, of course, do let me know if you have any other/better ideas for what to do next!

  • Change Epichrome.app from a standalone app to a Chrome extension. I'm not sure if Google would frown on an extension of this type, but given that Chrome has to be installed for Epichrome to work, it makes sense, and would have some big user interface advantages. SSBs could automatically be built using the frontmost tab, or using all the tabs of a window, and I could finally away with the clumsy modal interface.

  • Figure out some way to get the apps to show a badge on the dock icon. I tried abusing Chrome's download system, but that didn't work. This is a bit of a long-shot, but it would be cool to have customizable access to the app badge in the same way Fluid apps do.

  • Localize Epichrome so it can be used easily in other languages. This probably won't happen until/unless I convert it to a Chrome extension. I haven't found an easy way to localize an AppleScript app.

  • Add the ability to open an existing app and edit it. I'd probably also only do this once I'd converted the project to being a Chrome extension.

  • Figure out some way to allow the user to customize where the app's Chrome profile is stored. Not sure if anybody would actually want this, so I'm not likely to do it unless I hear from people.

  • Automatically make composite document icons using whichever icon the user selects as the main app icon. This is a super low-priority item and I may never get to it unless there's a real clamor for it. It does appear this could be done pretty simply by bundling docerator in with Epichrome.

Acknowledgements

  • The underlying SSB-creation and runtime engines were inspired by chrome-ssb-osx by lhl

  • The icon-creation script makeicon.sh was inspired by Henry's comment on 12/20/2013 at 12:24 on this StackOverflow thread

  • The idea for using an AppleScript interface came from a utility by Mait Vilbiks posted here

  • Epichrome Helper uses jQuery and jQuery UI in its options page.

  • The javascript for Epichrome Helper is compressed using UglifyJS2, installed under node.js.

  • The app and extension icons are based on this image, purchased from dreamstime.com. ID 19584489 (c) Alexandr Mitiuc (Alexmit).