Add extension documentation #743

extension/README.md

@@ -1,3 +1,109 @@
-# @pigallery2/extension-kit
+# pigallery2 Extension
 
-TODO.
+See feature issue for more information: [#743](https://github.com/bpatrik/pigallery2/issues/743).
+
+See sample extension at https://github.com/bpatrik/pigallery2-sample-extension.
+
+# Extension Usage
+
+Extension folder can be set through config. For the docker-ised version,
+they live under the `config/extension` folder in their own subdirectory. 
+
+# Extension development
+
+## Minimal setup
+
+You need at least a `server.js` in your extension folder that exports a `init(ext) {}` function.
+
+## Recommended setup
+
+```
+<path to the extension fodler>/myextension/package.js <- this is optional. You can add extra npm packages here
+<path to the extension fodler>/myextension/server.js <- this is needed
+```
+Where `<path to the extension fodler>` is what you set in the config and `myextension` is the name of your extension.
+Note: you do not need to add your `node_modules` folder. The app will call `npm intall` when initializing your extension.
+## Extension environment
+
+The app runs the extension the following way:
+* It reads all extensions in `<path to the extension fodler>/**` folder
+* Checks if `package.js` is present. If yes installs the packages
+* Checks if `server.js` is present. If yes, calls the `init` function.
+
+### Init and cleanup lifecycle
+There is also a `cleanUp` function that you can implement in your extension.
+The app can call your `init` and `cleanUp` functions any time.
+Always calls the `init` first then `cleanUp` later.
+Main use-case: `init` is called on app startup. `cleanUp` and `init` called later when there is a new config change.
+
+## Extension interface
+
+The app calls the `init` and `cleanUp` function with a `IExtensionObject` object.
+See https://github.com/bpatrik/pigallery2/blob/master/src/backend/model/extension/IExtension.ts  for details.
+
+
+`IExtensionObject` exposes lifecycle events, configs, RestAPis with some limitation.
+Changes made during the these public apis you do not need to clean up in the `cleanUp` function.
+App also exposes private `_app` object to provide access to low level API. Any changes made here needs clean up.
+
+## server.js
+
+See sample server.js at https://github.com/bpatrik/pigallery2-sample-extension.
+
+It is recommended to do the development in `ts`, so creating a `server.ts`. 
+Note: You need to manually transpile your `server.ts` file to `server.js` as the app does not do that for you.
+This doc assumes you do the development in `ts`.
+
+### server.ts
+
+You can import package from both the main app package.json and from your extension package.json.
+To import packages from the main app, you import as usual.
+For packages from the extension, you always need to write relative path. i.e.: prefix with `./node_modules`
+```ts
+// Including dev-kit interfaces. It is not necessary, only helps development with types.
+// You need to prefix them with ./node_modules
+import {IExtensionObject} from './node_modules/pigallery2-extension-kit';
+
+// Including prod extension packages. You need to prefix them with ./node_modules
+// lodash does not have types
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore
+import * as _ from './node_modules/lodash';
+
+// Importing packages that are available in the main app (listed in the packages.json in pigallery2)
+import {Column, Entity, Index, PrimaryGeneratedColumn} from 'typeorm';
+```
+
+
+####  pigallery2 extension dev-kit
+
+It is recommended to use the `pigallery2-extension-kit` node package.
+`npm install pigallery2-extension-kit --save` to your extension.
+
+`pigallery2-extension-kit` contains the type definitions and enums for the app.
+This node package is basically includes the all definitions of the app and exports the `IExtensionObject` that the `init` function receives.
+
+You can then `import {IExtensionObject} from './node_modules/pigallery2-extension-kit';`
+
+See https://github.com/bpatrik/pigallery2/blob/master/src/backend/model/extension/IExtension.ts to understand what contains `IExtensionObject`.
+
+NOTE: this is not needed to create an extension it only helps your IDE and your  development. These type definitions are removed when you compile `ts` to `js`.
+
+#### `init` function
+
+You need to implement the `init` function for a working extension:
+
+```ts
+
+export const init = async (extension: IExtensionObject<void>): Promise<void> => {
+
+}
+```
+
+#### pigallery2 lifecycle `events`
+
+Tha app exposes multiple interfaces for the extensions to interact with the main app. `events` are one of the main interfaces.
+Here are their flow:
+
+
+![events_lifecycle](events.png)

extension/events.drawio

@@ -0,0 +1 @@
+<mxfile host="app.diagrams.net" modified="2023-11-25T15:41:12.760Z" agent="5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36" etag="2TdW26wLRN6yi1qc34DG" version="20.2.7" type="device"><diagram id="9mL0kDflCIzzHydUxYXW" name="Page-1">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</diagram></mxfile>