Creating a new NodeBB Theme

NodeBB is built on Twitter Bootstrap, which makes theming incredibly simple.

Packaging for NodeBB

NodeBB expects any installed themes to be installed via npm. Each individual theme is an npm package, and users can install themes through the command line, ex.:

npm install nodebb-theme-modern-ui

The theme’s folder must contain at least two files for it to be a valid theme:

  1. theme.json
  2. theme.less

theme.less is where your theme’s styles will reside. NodeBB expects LESS to be present in this file, and will precompile it down to CSS on-demand. For more information regarding LESS, take a look at the project homepage.

Note: A suggested organization for theme.less is to @import multiple smaller files instead of placing all of the styles in the main theme.less file.

Configuration

The theme configuration file is a simple JSON string containing all appropriate meta data regarding the theme. Please take note of the following properties:

  • id: A unique id for a theme (e.g. “my-theme”)
  • name: A user-friendly name for the theme (e.g. “My Theme”)
  • description: A one/two line description about the theme (e.g. “This is the theme I made for my personal NodeBB”)
  • screenshot: A filename (in the same folder) that is a preview image (ideally, 370x250, or an aspect ratio of 1.48:1)
  • url: A fully qualified URL linking back to the theme’s homepage/project
  • templates: (Optional) A system path (relative to your plugin’s root directory) to the folder containing template files. If not specified, NodeBB will search for the “templates” directory, and then simply fall back to using vanilla’s template files.

Child Themes

If your theme is based off of another theme, simply modify your LESS files to point to the other theme as a base:

topic.less

As topic.less from the theme nodebb-theme-vanilla was imported, those styles are automatically incorporated into your theme.

Important: If you depend on another theme, make sure that your theme specifically states this in its package.json. For example, for the above theme, as we depend on nodebb-theme-vanilla, we would explicitly state this by adding a new section into the package.json file:

"peerDependencies": {
    "nodebb-theme-vanilla": "~0.0.1"
}