Defer loading JavaScript in Themes and Components

Thanks to @david we have a very clean pattern for “eager” loading JavaScript in themes.

This means you just put *.js.es6 files into the javascripts directory and it works exactly like plugins do, this is glorious.

For example this is how you do an initializer now, which has 100% parity with plugins:

  • Create a file called /javascripts/discourse/initializers/my-init.js.es6
import { withPluginApi } from "discourse/lib/plugin-api";

function initialize(api) {
  // init via api here

export default {
  name: "discourse-otp",

  initialize() {
    withPluginApi("0.8.28", initialize);

This is an enormously important feature cause we can now split up large complex themes into a lot of pieces, get linting, syntax highlighting and all the good stuff.

However, in some cases we may want to optionally ship a JS payload.

For example, say we are decorating posts, but only posts with very specific markdown. There is no point downloading a 100KB fancy library till we know we are going to use it.

I worked around this in my component following this fancy change:


import loadScript from "discourse/lib/load-script";

function generateOtp($elem) {
  loadScript(settings.theme_uploads.jsotp).then(() => {
     // stuff goes here

This meant

  1. I needed to add .js to theme authorized extensions
  2. I needed to add a bypass to the CSP for the particular asset in content security policy script src
  3. I needed to name the asset in my about.json

As a theme component writer, this is just too much friction cause you have no chance in the distribution game requiring this level of ninja.

I am thinking to make this usable there are 2 alternatives we can pick from

  1. We can teach the system to auto CSP the .js assets in active themes and by default allow themes to upload .js

  2. We can shift towards something like javascript_cache that non defer theme js uses.

I am kind of leaning on 1 cause adding .js to theme authorized extensions seems trivial and auto CSP should not be impossible.

@pmusaraj / @Johani / @Osama any thoughts here?


The ability to reference theme uploads in JS is a great addition! :100:

This makes a lot of sense to me because anything you can do in a .js file can already be done in files in the javascripts folder of the theme. So, I don’t see any harm in allowing themes to have .js uploads by default.


Reviving this because the only thing left here is to teach CSP to allow theme js uploads. js files have been default-allowed as theme uploads for a while now.

If theme js uploads are not blocked by CSP, then components like Image Annotator - Allows you to annotate images in the previewer won’t need to load their dependencies on the homepage (~170kb gzip). That component, for example, will only need to load those dependencies if the composer is opened. Plus, it never needs to load them to anon viewers.

Also, this change would “allow” themes to have web worker files that can do some heavy lifting off the main thread.

Allow in quotes above because you can have them as blobs, but it’s much nicer to have them in separate files instead of messing around with javascript in a string.


I have some good news here, it is a bit gnarly to implement but at last we are going to support local JS assets for cases when we want to use web workers in theme components.

There is no other clean way to push this through the CSP, serving worker files from the same domain resolves the giant hole here.


Note… this has now shipped :confetti_ball: