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 flarum@0.1.0-beta.16
- 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 infrastructureflarum-cli infra backend-testing: Adds (or updates) infrastructure for running automated backend testsflarum-cli update js-imports: Adds admin/forum/common namespaces to all JS imports from flarum coreflarum-cli generate migration: Generates a blank migration file with proper naming in the correct locationflarum-cli generate backend event-listener: Generates a blank event listener, adds an accompanying Extend\Event extender listen call to extend.php
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:
Command Roadmap
Init
These will generate a starter extension skeleton.
Generate
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 extend.php.
Frontend components:
Backend components:
Testing
Other:
Update
These will perform some menial task related to updating Flarum extensions for a new version of Flarum.
Infra
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.
Internal Improvements:
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 flarum-cli?
Next Steps
If you'd like to try this out, install it via npm install -g flarum-cli. You can run it with flarum-cli.
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?
