flarum/framework · error · Error

@flarum/jest-config could not locate Flarum core. Expected…

Error message

@flarum/jest-config could not locate Flarum core. Expected a Composer-vendored copy at `vendor/flarum/core/js`, or the `@flarum/core` package (inside the monorepo). Run `composer install` so `flarum/core` is present, then try again.

What it means

@flarum/jest-config's resolveCoreDir() locates Flarum core JS by trying a Composer-vendored copy at vendor/flarum/core/js and then require.resolve('@flarum/core/package.json'); if both fail it throws this Error. The package needs core's js source to configure the Jest transform/JSM environment. It can only run inside a Flarum install or the monorepo.

Solutions

  1. Run `composer install` in the Flarum root so vendor/flarum/core (including its js directory) exists
  2. In the monorepo, ensure js-packages/@flarum/core is present/resolvable from your working directory
  3. Run your tests from the Flarum project root (cwd) rather than an unrelated directory
  4. If vendoring manually, create vendor/flarum/core/js as a valid copy of core's js folder

Example fix

// before
$ npx jest # fails: no vendor/flarum/core
// after
$ composer install
$ npx jest
Defensive patterns

Strategy: validation

Validate before calling

const fs = require('fs');
if (!fs.existsSync('vendor/flarum/core/js/package.json')) { throw new Error('Run composer install first'); }

Try / catch

try { const core = resolveCoreDir(); } catch (e) { console.error('Flarum core missing — run composer install'); process.exit(1); }

Prevention

When it happens

Trigger: Running jest with @flarum/jest-config outside a project where flarum/core is installed: missing `composer install` in a Flarum root, running the package from an isolated npm project, or a repo where @flarum/core isn't linked/vendored.

Common situations: Fresh clone of a Flarum extension where composer dependencies were never installed; CI that only ran npm/yarn and skipped Composer; a moved or renamed vendor directory.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

AI-assisted analysis of flarum/framework@4b939f6853 (2026-09-15). Data as JSON: /api/errors/5ade6de4c97b7b60. Report an issue: GitHub.

Appendix: source

Thrown at js-packages/jest-config/index.cjs:60

  // test is the authority on where its own core lives, and this is checked
  // relative to the extension (cwd), not to where this package happens to sit.
  //
  // `cwd` is the directory jest runs from — the extension's `js` dir for a
  // typical layout — so look for the vendor path from there and from its
  // parent (extensions keep `vendor/` beside `js/`, not inside it).
  for (const base of [cwd, path.resolve(cwd, '..')]) {
    const vendored = path.resolve(base, 'vendor/flarum/core/js');

    if (fs.existsSync(vendored)) {
      return vendored;
    }
  }

  try {
    // Monorepo (or any install where @flarum/core resolves as a package).
    return path.dirname(require.resolve('@flarum/core/package.json', { paths: [cwd, __dirname] }));
  } catch (e) {
    throw new Error(
      '@flarum/jest-config could not locate Flarum core. Expected a Composer-vendored copy at ' +
        '`vendor/flarum/core/js`, or the `@flarum/core` package (inside the monorepo). Run ' +
        '`composer install` so `flarum/core` is present, then try again.'
    );
  }
}

module.exports = (options = {}) => {
  const cwd = process.cwd();
  const coreDir = resolveCoreDir(cwd);

  return {
    testEnvironment: 'jsdom',
    extensionsToTreatAsEsm: ['.ts', '.tsx'],
    // Everything is transformed by babel-jest, which understands Flarum's
    // Mithril-flavoured JSX (pragma `m`). We force `@babel/preset-env` to emit
    // ES modules (`modules: false`) so the output matches
    // `extensionsToTreatAsEsm` — the shared babel config defaults to `auto`,

View on GitHub (pinned to 4b939f6853)