cd flarum-source/extensions/akismet/js
npm install

Public API

extend (flarum/common/extend)

import { extend } from 'flarum/common/extend';

extend(
  target: object,
  method: string,
  callback: (returnValue: any, ...originalArgs: any[]) => void
): void;

Used to add behavior after an existing method runs without replacing it. The callback receives the method's return value as its first argument followed by the original arguments. Use this when you need to augment output (e.g., adding items to a list) without disrupting existing logic.

override (flarum/common/extend)

import { override } from 'flarum/common/extend';

override(
  target: object,
  method: string,
  callback: (original: (...args: any[]) => any, ...args: any[]) => any
): void;

Replaces a method entirely, receiving the original function as the first argument so it can be called conditionally. Use this when you need to intercept and potentially change the return value based on runtime conditions, such as swapping a flag reason label.

app.initializers.add

import app from 'flarum/forum/app';
// or
import app from 'flarum/admin/app';

app.initializers.add(id: string, initializer: () => void): void;

Registers a named initializer that runs when the Flarum application boots. The id must be unique (conventionally the extension's composer package name with / replaced by -). All extend/override calls for an extension are placed inside this callback to ensure the app is ready before patching.

Working examples

Scenario - Adding a custom post control item

Extend the post controls destructive list to insert a custom action when a specific flag type is present, following the akismet extension pattern.

import { extend } from 'flarum/common/extend';
import app from 'flarum/forum/app';
import type Post from 'flarum/common/models/Post';
import type ItemList from 'flarum/common/utils/ItemList';
import type Mithril from 'mithril';
import PostControls from 'flarum/forum/utils/PostControls';

app.initializers.add('my-extension', () => {
  extend(
    PostControls,
    'destructiveControls',
    function (items: ItemList<Mithril.Children>, post: Post) {
      if (items.has('approve')) {
        const flags = post.flags();
        if (flags && flags.some((flag) => flag?.type() === 'my-flag-type')) {
          const approveItem = items.get('approve');
          if (approveItem && typeof approveItem === 'object' && 'children' in approveItem) {
            (approveItem as any).children = app.translator.trans('my-ext.forum.post.custom_label');
          }
        }
      }
    }
  );
});

Scenario - Overriding a flag reason display

Override the flagReason method on the Post component to return custom text for your extension's flag type, falling back to the original for all other types.

import { override } from 'flarum/common/extend';
import app from 'flarum/forum/app';
import PostComponent from 'flarum/forum/components/Post';

app.initializers.add('my-extension', () => {
  override(PostComponent.prototype, 'flagReason', function (original, flag) {
    if (flag.type() === 'my-custom-flag') {
      return app.translator.trans('my-ext.forum.post.custom_flagged_text');
    }
    return original(flag);
  });
});

Scenario - Extending admin permission dependencies

Use the approval extension pattern to declare that granting one permission requires another to be granted first.

import { extend } from 'flarum/common/extend';
import app from 'flarum/admin/app';

app.initializers.add('my-extension', () => {
  extend(app, 'getRequiredPermissions', function (required: string[], permission: string) {
    if (permission === 'discussion.myCustomAction') {
      required.push('startDiscussion');
    }
  });
});

File walkthrough

• .github/ - GitHub Actions workflows for automated testing, linting, and publishing; not needed at runtime.
• bin/ - Contains test.sh, a convenience script to run the full test suite locally.
• extensions/ - Each subdirectory is a standalone Flarum extension with its own PHP source, JS source, locale files, and migrations.
• framework/ - The Flarum core framework; provides all base classes, components, and utilities that extensions import from flarum/*.
• js-packages/ - Reusable JS/TS packages shared across extensions (e.g., build tooling, type definitions).
• php-packages/ - Reusable PHP packages shared across extensions (e.g., testing helpers, shared utilities).
• .bundlewatch.config.json - Configures bundle size limits checked in CI to prevent asset bloat.
• .styleci.yml - Enforces PSR-2/PSR-12 PHP coding standards automatically on PRs.
• CHANGELOG.md - Tracks all changes per release across the monorepo.
• composer.json - Declares PHP dependencies and autoloading for the entire monorepo.
• flarum-monorepo.json - Tooling config for monorepo management scripts.
• package.json - Defines npm workspaces so all extension JS packages share a single node_modules.

Common pitfalls and fixes

• flarum/* imports resolve to nothing: The flarum/ path alias is only resolved by Flarum's custom webpack config; copy the webpack.config.js from any extension as your starting point rather than writing one from scratch.
• extend callback fires before app is ready: Always place extend/override calls inside app.initializers.add, never at module top level.
• Duplicate initializer IDs: Each call to app.initializers.add must use a globally unique string; collisions silently drop one initializer. Use your full package name.
• TypeScript errors on Mithril vdom types: Install @types/mithril and ensure your tsconfig.json includes "moduleResolution": "bundler" or "node16" to resolve .d.ts files correctly.
• PHP migrations not running: Flarum only discovers migrations in the path declared in your extension's extend.php; confirm the path matches your actual migrations/ directory.
• iframe-resizer not initializing in embed extension: The iframeResizer.contentWindow.js import must be the very first import in the entry file; reordering breaks the parent-frame handshake.

Vibe-coding prompt template

I have the Flarum monorepo source in the `flarum-source/` directory of my project.
I also have `USAGE.md` at the project root describing the real exports and integration patterns.

Please help me integrate Flarum extension functionality into my project step by step:

1. Read `USAGE.md` for the real exported symbols (`extend`, `override`, `app.initializers.add`).
2. Read the relevant extension source under `flarum-source/extensions/<name>/js/src/` for patterns.
3. Create a new extension entry file that uses `app.initializers.add` with a unique ID.
4. Use `extend` or `override` from `flarum/common/extend` to patch the target component or utility.
5. Wire up the webpack build using the pattern in `flarum-source/extensions/akismet/js/webpack.config.js`.
6. Do not invent any Flarum APIs; only use symbols visible in the source files and USAGE.md.

My goal: [describe your specific customization here].

License and credit

Flarum is open-source software licensed under the MIT License. See source/LICENSE.md for the full text. Upstream package: flarum monorepo. Community resources: flarum.org, Flarum Discuss.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.