Upcoming versions can be built from source.
Writing Nyxt Extensions: Example of nx-search-engines

Writing Nyxt Extensions: Example of nx-search-engines

Artyom Bologov

Nyxt is an extensible browser. But how does one write an extension for it? Given that there are few extensions (as of March 2021), there isn't much existing code to learn from. That's why I've written this step-by-step guide about how to extend Nyxt.

So, here's the process you can follow:

Create a CL package and an ASDF system.

Nyxt is built in Common Lisp, so you need to follow the packaging conventions for Common Lisp programs:

It's a lot, isn't it? Fortunately, all these routines can be automated with quickproject. So, you can open up Lisp REPL and do:

And most of the work will be done for you!

Set-up your package

You'll likely need to refer to Nyxt symbols (be they names of functions, classes, or variables). Typically this can be done by using the nyxt: prefix. To avoid that, you can import the frequently used symbols from the nyxt package. In the case of nx-search-engines, I needed define-class, define-mode, define-command, and search-engine class.

Importing can be done via the package definition, together with nickname setting, symbol exporting, and package documentation. In the case of nx-search-engines, package definition looked like this:

Write the code

If you know Common Lisp, this step is straightforward – just write the extension relying on numerous Nyxt APIs (see next section about them).

If you don't know Lisp – no problem, you can always learn it and write a great extension in the process! We've put together a collection of resources that can help you in starting out: Nyxt Common Lisp Learning Recommendations.

Use Nyxt APIs

There are lots of libraries Nyxt depends on. You can freely use them. Nyxt will guarantee that they are loaded. A non-exhaustive list of libraries you can rely on:

Nyxt APIs rely on the above libraries and allow you to shorten your code and extend Nyxt in a wink:

Since we use the Common Lisp package system, you can guess the stability of the API by how it's used:

However, as it's all written in Lisp, no one restricts you from using anything you can get your hands on ;)

nx-search-engines example

In the case of nx-search-engines, I relied on the search-engine class – after all, I needed to generate Nyxt-native search engines. This is quite a simple and boring API, and yet it's sufficient to allow Lisp-customizable search engines.

Another Nyxt API that I relied upon (particularly in search-engines-mode) was element hints. The search-hint command is a follow-hint sibling. The difference is that it searches the class-dispatchable hints instead of following them. All at the cost of several method definitions and a search-hint command call! That's how it looks:

Make the extension extensible :)

Nyxt uses the Common Lisp Object System (CLOS) for everything. There are Nyxt-specific macros to make any CLOS class configurable by the user. To make your extension customizable, you need to know only two of them: define-user-class and define-mode.

define-user-class makes a class you've already defined (with defclass or define-class) configurable via define-configuration. That's the only thing you need to write to make your classes customizable:

define-mode relies on this same system with define-class, define-user-class, and define-configuration. The difference is that modes are enableable and user-facing, while other classes usually aren't. A mode is the best place to store your extensions' configuration. I've relied on this with nx-search-engines and defined search-engines-mode:

Search is the only thing nx-search-engines is concerned about. Customization of search engines to use when searching element hints is the only reasonable configuration there.

Now one can change preferred search engines like this:

Make Nyxt users happy by publishing the extension!

Now that you've written your extension, packaged it, and used all the necessary customizable APIs, you can share it with the world! Don't forget to let us know about your extension for it to be included in a list of Nyxt extensions.

Thanks for reading :3