Hooks and modules

Extend builds with lifecycle hooks, modules, aliases, and generated files.

#

Hooks and modules extend a build without replacing the bundler. Use them for generated files, shared entrypoints, aliases, and manifest or diagnostic adjustments.

Hooks

#
import { defineConfig } from 'addonova';

export default defineConfig({
  entrypoints: { background: 'src/background.ts' },
  hooks: {
    'entrypoints:resolved': ({ addEntrypoint }) => {
      addEntrypoint('shared', 'src/shared-entry.ts');
    },
    'build:publicAssets': ({ assets }) => {
      assets.push({
        path: 'generated/config.json',
        contents: '{"ok":true}',
      });
    },
    'build:manifestGenerated': ({ manifest }) => {
      manifest.description = 'Generated by Addonova';
    },
  },
});
Hook Payload Purpose
config:resolved { config } Inspect resolved configuration.
entrypoints:found { config, entrypoints, addEntrypoint, removeEntrypoint } Adjust entrypoints after discovery and module setup.
entrypoints:resolved { config, entrypoints, addEntrypoint, removeEntrypoint } Final entrypoint pass before the build.
build:publicAssets { config, browser, outdir, assets } Add generated files.
build:manifestGenerated { config, browser, manifest, diagnostics } Inspect or mutate the manifest.
build:done { config, reports } Run after every target build.
dev:reload { config, target, manifestVersion, reason } Observe successful dev rebuilds.

Hook order

#

Hooks run sequentially:

  1. Hooks registered by configured modules, in modules order.
  2. Hooks registered by local modules/* files, sorted alphabetically.
  3. Hooks declared in the project configuration.

A failing hook stops the build with ADDONOVA_HOOK_FAILED, including the hook name, owner, and original cause.

Diagnostics

#

Hooks can append manifest diagnostics:

export default defineConfig({
  hooks: {
    'build:manifestGenerated': ({ diagnostics }) => {
      diagnostics.push({
        code: 'ADDONOVA_MANIFEST_INVALID_FIELD',
        severity: 'warning',
        message: 'Custom manifest check',
      });
    },
  },
});

Diagnostics with severity error fail the build.

Modules

#
import { defineAddonovaModule } from 'addonova';

export default defineAddonovaModule({
  name: 'shared-ui',
  setup({ hooks, addEntrypoint, addAlias, addFile }) {
    addEntrypoint('shared', 'src/shared-entry.ts');
    addAlias('@shared', './src/shared');
    addFile('generated/module.json', '{"source":"module"}');

    hooks.on('build:manifestGenerated', ({ manifest }) => {
      manifest.author = 'shared-ui';
    });
  },
});

Registration

#
export default defineConfig({
  modules: [
    'addonova-module-example',
    ['addonova-module-configured', { feature: true }],
  ],
});

modules accepts a module object, a package name, or a [package, options] tuple. Configured modules run first, in array order.

Local modules

#

Files under the top-level modules/ directory are discovered automatically:

modules/
├── 10-shared.ts
├── 20-icons.ts
└── auth.ts
  • Supported extensions: .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts.
  • Files are sorted by file name.
  • Files starting with . or _, declaration files, and *.test.* or *.spec.* files are ignored.
  • Nested directories are not scanned.

Module API

#
Member Signature Purpose
defineAddonovaModule ({ name, configKey?, setup }) Editor types for a module definition.
addEntrypoint (name, input, options?) Add an entrypoint.
addAlias (name, target) Add a bundler alias.
addFile (path, contents) Emit a generated file into every target.
hooks.on (event, handler) Register a lifecycle hook.
configKey string Read module options from a config field.

addAlias() resolves targets starting with ./, ../, or an absolute path from the project root. Other targets are package specifiers.

addFile() paths must stay inside the output directory.

Errors

#
Code Meaning
ADDONOVA_MODULE_LOAD_FAILED The module could not be imported.
ADDONOVA_MODULE_INVALID The default export is not a valid module.
ADDONOVA_MODULE_SETUP_FAILED setup() threw.
ADDONOVA_MODULE_DUPLICATE Two modules use the same name.

Next: Runtime and browser API.

Edit this page on GitHub