Following documentation is mostly speaking about Chrome Extension development but the same patterns generally apply to Chrome App development as well.

This library is data-driven. Given an API namespace, all API methods, properties and events are described in a Clojure map along with their parameters, callbacks, versions and additional metadata (a simple example - look for api-table here). Chromex then provides a set of macros which consume this table and generate actual ClojureScript code wrapping native APIs.

These macros can be further parametrized which allows for greater flexibility. Sane defaults are provided with following goals:

Chrome Extension API is evolving. You might want to target multiple Chrome versions with slightly different APIs. Good news is that our API data map contains full versioning and deprecation information.

By default you target the latest APIs. But you can target older API version instead and we will warn you during compilation in case you were accessing any API not yet available in that particular version.

Additionally we are able to detect calls to deprecated APIs and warn you during compilation.

Generated API data map contains information about all parameters and their types. Chromex provides a pluggable system to specify how particular types are marshalled when crossing API boundary.

By default we marshall only a few types where it makes good sense. We don't want to blindly run all parameters through clj->js and js->clj conversions. That could have unexpected consequences and maybe performance implications. Instead we keep marshalling lean and give you an easy way how to provide your own macro which can optionally generate required marshalling code (during compilation).

There is also a practical reason. This library is auto-generated and quite large - it would be too laborious to maintain hairy marshalling conventions up-to-date with evolving Chrome API index. If you want to provide richer set of marshalling for particular APIs you care about, you can do that consistently.

Many Chrome API calls are async in nature and require you to specify a callback (for receiving an answer later). You might want to watch this video explaining API conventions in Chrome.

We automatically turn all API functions with a callback parameter to a ClojureScript function without that callback parameter but returning a new core.async channel instead (promise-chan). The channel eventually receives a vector of parameters passed into the callback. When an error occurs, the channel closes without receiving any result (you receive nil). In that case you can immediately call chromex.error/get-last-error to obtain relevant error object (which is what was found in chrome.runtime.lastError during the callback).

This mechanism is pluggable, so you can optionally implement your own mechanism of consuming callback calls.

Chrome API namespaces usually provide multiple event objects which you can subscribe with .addListener. You provide a callback function which will get called with future events as they occur. Later you can call .removeListener to unsubscribe from the event stream.

We think consuming events via core.async channels is more natural for ClojureScript developers. In Chromex, you can request Chrome events to be emitted into a core.async channel provided by you. And then implement a single loop to sequentially process events as they appear on the channel.

Again this mechanism is pluggable, so you can optionally implement a different mechanism for consuming event streams.

We provide an example skeleton Chrome extension chromex-sample. This project acts as a code example but also as a skeleton with project configuration. We recommended to use it as starting point when starting development of your own extension.

Chromex does not rely on externs file. Instead it is rigorously using string names to access Javascript properties. I would recommend you to do the same in your own extension code. It is not that hard after all. You can use oget, ocall and oapply macros from chromex.support namespace. Or even better use full-featured library cljs-oops designed to work with string names.

Note: There is a chrome_extensions.js externs file available, but that's been updated ad-hoc by the community. It is definitely incomplete and may be incorrect. But of course you are free to include the externs file into your own project and rely on it if it works for your code. It depends on how recent/popular APIs are you going to use.

As we wrote in previous sections, by default you consume Chrome events via core.async channels:

first, you have to create/provide a channel of your liking

then optionally wrap it in make-chrome-event-channel call

then call one or more tap-some-events calls

then you can process events as they appear on the channel

If you don't want to use the channel anymore, you should close! it.

Events coming from the channel are pairs [event-id params], where params is a vector of parameters passed into event's callback function. See chromex-sample for example usage. Refer to Chrome's API docs for specific event objects.

Note: instead of calling tap-some-events you could call tap-all-events. This is a convenience function which will tap events on all valid non-deprecated event objects in given namespace. For example tabs/tap-all-events will subscribe to all existing tabs events in the latest API.

make-chrome-event-channel is a convenience wrapper for raw core.async channel. It is aware of event listeners and is able to unsubscribe them when channel gets closed. But you are free to remove listeners manually as well, tap calls return ChromeEventSubscription which gives you an interface to unsubscribe! given tap. This way you can dynamically add/remove subscriptions on the channel.

Tap calls accept not only channel but also more optional arguments. These arguments will be passed into .addListener call when registering Chrome event listener. This is needed for scenarios when event objects accept filters or other additional parameters. web-navigation/tap-on-committed-events is an example of such situation. Even more complex scenario is registering listeners on some webRequest API events (see 'Registering event listeners' section).

In some rare cases Chrome event listener has to be synchronous. For example webRequest's onBeforeRequest event accepts "blocking" flag which instructs Chrome to wait for listener's answer in a blocking call.

What happened here? We have specified our own event listener factory which is responsible for creating a new event callback function whenever chromex asks for it. The default implementation is here. This function is part of our config object, so it can be redefined during runtime. with-custom-event-listener-factory is just a convenience macro to override this config setting temporarily.

This way we get all benefits of chromex (marshalling, logging, API deprecation/version checking, etc.) but still we have a flexibility to hook our own custom listener code if needed. Please note that event listener has to return a native value. We don't have type information here to do the marshalling automatically. Also note that incoming parameters into event listener get marshalled to ClojureScript (as expected). And obviously this event won't appear on the channel unless you put! it there in your custom listener code.

Also note how we passed extra arguments for .addListener call. This was discussed in the previous section.

Advanced tip: similarly you can replace some other configurable functions in the config object. For example you can change the way how callbacks are turned into core.async channels. Theoretically you could replace it with some other mechanism (e.g. with js promises).