DocsIntroduction
List of Official Plugins for SimpleNS
Plugins in SimpleNS
SimpleNS uses a plugin-based architecture that allows you to extend its capabilities by adding new notification providers without modifying the core system.
Why Plugins?
Plugins keep the core lean while enabling unlimited extensibility. Add only the providers you need, exactly how you need them configured.
What are Plugins?
Plugins are self-contained npm packages that implement the SimpleNSProvider interface from @simplens/sdk. Each plugin:
Encapsulates Logic
Contains all the code needed to send notifications via a specific service (e.g., Gmail, Twilio, FCM)
Defines Schemas
Provides Zod schemas for recipient and content validation specific to the channel
Manages Lifecycle
Handles initialization, health checks, and graceful shutdown
Configures Rate Limits
Specifies rate limiting behavior to prevent API throttling
Role of Plugins
Plugins serve several critical functions within the SimpleNS ecosystem:
Plugin Lifecycle
Every plugin follows a consistent lifecycle managed by the SimpleNS core:
Installation
Use the @simplens/config-gen CLI to generate plugin configuration:
# Generate config for a plugin
npx @simplens/config-gen generate @simplens/nodemailer-gmail
# Add to existing config
npx @simplens/config-gen gen @simplens/mock -c simplens.config.yaml
# List available plugins
npx @simplens/config-gen list --officialThis creates simplens.config.yaml with the plugin configuration. You'll need to set the required environment variables in .env.
SimpleNS automatically installs plugins to .plugins/ on startup based on your simplens.config.yaml.
Initialization
The plugin's initialize() method is called with resolved credentials and optional configuration from environment variables.
Health Check
SimpleNS verifies the plugin is ready by calling healthCheck(). Unhealthy plugins are flagged but don't block other providers.
Registration
The plugin is registered in the Plugin Registry with its configured priority and channel mapping.
Message Handling
When notifications arrive, the plugin's send() method is invoked to deliver them via the underlying service.
Shutdown
On graceful termination, shutdown() is called to clean up connections and resources.
Official Plugins
SimpleNS provides official, production-ready plugins maintained by the core team:
Nodemailer Gmail
@simplens/nodemailer-gmail
Send emails using Gmail's SMTP service via Nodemailer.
Mock Provider
@simplens/mock
A testing plugin that simulates notification delivery. Perfect for development and E2E testing.
Configuration Example
Plugins are configured in your simplens.config.yaml:
providers:
- package: "@simplens/nodemailer-gmail"
id: "gmail-primary"
credentials:
EMAIL_USER: ${EMAIL_USER}
EMAIL_PASS: ${EMAIL_PASS}
options:
priority: 10
rateLimit:
maxTokens: 100
refillRate: 50
channels:
email:
default: "gmail-primary"providers:
- package: "@simplens/nodemailer-gmail"
id: "gmail-primary"
credentials:
EMAIL: ${GMAIL_EMAIL}
APP_PASSWORD: ${GMAIL_APP_PASSWORD}
options:
priority: 10
- package: "<fallback_provider_npm_package_name>"
id: "email-fallback"
credentials: {}
options:
priority: 1
channels:
email:
default: "gmail-primary"
fallback: "email-fallback"Environment Variables
Use ${VAR_NAME} syntax in credentials to reference environment variables. SimpleNS resolves these at runtime, keeping secrets out of config files.
Installing Plugins
Plugins are auto-installed when you start SimpleNS with a configured simplens.config.yaml.
Using Config Generator CLI
# Generate config for single or multiple plugins
npx @simplens/config-gen generate @simplens/nodemailer-gmail
npx @simplens/config-gen gen @simplens/mock @simplens/nodemailer-gmail
# Add to existing config
npx @simplens/config-gen gen @simplens/nodemailer-gmail -c simplens.config.yaml
# List available plugins
npx @simplens/config-gen list --official
npx @simplens/config-gen list --communityPlugins are installed to the .plugins/node_modules/ directory, keeping them separate from your core dependencies.