Migration Guide - Luakit

# Luakit Documentation / Pages / Migration Guide

# Migration Guide

## Migrating from version 2017-08-10

### Remove unique instance code from `rc.lua`

Unique instance support has been moved to a module. To update, follow these steps:

1. Remove the two `if unique then ... end` blocks from your `rc.lua`.
2. Add `require "unique_instance"` to your `rc.lua`, before all other `require` statements.

### Move `globals` settings to `rc.lua`

The `globals.lua` configuration file has been removed. In its place is the new `settings` module, which provides a central place to set settings with validation and domain-specific setting support.

All modified fields of the `globals` table need to be migrated to equivalent settings. When starting luakit, a warning will be logged for each setting that must be migrated, showing the new code for that setting.

### Remove old configuration files

The `window.lua`, `webview.lua`, and `webview_wm.lua` configuration files have been made core modules, and any configuration files are ignored.

If you have made extensive changes to these files, please open an issue on the luakit GitHub repository to discuss adding new APIs to support your changes. As an interim solution, you can still override the core modules by modifying the `package.path` variable; note that this is not officially supported, and unless you carefully keep your modified files synchronized with new changes, unpredictable errors may result.

## Migrating from a pre-WebKit2 Version

The latest luakit release is built around the WebKit 2 APIs. Changes in the APIs provided by WebKit have necessitated some corresponding changes in luakit's APIs, and as a result there have been many breaking changes.

### Remove any existing personal configuration

Luakit's configuration file has seen many changes; as a result, you are likely to encounter errors unless you remove any personal configuration for a previous luakit version. You may wish to back up your configuration if you have made extensive changes; such changes can then be merged in to the up-to-date configuration.

Note: It is inadvisable to copy luakit's entire system configuration directory to make a personal copy, as was previously encouraged. This makes it harder for you to upgrade luakit, as you have more files to merge upstream changes into, and you are more likely to experience errors caused by such upstream changes (until those changes are merged with your personal configuration).

### Migrate personal key bindings

The `binds.lua` and `modes.lua` configuration files have been removed. It is no longer necessary to copy the entire set of key bindings to your configuration to change or add just a few key bindings. Instead, use `add_binds` and `remove_binds` to add and remove key bindings.

### Remove use of `module()` in scripts

Lua's `module()` function sets a global variable of the same name as the module, which pollutes the global namespace for all Lua code. A recent effort was made to remove all usage of `module()` within Luakit. While `module()` is still accessible, its use is not advised.

This has the side effect that many variables once assumed globally accessible must now be retrieved with a call to `require()`.

### Remove use of `init_funcs`

The `window` and `webview` classes previously had a method of registering functions to be called when a new window or webview was created, called `init_funcs`. This has been removed entirely in favor of a signals-based approach, which does not run the risk of name collision.

The `window` and `webview` classes now emit the `"init"` signal. To replace any functions previously registered via `init_funcs`, add a signal handler:

    webview.add_signal("init", function (view)
        -- Do something with new view
    end)

One important difference between the `"init"` signal and the `init_funcs` method is that the former no longer passes the current window table `w` as a parameter. This is because views may be moved between windows (for example, with the `:tabdetach` command).

The `window` class also emits a `"build"` signal before emitting the init signal. This provides an opportunity for modules to change the layout and arrangement of widgets within the window, before the `"init"` signal is emitted.

### Remove use of `local capi` table

Some old code wraps references to several builtin variables in a `capi` table. This does `not` namespace the builtin variables wrapped in this manner; they are still globally accessible (and otherwise could not be wrapped in this fashion), and so all this accomplishes is the addition of more code, more indirection, and confusion about luakit's and Lua's namespacing rules, for no actual advantage.

As such, it is advised to remove any such wrapper tables, and reference the globally-accessible builtin luakit libraries directly.

### Use `styles` module instead of `user_stylesheet_uri`

The `styles` module offers a replacement for the old `user_stylesheet_uri` property, which was used to set a stylesheet to customize web behavior. This module has a number of advantages over the old method, including the ability to enable/disable stylesheets at runtime, the ability to have multiple stylesheets, and the ability to use `@-moz-document` rules in your stylesheets.

1. Ensure the `styles` module is enabled in your `rc.lua`.
2. Locate the `styles` sub-directory within luakit's data storage directory. Normally, this is located at `~/.local/share/luakit/styles/`. Create the directory if it does not already exist.
3. Move any CSS rules to a new file within that directory. In order for the `styles` module to load the stylesheet, the filename must end in `.css`.
4. Make sure you specify which sites your stylesheet should apply to. The way to do this is to use `@-moz-document` rules. The Stylish wiki page Applying styles to specific sites may be helpful.
5. Run `:styles-reload` to detect new stylesheet files and reload any changes to existing stylesheet files; it isn't necessary to restart luakit.