Over the past few years, the FoF Extension Generator has been an invaluable tool for getting started with extension development. Not needing to worry about the skeleton/structure makes diving into development much easier!
One of our core values is 'Framework First': Flarum is as much a framework for extension development as it is a forum platform. In accordance with that, we've made some changes recently:
- We released a frontend typings package:
npm install --save-dev firstname.lastname@example.org
- We released a backend testing package
- We developed an extension dependency system that also includes optional dependencies (boot after X if X is installed)
- We made several large overhauls and expansions to our docs, including reorganization, addition of undocumented topics, and translation into other languages. We're planning an
examples section, which will walk you through a step-by-step tutorial of developing some basic, representative extensions.
Today I'm pleased to announce the newest addition to this family: the Flarum development CLI. Currently it is in alpha,
as we've been focused on developing a breadth of representative functionality. So far, we've implemented several such commands, designed to show aspects of what it could eventually do:
flarum-cli init: generates a blank extension skeleton, including all recommended infrastructure
flarum-cli infra backend-testing: Adds (or updates) infrastructure for running automated backend tests
flarum-cli update js-imports: Adds admin/forum/common namespaces to all JS imports from flarum core
flarum-cli generate migration: Generates a blank migration file with proper naming in the correct location
flarum-cli generate backend event-listener: Generates a blank event listener, adds an accompanying
listen call to
Frequently when developing extensions, we find ourselves copying boilerplate files from other extensions / the documentation, and doing certain repetetive, menial tasks. So let's automate it away! Here's a roadmap for what we hope this tool will look like:
These will generate a starter extension skeleton.
These will generate a stub file, which will initially have comments pointing to relevant places in the documentation. When applicable, an extender will also be added to
These will perform some menial task related to updating Flarum extensions for a new version of Flarum.
As we add new things, extension skeletons get outdated. Updating them can be a pain. These will update infrastructure files / setup, copying straight from the init boilerplate to get you the latest version of whatever infrastructure component you're hoping to update.
Things to decide
- Could this support tools, extenders, and events exported by extensions? Theoretically speaking, if it's installed in
vendor (as it should be if using dependencies / optional dependencies properly), we might be able to discover it...
- Audit: inspect stuff that's out of date? Could have separate commands for audit and for deprecated things...
- How should we group the generate commands? Should there be separate commands for each component, or something like
flarum-cli generate frontend, which would lead to an interactive menu? Or
flarum-cli generate frontend component,
flarum-cli generate backend api-controller, etc?
- How opinionated should this be when generating stubs? I'd argue that if no path is provided, we should place things in the recommended location (listeners and subscribers in
src\Listener). If a path is provided, place it there (TODO).
- Should we shorten the name? e.g.
fl instead of
If you'd like to try this out, install it via
npm install -g flarum-cli. You can run it with
If you're interested in contributing, please comment so below! Source code is at https://github.com/flarum/flarum-cli.
At this point, the most valuable thing is feedback: did we miss anything above? Are there any menial processes you deal with when developing extensions that you would like to see automated away?