How to Fork and Deploy a NodeBB Custom Theme to Heroku


NodeBB uses custom themes, but expects them to be installed as an npm dependency. And here we have a problem. Who wants to make a npm package for some client's one-off theme? I prefer to version the theme directly in the repo, less confusing for future developers. But only you, reader, may truly judge if this process is preferable. In for a penny, in for a pound. And so it goes.

In this tutorial, we will fork a NodeBB theme, version it in our repo, use yarn link on Heroku so NodeBB includes our theme in the build, and then use yalc to avoid the error   npm ERR! 404 Not Found - GET - Not found. In the end, we will have our theme versioned in the repo rather than existing as a separate dependency.

We will use nodebb-theme-persona as our starter.

mkdir src/themes
cp node_modules/nodebb-theme-persona  src/themes/nodebb-theme-persona-mytheme

Now, search and replace nodebb-theme-persona with nodebb-theme-persona-mytheme in your codebase. Also caps-sensitive replace Persona with Persona Mytheme.

Here's docs on yarn link and a tutorial on yalc. I suggest reading them before executing these commands!

cd src/themes/nodebb-theme-persona-mytheme
# install yalc globally and locally
yarn global add yalc
yarn add yalc -D
# now link and publish
yarn link
yalc publish
cd ../../../
yarn link nodebb-theme-persona-mytheme
yalc add nodebb-theme-persona-mytheme

Now, you can install Persona Mytheme on your local NodeBB.

Next, you'll need to make sure yarn link and yalc publishpr gets run on Heroku.

mkdir scripts
touch scripts/
chmod u+x scripts/

Add this to

# to fix
npm install yarn
yarn link
cd $ROOT
yarn link $THEME_NAME

Append this script this to your Procfile (full Procfile below, what's appended is ./scripts/ && )

web: ./scripts/ && node loader.js --no-daemon

Commit it, and you'll get a bunch of linter errrors.

Add some of your libraries to you .eslintignore file


Add .eslintignore with git add, and then push to Heroku, and install your theme!

Remember, you won't see any changes you make to the them until after you run ./nodebb build.

About the Author

Hi. My name is Jeremiah John. I'm a sf/f writer and activist.

I just completed a dystopian science fiction novel. I run a website which I created that connects farms with churches, mosques, and synagogues to buy fresh vegetables directly and distribute them on a sliding scale to those in need.

In 2003, I spent six months in prison for civil disobedience while working to close the School of the Americas, converting to Christianity, as one does, while I was in the clink.