Thanks for your interest in contributing to the nSelf plugin ecosystem.

Free MIT plugins for the nSelf CLI. There are 25 free plugins available to everyone.

• nSelf CLI
• Node.js 22+ (for registry/SDK tools)
• Go 1.22+ (for Go plugins)

1. Clone the repo and the CLI:

   git clone https://github.com/nself-org/plugins.git
   git clone https://github.com/nself-org/cli.git

2. Install the nSelf CLI:

   cd cli && make install

3. Start a local nSelf stack:

   mkdir testproject && cd testproject
   nself init
   nself start

4. Install a plugin for development:

   nself plugin install <plugin-name> --dev

Plugins live in free/, community/, and monitoring/ directories. Each plugin lives in <directory>/<plugin-name>/ with this layout:

free/<plugin-name>/
  plugin.json          # Plugin manifest
  install.sh           # Installation script
  README.md            # Plugin-specific docs
  docker-compose.yml   # If adding a service
  ts/src/              # TypeScript source
    types.ts
    client.ts
    database.ts
    server.ts
    index.ts
  migrations/          # SQL migrations (optional)

• TypeScript strict mode
• All tables use the np_ prefix (e.g., np_notify_subscriptions)
• Every handler includes source_account_id for multi-tenancy
• pnpm only (no npm or yarn)
• All shell scripts must be Bash 3.2 compatible (no echo -e, no ${var,,}, no declare -A)
• Follow existing code patterns; include comments for complex logic; use printf not echo -e

Read Standards BEFORE contributing. Violations will cause automated build failures.

All plugins must comply with:

• Universal np_ table prefix
• source_account_id multi-app isolation
• Official category assignment (1 of 13)
• Lowercase-with-hyphens naming (my-service, not MyService)

ALL tables must:

• Be prefixed with np_ (e.g. np_stripe_customers, not stripe_customers)
• Include source_account_id for multi-tenant isolation
• Include standard columns: created_at, synced_at
• Use JSONB for flexible data
• Add indexes for common queries

Example:

CREATE TABLE np_myplugin_resources (
    id UUID PRIMARY KEY,
    source_account_id VARCHAR(255) NOT NULL,  -- REQUIRED
    name VARCHAR(255) NOT NULL,
    metadata JSONB DEFAULT '{}',
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    synced_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),

    INDEX idx_np_myplugin_resources_account (source_account_id)
);

plugin.json must include:

{
  "multiApp": {
    "supported": true,
    "isolationColumn": "source_account_id",
    "pkStrategy": "uuid",
    "defaultValue": "primary"
  }
}

Choose ONE of the 13 official categories:

• authentication, automation, commerce, communication, content
• data, development, infrastructure, integrations, media
• streaming, sports, compliance

See Standards for category descriptions.

Before submitting, run these checks:

# 1. Validate JSON syntax
jq empty plugins/my-plugin/plugin.json

# 2. Check table prefixes (should return nothing)
jq -r '.tables[] | select(startswith("np_") | not)' plugins/my-plugin/plugin.json

# 3. Check multi-app isolation (should output: source_account_id)
jq -r '.multiApp.isolationColumn' plugins/my-plugin/plugin.json

# 4. Check category is valid
jq -r '.category' plugins/my-plugin/plugin.json

All checks must pass or your PR will fail automated validation.

1. Fork the repository
2. Create a feature branch from main
3. New plugins need a plugin.json, install.sh, and README
4. Make your changes, following existing plugin patterns
5. Test with a local nSelf stack
6. Submit a PR with a clear description of what changed and why

Conventional commits: feat:, fix:, chore:, docs:, test:

Open an issue on GitHub with:

• nSelf CLI version (nself version)
• Plugin name and version
• Steps to reproduce
• Expected vs actual behavior

Do not open a public issue for security vulnerabilities. Follow the process in SECURITY.md.

• GitHub Discussions — preferred for questions about plugin development
• Community: nself.org

• GOVERNANCE.md — decision model
• ENFORCEMENT.md — code of conduct enforcement
• CODEOWNERS — who reviews what
• Plugin-Development — detailed plugin dev guide
• All Plugins: the full plugin catalog

← Home | _Sidebar