Spaces:
Sleeping
Sleeping
File size: 2,696 Bytes
61d39e2 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 |
# Puter Backend Extensions
## What Are Extensions
Extensions can extend the functionality of Puter's backend by handling specific
events or importing/exporting runtime libraries.
## Creating an Extension
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](../../../../doc/self-hosters/config.md)
by setting `mod_directories` to an array of valid locations.
The `mod_directories` parameter has the following default value:
```json
["{repo}/mods/mods_enabled", "{repo}/extensions"]
```
### Events
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:
```javascript
// 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' });
});
```
### Puter Extension Imports
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`:
```javascript
const { kv } = extension.imports('data');
kv.set('some-key', 'some value');
```
#### The `data` import
The data import makes it possible to access Puter's database, persistent
key-value store, and in-memory cache.
- [Read more about the 'data' import](./builtins/data.md)
### Adding Features to Puter
- [Implementing Drivers](./pages/drivers.md)
## Extensions - Planned Features
Extensions are under refactor currently. This is the checklist:
- [x] Add RuntimeModule construct for imports and exports
- [x] Add support to implement drivers in extensions
- [ ] Add the ability to target specific extensions when
emitting events
- [ ] Add event name aliasing and configurable import mapping
- [ ] Extract extension loading from the core
- [ ] List exports in console
|