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:
- Hooks registered by configured modules, in
modulesorder. - Hooks registered by local
modules/*files, sorted alphabetically. - 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.