Getting Started With Flarum Extensions; a How-To Guide For Developers

youds

Installation

This guide gives you a project skeleton in flarum/workbench/your-project so you can begin working on the extension out of the box.

Flarum requires composer, to get setup please follow these steps:

$ php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
$ php -r "if (hash_file('sha384', 'composer-setup.php') === '48e3236262b34d30969dca3c37281b3b4bbe3221bda826ac6a9a62d6444cdb0dcd0615698a5cbe587c3f0fe57a54d8f5') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
$ php composer-setup.php --install-dir=/bin
$ mv /bin/composer.phar /bin/composer

Now, lets get Flarum up and running

$ mkdir flarum
$ cd flarum
$ composer create-project flarum/flarum . --stability=dev

Now navigate away to get the forum setup. Once finished, continue below. Back to the flarum root directory and we want to include repository in the ‘composer.json’ file.

Add in the following, after the list of required packages:

"repositories": [
    {
        "type": "path",
        "url": "workbench/*/"
    }
],

As you have specified dev version for the install, this should be just above the config directive. Next, add your package to the list of packages with the value *@dev. I’m creating an embedded plugin, so I use:

"youds/embedd": "*@dev"

Next, we need to create our folders. Run:

$ mkdir workbench
$ mkdir workbench/embedd
$ vi workbench/embedd/composer.json

Now include the following:

{
    "name": “youds/embedd”,
    "description": “Embedd Flarum Into External Sites“,
    "type": "flarum-extension",
    "require": {
        "flarum/core": "^0.1.0-dev”
    },
    "extra": {
        "flarum-extension": {
            "title": “Embedd”,
            "icon": {
                "name": "line-chart",
                "backgroundColor": "#01a6cb",
                "color": "#ffffff"
            }
        }
    }
}

Finally, for this part of the installation, run composer update on the root directory. You should see:

$ composer update

For more information on this part of the project setup, see https://discuss.flarum.org/d/1608-extension-development-using-composer-repositories-path/6

Now, wouldn’t it be nice if there was a tool to create a project skeleton for us? Just so happens there is one. Firstly, make sure node and nom are up to date.

$ npm install -g npx
$ npx @ReFlar/create-flarum-extension workbench/embedd

Fill out the questions and voila, you are now sporting a branch new Flarum Extension.

In order to get it working, so you can make edits, enter the js folder and run the following:
$ npm install -g webpack
$ npm install
$ npm run dev

clarkwinkelmann

youds nice guide, a few comments though:

We usually require specific Flarum betas in our extensions composer.json, like "flarum/core": "^0.1.0-beta.8". Unless you're actually working with Flarum dev-master in order to check your extension against the next beta, you shouldn't have a -dev dependency to core.

And second question, is this necessary ?

npm install -g webpack

npm and yarn seem to be able to run webpack just fine even if it's not installed globally on my computer.

youds

Works for me 😀

luceos

clarkwinkelmann We usually require specific Flarum betas in our extensions composer.json, like "flarum/core": "^{0.1.0-beta.8".}

It would even be wise to use the stricter exact match until stable and force yourself to tag a new version after testing it works with a new Flarum version.

youds

I’m new to both Flarum and npm/node, the above is a working workflow for new developers to follow, taken from 2 guides; the one mentioned and the GitHub box README for skeleton declaration.

I hope someone (no doubt I’ll come back to it at some point) finds it of use. Let’s get those extensions flying into production. I for one think there is massive scope.

Kind regards