Skip to content

README.md

Latest commit

 

History

History
108 lines (80 loc) · 2.56 KB

README.md

File metadata and controls

108 lines (80 loc) · 2.56 KB

Plugins

This directory contains documentation for official Fexios plugins.

Import path

All official plugins are exported from:

import { pluginXXX } from 'fexios/plugins'
//       ↑↑↑↑↑↑↑↑↑ Replace with the real plugin you want to use

Official plugins

Creating a plugin (tutorial)

Fexios plugins are objects with a required name and install(fx) function.

1) Minimal plugin template

import { Fexios, type FexiosPlugin } from 'fexios'

export const authPlugin: FexiosPlugin = {
  name: 'auth-plugin',
  install(fx) {
    fx.on('beforeRequest', (ctx) => {
      ctx.request.headers = {
        ...(ctx.request.headers as any),
        Authorization: 'Bearer token',
      }
      return ctx
    })
  },
}

const fx = new Fexios()
await fx.plugin(authPlugin)

2) Uninstalling a plugin

If your plugin defines uninstall(fx), Fexios will call it when you uninstall:

export const demoPlugin: FexiosPlugin = {
  name: 'demo-plugin',
  install() {
    // setup...
  },
  uninstall() {
    // cleanup...
  },
}

const fx = new Fexios()
await fx.plugin(demoPlugin)

// uninstall by name or by reference
fx.uninstall('demo-plugin')
// fx.uninstall(demoPlugin)

3) Adding instance methods (TypeScript module augmentation)

Plugins can attach new methods/fields onto the Fexios instance. To make it type-safe, add module augmentation in your plugin module:

import type { FexiosPlugin } from 'fexios'

declare module 'fexios' {
  interface Fexios {
    hello: (name: string) => string
  }
}

export const helloPlugin: FexiosPlugin = {
  name: 'hello-plugin',
  install(fx) {
    fx.hello = (name) => `Hello, ${name}`
  },
  uninstall(fx) {
    fx.hello = undefined as any
  },
}

4) Hooks & lifecycle events

Inside install(fx), you can use:

  • fx.on('<lifecycleEvent>', handler) to intercept request/response lifecycle.
  • fx.interceptors.request.use(...) / fx.interceptors.response.use(...) as axios-like sugar.

Official plugins (SSE/WebSocket) also emit custom lifecycle events such as sse:beforeConnect / websocket:beforeConnect.

Runtime notes (browser vs Node.js)

  • In browsers, EventSource and WebSocket are usually available globally.
  • In Node.js, you may need to provide polyfills (set them on globalThis) before using pluginSSE / pluginWebSocket.