Flarum/framework: the MIT PHP forum core behind Flarum forums

What the flarum/framework repository actually contains

The README opens with a warning that matters more than the feature list: "This repository contains Flarum's core code. If you want to set up a forum, visit the Flarum skeleton repository." That single line defines the audience. This is not a download-and-run forum. It is the source tree that the skeleton pulls in as a dependency.

The top-level layout confirms it. There is a composer.json for the PHP side, a package.json that declares the whole thing a private monorepo named flarum-monorepo, and directories named framework/, extensions/, js-packages/ and php-packages/. The package.json workspaces list points at framework/*/js, extensions/*/js and js-packages/*, so JavaScript from the core, from bundled extensions and from shared packages is installed and built together in one Yarn workspace tree. The repository also carries flarum-monorepo.json, phpstan.neon, .styleci.yml and a bin/ directory, which is the shape of a project that maintains many packages in one place rather than a single installable application.

So the people this serves are Flarum contributors and extension authors. If you are evaluating Flarum as forum software for a community, the README sends you to the documentation and to the skeleton repository, and the questions you care about (hosting, database, mail, upgrades) are answered there, not here.

PHP backend, Mithril frontend: how Flarum splits the work

The README describes the interface as "powered by Mithril, a performant JavaScript framework with a tiny footprint." That is the architectural decision that separates Flarum from forums that render pages server-side. The PHP layer and the JavaScript layer are two separate codebases in the same monorepo, and the workspaces in package.json exist precisely so both can be built in one pass.

The README also states that Flarum is "built with PHP so it's quick and easy to deploy" and that it has "no complex dependencies." Treat those as design intentions rather than guarantees. A monorepo with a Yarn workspace definition, a phpstan.neon, a StyleCI configuration and a bundlewatch config (the .bundlewatch.config.json entry in the repository root) is not a small tree; the claim is about what a deployed forum needs at runtime, not about what a contributor checks out.

The extensibility story is the third pillar. The README calls the architecture "amazingly flexible, with a powerful Extension API." In practice that API is why the extensions/ directory sits at the top level next to framework/: bundled extensions are developed and versioned against the core in the same repository, which is a different arrangement from a core that ships alone and leaves every add-on to a third party.

Installing Flarum: where the README sends you

There is no install command in this README. It gives no Composer line, no Docker image, no environment variables and no configuration keys. What it gives is a destination: the Flarum skeleton repository at github.com/flarum/flarum. That is the repository you clone or require when you want a working forum, and it is the one that pulls flarum/core in as a dependency.

The README does name the package, though, in its badge links: packagist.org/packages/flarum/core. That is the Composer package name for the core. If you are working inside this monorepo rather than deploying a forum, the repository root is a private Yarn workspace, and its only declared script is an audit helper:

{
    "private": true,
    "name": "flarum-monorepo",
    "workspaces": [
        "framework/*/js",
        "extensions/*/js",
        "js-packages/*"
    ],
    "scripts": {
        "audit-fix": "npx yarn-audit-fix"
    }
}

What you should take from that snippet is the scope of the workspace globs, not a setup procedure. The README does not document a build sequence for contributors, so anyone cloning this repository should read the contributing guide at docs.flarum.org/contributing before assuming a command order. For support, the README points to the documentation, to Flarum Discuss and to the project's Discord server.

The 1.x and 2.x split is the real adoption risk

The default branch is 2.x, and the recent release list shows two live lines at once: v1.8.20 published on 2026-09-17, and v2.0.0-rc.8 published on 2026-08-27, preceded by v2.0.0-rc.7 on 2026-08-24. The rc suffix means 2.x is still a release candidate, not a stable release, and the README says nothing about migrating a forum from 1.x to 2.x, about which branch is recommended for production, or about how extensions should declare compatibility with either line.

That silence is the limitation worth weighing. A forum operator on 1.8.x gets patch releases on a stable line. A contributor working from the default branch is building against a candidate. The repository does not tell you which of those two positions you are in; the release tags are the only signal.

The second constraint is the monorepo boundary itself. Because bundled extensions live in extensions/ and JavaScript packages in js-packages/, a change in this repository can move several packages at once. That is convenient for the core team and it means an extension author cannot assume the core evolves independently of the extensions shipped alongside it.

Finally, the README documents no rollback procedure, no database migration policy and no downgrade path. If you need those guarantees before adopting a candidate line, this repository does not supply them.

Flarum/framework compared with a conventional PHP forum

The clearest alternative in the PHP forum space is the classic server-rendered model, where each page request is assembled in PHP and returned as HTML. Flarum takes the opposite route: the README states the interface is powered by Mithril, so the client is a JavaScript application and the PHP side serves it. The practical difference is where complexity lands. A server-rendered forum asks more of the PHP layer and less of the browser; Flarum asks the JavaScript workspace in this monorepo to carry the interaction model, which is why js-packages/ and the bundlewatch configuration exist at all.

A second comparison point is packaging. Flarum's core is distributed as flarum/core on Packagist and consumed through a separate skeleton repository, which keeps the application template out of the core tree. Projects that ship the whole application as one Composer package put deployment and core development in the same place. Flarum's split means the README can be short, but it also means a reader who lands on this repository first has to follow a link before anything runs.

Neither arrangement is better in the abstract. The split is a good fit when you want the application skeleton to be replaceable and the core to be a dependency. It is a poor fit when you want one repository that both defines and runs the product.

Licence, maintenance and what an upgrade costs

Flarum is MIT licensed, per the README's License section and the LICENSE.md file at the repository root. MIT is permissive: it allows reuse and redistribution with the licence and copyright notice retained. That is a statement about the licence text, not legal advice about your situation; if you are embedding Flarum in a commercial product, read the licence itself and, where it matters, take your own counsel.

The repository is not archived, and the last push was on 2026-09-21. Patch releases on the 1.8 line and successive release candidates on the 2.0 line both appear in the recent release list, so both lines are receiving changes. The CHANGELOG.md at the repository root is where the project records what changed; the README does not summarise it.

Upgrade cost is where the documentation gap bites. The README does not describe an upgrade procedure, an extension compatibility matrix, or what a 1.x to 2.x move involves. Because extensions are developed inside this same monorepo, the compatibility question is not just about your own code: it is about whether the extensions you rely on have been updated for the line you are running. Anyone planning an upgrade should treat the CHANGELOG and the release tags as the primary sources, since the README is silent on the subject.

Editorial conclusion

Adopt Flarum/framework if you intend to work on Flarum itself, build extensions against its PHP and Mithril layers, or track the 2.x release candidates before a stable cut. Do not clone it expecting a running forum; the README directs forum operators to the Flarum skeleton repository, and deployment, upgrade and troubleshooting guidance lives in the documentation rather than in this README. Before committing to 2.x, check which release line your extensions declare support for, since v1.8.20 and v2.0.0-rc.8 are both current and the README documents no migration path between them.

Frequently asked questions

Official sources

1. flarum/framework on GitHub
2. License: MIT
3. Project website
4. README
5. Releases