Theming

Setting up your environment

In order to theme Converse, you first need to set up a Development environment and then you’ll also want to follow the guide to Setting up a webserver.

Modifying the HTML templates of Converse

Converse uses lit-html as HTML templating library, and the HTML source code is contained in JavaScript .js files in various ./template directories in the source code.

Some top-level templates are found in the ./src/templates directory, but usually the templates that are relevant to a specific plugin will be find inside that plugin’s subdirectory.

For example: src/plugins/chatview/templates.

You can modify HTML markup that Converse generates by modifying these files.

Use webpack aliases to modify templates without changing the original files

Generally what I do when creating a modified version of Converse for a project or customer, is that I create a new JavaScript package with its own package.json and I then add converse.js as a dependency (e.g. via npm install --save converse.js) to the package.json.

Then I add a Webpack configuration and use webpack aliases to resolve template paths to my own modified files.

For example, in the webpack configuration snippet below, I add two aliases, so that the message-body.js and message.js templates can be replaced with two of my own custom templates.

resolve: {
    extensions: ['.js'],
    alias: {
    './message-body.js': path.resolve(__dirname, 'path/to/my/custom/message-body.js'),
    './templates/message.js': path.resolve(__dirname, 'path/to/my/custom/chat_message.js'),
    }
}

Modifying the CSS

The CSS files are generated from Sass files that end in .scss and which are distributed throughout the source code.

Similarly to the template files, the CSS that is relevant to a particular plugin is usually inside the ./styles directory inside the relevant plugin directory.

For example: src/plugins/controlbox/styles.

To generate the CSS you can run:

make css