Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/artrz/thunderbird-theme-builder

Eases Thunderbird Themes creation using Node
https://github.com/artrz/thunderbird-theme-builder

Last synced: about 1 month ago
JSON representation

Eases Thunderbird Themes creation using Node

Host: GitHub
URL: https://github.com/artrz/thunderbird-theme-builder
Owner: artrz
License: gpl-3.0
Created: 2024-08-21T00:27:04.000Z (5 months ago)
Default Branch: main
Last Pushed: 2024-09-17T03:51:29.000Z (4 months ago)
Last Synced: 2024-09-17T06:30:52.301Z (4 months ago)
Language: TypeScript
Size: 355 KB
Stars: 1
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE

Awesome Lists containing this project

README

# Thunderbird Theme Builder

The Theme Builder allows to create themes easily by parsing a config file and generating
an XPI file from it. It can also append a custom css file for theme experiment settings.

## Installation

`npm install -D https://github.com/artrz/thunderbird-theme-builder`

## Quick start

Run `npx tbtb init` to create the base files:

- src/themeConfig.js - Where the colors are defined.
- src/themeCustomStyles.scss - For adding and overriding rules.
- src/build.js - Script to build the theme.

Execute `node src/build.js` to create the theme.

## files, file structure and building process overview

At its bare minimum, a buildable theme is constituted of three files, `themeConfig.js`
containing the theme configuration, `build.js` containing the build instructions and
`package.json` where some (or all the) theme properties are obtained.

There isn't a fixed file structure as every file name or path can be configured so
the actual file structure can depend on the theme complexity. If the theme contains
too many style rules, multiple stylesheets can be used. If the theme will also use images,
an assets directory with the required resources can be configured too.

Simple theme with custom css file. This structure is generated by init command.
```
project-root
├── src
│ ├── build.js
│ ├── themeConfig.js
│ └── themeCustomStyles.scss
└── package.json
```

Simple theme, no custom css file.
```
project-root
├── src
│ ├── build.js
│ └── themeConfig.js
└── package.json
```

Complex theme:
```
project-root
├── assets
│ └── account_watermark.svg
├── src
│ ├── styles
│ │ └── colors.scss
│ │ └── ui.scss
│ ├── build.js
│ └── themeConfig.js
└── package.json
```

Finally, to build the theme some properties are required. Some of them are for the theme manifest file
and others to specify where the theme source files are located.
While most properties can be transparently obtained from the default `package.json` or have sane defaults,
you may want to customize them. This can be done inside the package JSON file or in the build file.

## Main theme's configuration files

### themeConfig.js

This file contains the main theme configuration, an object with three properties: `color_scheme`, `theme_colors` and `theme_experiment_colors`.
The values from `color_scheme` are inserted in `theme_colors` and in `theme_experiment_colors`, and also added as style variables so they can be on any stylesheet.

```js
module.exports = {
// This is where the custom colors are defined. You can use any string as key name.
color_scheme: {
color_foo: '#2E3440', // Will be available as var(--color_foo)
color_bar: '#3B4252', // Will be available as var(--color_bar)
// ...
},

// This is where the theme colors are configured. Use the color names from the `color_scheme` property.
// All the available elements are inside the autogenerated file.
theme_colors: {
// ...
frame: 'color_foo',
frame_inactive: 'color_bar',
popup: 'color_foo',
// ...
},

// Besides configuring the available elements it's also possible to override variables used in the application. This is where you can override the values. Find them using the developer toolbox.
theme_experiment_colors: {
// ...
'--primary-color': 'color_foo',
'--button-primary-text-color': 'color_bar',
// ...
},

// Using the images property it's possible to configure images to include in the theme.
// For this to work the assets directory must be configured on the build properties.
images: {
theme_frame: 'frame_image.png',
}
};
```

### themeCustomStyles.scss

This is an empty file where you can add your custom styles.
The theme builder supports CSS, SCSS and SASS files. If you prefer to use a different file type, besides changing the file extension
you need to update the filename in the build properties.
It's also possible to use custom images as part of the styles.

```css
body {
background-color: var(--color_foo); /* defined in color_scheme.color_foo */
}
.overridden-class {
background-image: url('my_file.png');
}
```

### build.js

Use this file to build the theme. Easiest way is by adding a NPM script in package.json to run it:

```json
{
"scripts": {
"build": "node src/build.js"
}
}
```

## Theme properties

When building the theme there are some properties required in order to create the theme's manifest file.

### Configuring / overriding properties

There are two ways to set/override the theme properties, by adding the values inside package.json
or by setting them as a parameter in the build script.

#### Configuring in package.json

Properties must be added inside `extra.thunderbird`:

```json
{
"extra": {
"thunderbird": {
...
}
}
}
```

#### Configuring as build parameter

Add an object containing the properties to configure as second parameter of the build function call:

```js
// build.js
...
build(theme, {
...
});
```

### Default properties from package.json

A big part of the theme properties can be actually obtained from the project's package file:

- `name`: used to generate the default theme id: `${name}@addons.thunderbird.net` and as the theme name fallback if `displayName` is not defined.
- `displayName`: used as the theme name.
- `version`: used as the theme version.
- `description`: used as the theme description.
- `author.name`: used as the author's name.
- `author.url`: used as the author's home page.

### Complimenting the default properties

There are two values which cannot be obtained from the default package.json structure:
the theme id and the minimum required Thunderbird version.
The following object shows how to configure them:

```js
{
themeId: '[email protected]',
thunderbirdMinVersion: '128.0',
}
```

### Configuring file locations properties

If your theme uses a different file structure you may need to reconfigure some location properties:

```js
{
// `Dir` suffixed props are relative to root
srcDir: 'source',
outDir: 'dist',
assetsDir: 'source/assets',
stylesPath: 'styles' // styles refers to a subdirectory. Relative to `srcDir`.
}
```

A note on `stylesPath`: This property supports a string or an array of strings. Every string in turn can
refer to a file or a directory. When a string points to a directory, every CSS, SCSS and SASS file will
be processed in alphabetical order.

### Full properties object

```js
{
name: undefined, // The theme name.
version: undefined, // The theme version. Eg: 1, 1.0, 1.0.0.
themeId: undefined, // The theme id.
author: {
name: undefined, // The author name.
url: undefined, // The author website.
},

thunderbirdMinVersion: '115.0', // The minimum Thunderbird version required for the theme.

srcDir: 'src', // Where the source files are located.
outDir: 'build', // Where the XPI file is going to be placed.
assetsDir: undefined, // Where the assets are going to be placed.
stylesPath: undefined, // Location of the custom styles, relative to `srcDir`.
}
```

Even though any property can be defined/overridden is best advised to fully configure the package.json file
and let the package get the information from there.

Note on the manifest version: currently it's not possible to configure it, and is always set as version 2.

### Images

There are two ways to use images: setting images as resources for the theme and using them as part of the custom styling.
After configuring the assets directory and placing the images there, all of them are going to be copied to the root directory of the theme
so to refer to them it's only required to use their filename.

## Build

The package exposes a single function that needs to be called to build the theme. The simplest way to
generate the theme is by running the build.js file. If the build script was added as previously suggested,
after configuring the theme colors and style file just run `npm run build` to generate the theme.

## Examples

See [Nord Hardt](https://github.com/artrz/thunderbird-nord-hardt-theme) for an actual example.