Updating the UI / Theme


I’ve recently started using Mailpile and I’d like to make some updates to the user interface. Looking at the current repo, I was thinking of migrating the current default-theme folder to a stand alone repo so that anyone who wants to create a new theme (and doesn’t want to work on the back-end) can just clone the ‘theme-repo’ and start tweaking. I’m also planning on migrating the build tools from bower to something more current (since bower is end-of-life).

I’d love some feedback from anyone familiar with the project whether:

  • the above is a good idea;
  • if this is planned for in the roadmap; and
  • if there are any expected pitfalls that you might foresee.

And thanks for creating such an amazing project, I’m just sad i didn’t know about it sooner!


Hello! I’ve been wishing someone would do something like this for a long time.

Currently there’s no roadmap worth believing in, I burned out and haven’t had time for the project lately. Nobody else has replaced me… The project absolutely needs what you are proposing. I’d try and be a bit more present to support you in this effort.

I have lots of opinions on how I’d like to see this done, but I’m not a front-end developer so my ideas may not be the right ones to help make things more accessible to other front-end devs.

I think creating a separate fork is a great idea. The Mailpile code has settings hidden away which will let you activate your theme without any code changes: just set sys.path.html_theme to “your-theme” (a sibling folder next to default-theme) and it should read from there instead.

The main pitfall, is that once you start diverging from the master branch, there’s nothing to keep us in sync. The functionality of the HTML and Javascript is all in there and you’ll have to manually backport things from master if you want to stay current. And vice-versa.

Which bits are you interested in working on? The CSS/HTML? The Javascript functionality? Both?


Hey Bjarni, thanks for the quick reply!

I’ve tried Mailpile with the JS turned off and is seems its mostly responsible for UI tweaks and running the notifications, and the core of the apps functionality is provided by the python server, is that correct? If so, my plan is to work on the appearance, CSS and HTML.

So I’d start by moving from Bower to NPM and migrating the JS dependencies over without re-implementing the current JS code. After that my plan would be to update the Jinja templates to apply a standardized UI language e.g. Github Primer (https://primer.style/css) or Google Material. I’ve used Primer for internal tools in the past and think it would work well here.

The upside / downside would be that my Mailpile theme would look identical to GitHub. To me that would be a positive since I find the GitHub UI very well designed and intuitive. However, that would result in some ‘blandness’. I"m hoping that moving to a fairly well known CSS design system would then allow anyone else who wants to play with the look and feel to be able to focus on that, without having to worry about the rest of the project.

Regarding the API between the main app and the UI, I understand the entire app to be constructed of endpoints that can either reply with JSON or HTML (via Jinja). So there would be breaking changes if either:

  • Any of the variables supplied to the Jinja templates was removed; or
  • The structure of the data returned by the Json api changed.

I’ll be starting with (and focused mainly on) the main page where you can see a list of all the emails, is the API for this page quite stable?


Our Javascript/Python philosophy was roughly that the app should be functional “read-only” without Javascript, but relying on Javascript for “writing” (composing, changing settings, sending e-mail, etc.) was OK.

Your plan sounds good, although I would hope it could immediately be followed by an effort to port the current look to the new system. I wouldn’t make that a requirement though, someone else can do that if you’re not interested.

Your understanding is mostly correct - you will also get breaking changes if you change the HTML so that the Javascript methods no longer find what they are looking for. I suspect this will be the trickiest part of your effort, untangling which structure/tags/classes are use by JS and which are not.

Since not much development has been happening, the API of most pages can be considered is quite stable. :wink:


Great, thanks.

I’m going to start on moving the theme to NPM and I’ll let you know when I get to some tangible results. Then I’ll evaluate the next steps.

Thanks for all the info!