Plugin Development

On this page 15

stx provides a comprehensive plugin system that allows you to extend the framework's functionality. This guide covers how to create, distribute, and maintain stx plugins.

Plugin Architecture

Basic Plugin Structure

export interface MyPluginOptions {
  enabled?: boolean
  apiKey?: string
  customSettings?: Record<string, any>
}

export class MyPlugin {
  constructor(private options: MyPluginOptions = {}) {}

  install(app: stxApp) {
    // Plugin initialization logic
    app.provide('myPlugin', this)
    app.config.globalProperties.$myPlugin = this
  }

  async initialize() {
    // Setup logic
  }

  destroy() {
    // Cleanup logic
  }
}

export default MyPlugin

Plugin Registration

import { createApp } from '@stacksjs/core'
import MyPlugin from './plugins/my-plugin'

const app = createApp()

app.use(MyPlugin, {
  enabled: true,
  apiKey: process.env.MY_PLUGIN_API_KEY
})

Plugin Types

Compiler Plugins

export function createTransformerPlugin(options: TransformerOptions) {
  return {
    name: 'custom-transformer',
    transform(code: string, id: string) {
      if (id.endsWith('.stx')) {
        return code.replace(options.transformPattern, options.replacement)
      }
      return null
    }
  }
}

Runtime Plugins

export class StateManagerPlugin {
  private store = new Map()

  install(app: stxApp) {
    app.provide('state', {
      get: (key: string) => this.store.get(key),
      set: (key: string, value: any) => this.store.set(key, value),
      delete: (key: string) => this.store.delete(key)
    })
  }
}

Plugin Distribution

NPM Package Structure

{
  "name": "@stacksjs/my-plugin",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "files": ["dist"],
  "peerDependencies": {
    "@stacksjs/core": "^2.0.0"
  },
  "keywords": ["stx", "plugin", "my-plugin"]
}

TypeScript Definitions

declare module '@stacksjs/core' {
  interface ComponentCustomProperties {
    $myPlugin: MyPlugin
  }

  interface GlobalComponents {
    MyComponent: typeof MyComponent
  }
}

Testing Plugins

Unit Testing

import { test, expect } from 'bun:test'
import { createApp } from '@stacksjs/core'
import MyPlugin from '../src'

test('plugin installs correctly', () => {
  const app = createApp()

  expect(() => {
    app.use(MyPlugin, { enabled: true })
  }).not.toThrow()

  expect(app.config.globalProperties.$myPlugin).toBeDefined()
})

Plugin Ecosystem

Official Plugins

stx-router - Client-side routing
@stacksjs/state - State management
@stacksjs/i18n - Internationalization

Community Guidelines

Guidelines for community plugin development:

Follow semantic versioning
Include comprehensive tests
Provide TypeScript definitions
Document API and usage examples
Follow stx coding standards

Plugin API Reference - Complete plugin API documentation
Component Development - Building components for plugins
State Management - Integrating with stx state
Configuration Guide - Plugin configuration patterns