How to extend an existing extension?

Pollux

I'm in the process of customizing Byōbu to my needs. I have a file my_extension/js/src/forum/index.js to override some other functions. In order to do that I import the relevant modules, e.g.

import DiscussionsUserPage from 'flarum/components/DiscussionsUserPage';
import addTagComposer from 'flarum/tags/addTagComposer';
import PrivateDiscussionsUserPage from 'fof/byobu/components/PrivateDiscussionsUserPage';

The first two, a core module and a module from a bundled extension, don't cause any problems, but the third one presents an error in the console:

Error: Cannot find module 'fof/byobu/components/PrivateDiscussionsUserPage'

Is this a kind of race condition? And if yes, how would I handle that?

datitisev

Pollux Extensions need to export things for other extensions to be able to use them. And most don't.

The system currently isn't great. But here's how it works. Hopefully this is helpful.

When you import from fof/byobu/components/PrivateDiscussionsUserPage, you are trying to import the file byobu/components/PrivateDiscussionsUserPage from the NPM package fof.

The webpack config has an option that you can pass called useExtensions, to which you pass an array of extension IDs (e.g. fof-byobu). The extension must export the classes before you are able to use them.

Byobu does export some things - not all (see https://github.com/FriendsOfFlarum/byobu/blob/212591a0324a2561c1fe3204aff16972404b4a3c/js/src/forum/index.js#L23-L24).

You can import those by importing from @fof-byobu (after adding it to the useExtensions setting, example @ https://github.com/FriendsOfFlarum/drafts/blob/1e967bd32093e15a3734638df3c9e471f6ed8bff/js/webpack.config.js).

That'll look something like this:

import byobu from '@fof-byobu';

extend(byobu.components.PrivateDiscussionsUserPage, ...)

import { components } from '@fof-byobu';

// use components.*

Do keep in mind that for that import to not be null, your extension must load after the one you are requiring. If you do not want this, you can use app.initializers priority (set it to -1 or something lower than 0) and use

app.initializers.extend('...', () => {
  const { components } = require('@fof-byobu');

  // ...
}, -1);

You can check out fof/drafts for an example usage @ https://github.com/FriendsOfFlarum/drafts/blob/1e967bd32093e15a3734638df3c9e471f6ed8bff/js/src/forum/components/DraftsList.js#L135

Pollux

Thank you @datitisev, that was a great help.

Since you mentioned webpack, I took a look at the output of npm run dev, which I hadn't done before, and saw the error there as well:

ERROR in ./src/forum/index.js
Module not found: Error: Can't resolve 'fof/byobu/components/PrivateDiscussionsUserPage' in '/flarum/packages/my_extension/js/src/forum'
 @ ./src/forum/index.js 5:0-89 30:11-37
 @ ./forum.js

Then I edited webpack.config.js as suggested:

module.exports = require('flarum-webpack-config')({
    useExtensions: ['fof-byobu']
});

and imported from '@fof-byobu' according to your instructions:

import { components } from '@fof-byobu';

Now npm run dev showed no more errors.

Then I tried to override PrivateDiscussionsUserPage:

override(components.PrivateDiscussionsUserPage.prototype, 'content', function () {
  return ( [...] );
});

Strangely enough, I still had an error in the console:

TypeError: _fof_byobu__WEBPACK_IMPORTED_MODULE_4__.components.PrivateDiscussionsUserPage is undefined

I included a console.log(components) in my extension and to my surprise there was no module PrivateDiscussionsUserPage. Instead, a module PrivateDiscussionUserPage was included (without the 's' at the end of 'Discussion'), and overriding Components.PrivateDiscussionUserPage.prototype worked perfectly.

But, so I thought by myself, where the heck did this 's' got lost? The filename is PrivateDiscussionsUserPage.js, the exported default class is PrivateDiscussionsUserPage.

I finally found the explanation in the file vendor/fof/byobu/js/src/forum/components/index.js:

export const components = {
    [...]
    PrivateDiscussionUserPage: PrivateDiscussionsUserPage,
    [...]
};

So here the module is exported as PrivateDiscussionUserPage.

I ask myself: Is this confusing naming on purpose?

And one more thing:

Doesn't the import of all modules from components affect performance? Is it not possible and advisible to import only the required modules?

datitisev

Pollux Oh, I don't think that name difference is intended.

Doesn't the import of all modules from components affect performance? Is it not possible and advisible to import only the required modules?

No. You aren't importing anything - webpack doesn't have access to the extension source files. The calls to @fof-byobu are replaced with flarum.extensions['fof-byobu'] - that's basically all that is happening here.

Pollux

datitisev

Thanks once more, my extension work involving Byobu worked very well.

Now I'm intending to do something else that also needs to use functionality from another extension. In particular I want to use addPostMentionPreviews.js from flarum/mentions to provide post previews in other circumstances without having to fork parts of the mentions extension.

So first I looked at the mentions extension to find out whether addPostMentionPreviews.js is exported. flarum/mentions/js/forum.js says:

export * from './src/forum';

... so I thought: great, this looks good.

Then I edited my webpack config to use the mentions extension:

module.exports = require('flarum-webpack-config')({
    useExtensions: ['flarum-mentions']
});

and tried to

import addPostMentionPreviews from '@flarum-mentions';

import { mentions } from '@flarum-mentions';

In both cases the console says Error: Cannot find module '@flarum-mentions'.

Then I looked further and found that at the end of flarum/mentions/js/src/forum/index.js only the textFormatter component is exported:

export * from './utils/textFormatter';

but even importing just textFormatter didn't work as nothing from @flarum-mentions was ever found.

So I asked myself, whether @flarum-mentions was the correct naming. I chose it mimicking your @fof-byobu, but I'm not sure it's the right way of calling the mentions ressources. Where does this name come from? Is it derived from the path replacing slashes with dashes? Does it have to follow the name in the extension's composer.json (which in this case is the same, but not in others)?

datitisev

Pollux What mentions exports is kind of like a "public API". However, it should definitely be exporting all it's files to flarum.core.compat as well (like flarum/tags) - you won't be able to access any file other than what is exported.

Your code might not be finding the specific exports because of load order. I suggest you use the dev tools and inspect flarum.extensions['flarun-mentions'].

Do remember that you may want to use require() instead of import to make sure it's available when you need it.

Hopefully this makes sense, wrote it on mobile