src/backend/doc/extensions/README.md
Extensions can extend the functionality of Puter's backend by handling specific events or importing/exporting runtime libraries.
The easiest way to create an extension is to place a new file or directory under
the extensions/ directory immediately under the root directory of the Puter
repository. If your extension is a single .js file called my-extension.js it
will be implicitly converted into a CJS module with the following structure:
extensions/
|
|- my-extension/
|
|- package.json
|- main.js
The location of the extensions directory can be changed in
the config file
by setting mod_directories to an array of valid locations.
The mod_directories parameter has the following default value:
["{repo}/mods/mods_enabled", "{repo}/extensions"]
The primary mechanism of communication between extensions and Puter,
and between different extensions, is through events. The extension
pseudo-global provides .on(fn) to add event listemers and
.emit('name', { arbitrary: 'data' }) to emit events.
To try working with events, you could make a simple extension that emits an event after adding a listener for its own event:
// Listen to a test event called 'test-event'
extension.on('test-event', event => {
console.log(`We got the test event from ${sender}`);
});
// Listen to init; a good time to emit events
extension.on('init', event => {
extension.emit('test-event', { sender: 'Quinn' });
});
Your extensions may need to invoke specific actions in Puter's backend
in response to an event. Puter provides libraries at runtime which you
can access via extension.imports:
const { kv } = extension.imports('data');
kv.set('some-key', 'some value');
data importThe data import makes it possible to access Puter's database, persistent key-value store, and in-memory cache.
DEVCONSOLE=1 is set (e.g. npm run dev), the dev-console extension registers a UNIX socket (dev.sock) so you can run backend commands (see CommandService) from a terminal. See Backend – dev socket.Extensions are under refactor currently. This is the checklist: