From 051d87a51ff4ad3d9b58f2cf403512b1011e3e14 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 26 Jan 2026 13:16:14 +0000 Subject: [PATCH 1/4] docs: add product plan for CLI plugin system Introduces comprehensive design document covering: - Plugin structure (entities + BE functions) - Host app configuration format - Extension mechanism for schemas and functions - Plugin installation flow from multiple sources - CLI commands for plugin management - Deploy behavior with plugin merging - Security considerations and permissions model --- docs/plans/plugin-system-plan.md | 888 +++++++++++++++++++++++++++++++ 1 file changed, 888 insertions(+) create mode 100644 docs/plans/plugin-system-plan.md diff --git a/docs/plans/plugin-system-plan.md b/docs/plans/plugin-system-plan.md new file mode 100644 index 00000000..9f4c3854 --- /dev/null +++ b/docs/plans/plugin-system-plan.md @@ -0,0 +1,888 @@ +# Base44 CLI Plugin System - Product Plan + +## Executive Summary + +This document outlines the design for a **Plugin System** in the Base44 CLI. Plugins are reusable packages of **entities (schemas)** and **backend functions** that can be shared across multiple Base44 applications. Host applications can install plugins and optionally extend their schemas and functions. + +--- + +## 1. Core Concepts + +### 1.1 What is a Plugin? + +A **Plugin** is a distributable, versioned package containing: + +| Component | Description | +|-----------|-------------| +| **Entities** | JSON schema definitions (data models) | +| **Backend Functions** | Server-side logic (TypeScript/JavaScript) | +| **Metadata** | Name, version, author, dependencies | + +Plugins enable: +- **Reusability**: Share common patterns across projects (auth, payments, notifications) +- **Modularity**: Compose applications from building blocks +- **Ecosystem**: Create and distribute community plugins + +### 1.2 Plugin vs. App Relationship + +``` +┌─────────────────────────────────────────────────────────────┐ +│ HOST APPLICATION │ +│ │ +│ ┌─────────────────┐ ┌─────────────────┐ │ +│ │ App Entities │ │ App Functions │ │ +│ └─────────────────┘ └─────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────┐ │ +│ │ PLUGINS │ │ +│ │ │ │ +│ │ ┌──────────────────┐ ┌──────────────────┐ │ │ +│ │ │ @base44/auth │ │ @acme/payments │ │ │ +│ │ │ ├─ User entity │ │ ├─ Payment │ │ │ +│ │ │ ├─ Session │ │ ├─ Invoice │ │ │ +│ │ │ └─ login() │ │ └─ charge() │ │ │ +│ │ └──────────────────┘ └──────────────────┘ │ │ +│ └─────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────┐ │ +│ │ EXTENSIONS │ │ +│ │ User entity + { companyId, role } │ │ +│ │ login() + custom validation │ │ +│ └─────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## 2. Plugin Structure + +### 2.1 Directory Layout + +``` +my-plugin/ +├── plugin.jsonc # Plugin manifest (required) +├── entities/ +│ ├── user.jsonc +│ └── session.jsonc +├── functions/ +│ ├── login/ +│ │ ├── function.json +│ │ └── index.ts +│ └── logout/ +│ ├── function.json +│ └── index.ts +└── README.md # Documentation +``` + +### 2.2 Plugin Manifest (`plugin.jsonc`) + +```jsonc +{ + // Required fields + "name": "@base44/auth", // Unique identifier (npm-style naming) + "version": "1.0.0", // Semantic versioning + + // Optional metadata + "description": "Authentication plugin for Base44 apps", + "author": "Base44 Team", + "license": "MIT", + "repository": "https://github.com/base44/auth-plugin", + + // Plugin dependencies (other plugins this depends on) + "dependencies": { + "@base44/email": "^2.0.0" + }, + + // Resource configuration + "entities": { + "directory": "entities", // Default: "entities" + "exports": ["User", "Session"] // Explicitly exported entities + }, + + "functions": { + "directory": "functions", // Default: "functions" + "exports": ["login", "logout"] // Explicitly exported functions + }, + + // Extension points - what can host apps customize + "extensible": { + "entities": { + "User": { + "allowAddProperties": true, // Host can add fields + "allowOverrideProperties": false // Host cannot change existing fields + } + }, + "functions": { + "login": { + "hooks": ["beforeLogin", "afterLogin"] // Available hooks + } + } + } +} +``` + +### 2.3 Plugin Entity Schema + +Plugin entities follow the same format as app entities, with additional plugin-specific metadata: + +```jsonc +// entities/user.jsonc +{ + "name": "User", + "type": "object", + "description": "User account for authentication", + + // Schema definition + "properties": { + "email": { + "type": "string", + "format": "email", + "description": "User's email address" + }, + "passwordHash": { + "type": "string", + "private": true // Not exposed to client + }, + "createdAt": { + "type": "string", + "format": "date-time" + } + }, + "required": ["email", "passwordHash"], + + // Plugin-specific: marks this as core (non-removable) + "_plugin": { + "core": true, + "extensible": true + } +} +``` + +--- + +## 3. Host App Configuration + +### 3.1 Updated Project Config (`base44/config.jsonc`) + +```jsonc +{ + "name": "my-saas-app", + "description": "A SaaS application built on Base44", + + // NEW: Plugin configuration + "plugins": { + // Installed plugins with version constraints + "installed": { + "@base44/auth": "^1.0.0", + "@base44/email": "^2.0.0", + "@acme/payments": "1.2.3" + }, + + // Plugin-specific configuration + "config": { + "@base44/auth": { + "sessionDuration": "7d", + "requireEmailVerification": true + }, + "@acme/payments": { + "provider": "stripe", + "currency": "USD" + } + } + }, + + // Existing config + "site": { + "buildCommand": "npm run build", + "outputDirectory": "./dist" + } +} +``` + +### 3.2 Plugin Extensions Directory + +Host apps can extend plugins through an `extensions/` directory: + +``` +my-app/ +├── base44/ +│ ├── config.jsonc +│ └── .app.jsonc +├── entities/ # App's own entities +├── functions/ # App's own functions +└── extensions/ # NEW: Plugin extensions + └── @base44/ + └── auth/ + ├── entities/ + │ └── user.extend.jsonc + └── functions/ + └── login/ + └── hooks.ts +``` + +--- + +## 4. Extension Mechanism + +### 4.1 Extending Entity Schemas + +Host apps can extend plugin entities by adding new properties: + +```jsonc +// extensions/@base44/auth/entities/user.extend.jsonc +{ + "extends": "@base44/auth/User", + + // Add new properties + "properties": { + "companyId": { + "type": "string", + "description": "Reference to user's company" + }, + "role": { + "type": "string", + "enum": ["admin", "member", "viewer"], + "default": "member" + }, + "preferences": { + "type": "object", + "properties": { + "theme": { "type": "string", "enum": ["light", "dark"] }, + "notifications": { "type": "boolean", "default": true } + } + } + }, + + // Add to required fields (optional) + "additionalRequired": ["companyId"], + + // Add indexes for custom fields + "indexes": [ + { "fields": ["companyId"] }, + { "fields": ["companyId", "role"] } + ] +} +``` + +**Merged Result at Deploy Time:** + +```jsonc +// Final User entity (plugin + extensions merged) +{ + "name": "User", + "type": "object", + "properties": { + // From plugin + "email": { "type": "string", "format": "email" }, + "passwordHash": { "type": "string", "private": true }, + "createdAt": { "type": "string", "format": "date-time" }, + // From host extension + "companyId": { "type": "string" }, + "role": { "type": "string", "enum": ["admin", "member", "viewer"] }, + "preferences": { "type": "object", ... } + }, + "required": ["email", "passwordHash", "companyId"] +} +``` + +### 4.2 Extending Backend Functions + +Host apps can hook into plugin functions at defined extension points: + +```typescript +// extensions/@base44/auth/functions/login/hooks.ts + +import { BeforeLoginHook, AfterLoginHook } from '@base44/auth'; + +/** + * Called before the plugin's login logic executes + * Can modify input or throw to prevent login + */ +export const beforeLogin: BeforeLoginHook = async (context) => { + const { email, password, request } = context; + + // Custom validation: check if email domain is allowed + const domain = email.split('@')[1]; + const allowedDomains = ['mycompany.com', 'partner.com']; + + if (!allowedDomains.includes(domain)) { + throw new Error('Email domain not allowed'); + } + + // Log login attempt + await context.entities.AuditLog.create({ + action: 'login_attempt', + email, + ip: request.headers['x-forwarded-for'] + }); + + return context; // Pass through (can modify) +}; + +/** + * Called after successful login + * Can modify response or perform side effects + */ +export const afterLogin: AfterLoginHook = async (context) => { + const { user, session, response } = context; + + // Add custom data to response + response.data.company = await context.entities.Company.get(user.companyId); + response.data.permissions = await getPermissions(user.role); + + // Send notification + await context.functions.sendEmail({ + to: user.email, + template: 'login_notification' + }); + + return response; +}; +``` + +### 4.3 Function Wrapping (Advanced) + +For more control, host apps can wrap entire plugin functions: + +```typescript +// extensions/@base44/auth/functions/login/wrapper.ts + +import { wrapFunction } from '@base44/plugin-sdk'; +import { login as originalLogin } from '@base44/auth'; + +export default wrapFunction(originalLogin, { + // Transform input before calling original + transformInput: async (input, context) => { + return { + ...input, + email: input.email.toLowerCase().trim() + }; + }, + + // Transform output after original returns + transformOutput: async (output, context) => { + return { + ...output, + loginTime: new Date().toISOString() + }; + }, + + // Handle errors from original function + onError: async (error, context) => { + await context.entities.FailedLogin.create({ + email: context.input.email, + error: error.message, + timestamp: new Date() + }); + throw error; // Re-throw or return fallback + } +}); +``` + +--- + +## 5. Plugin Installation + +### 5.1 Installation Sources + +Plugins can be installed from multiple sources: + +| Source | Command | Example | +|--------|---------|---------| +| **Base44 Registry** | `base44 plugins add ` | `base44 plugins add @base44/auth` | +| **npm Registry** | `base44 plugins add ` | `base44 plugins add base44-auth-plugin` | +| **Git Repository** | `base44 plugins add ` | `base44 plugins add github:acme/payments` | +| **Local Path** | `base44 plugins add ` | `base44 plugins add ../my-plugin` | + +### 5.2 Installation Flow + +``` +┌─────────────────────────────────────────────────────────────┐ +│ PLUGIN INSTALLATION FLOW │ +└─────────────────────────────────────────────────────────────┘ + +User runs: base44 plugins add @base44/auth + + │ + ▼ +┌─────────────────────┐ +│ 1. Resolve Plugin │ • Check Base44 registry +│ │ • Fall back to npm +│ │ • Parse git URLs +└─────────────────────┘ + │ + ▼ +┌─────────────────────┐ +│ 2. Fetch Plugin │ • Download package +│ │ • Verify checksum +│ │ • Extract to temp +└─────────────────────┘ + │ + ▼ +┌─────────────────────┐ +│ 3. Validate │ • Check plugin.jsonc exists +│ │ • Validate schema +│ │ • Check version compatibility +└─────────────────────┘ + │ + ▼ +┌─────────────────────┐ +│ 4. Resolve Deps │ • Read dependencies +│ │ • Check for conflicts +│ │ • Install missing deps +└─────────────────────┘ + │ + ▼ +┌─────────────────────┐ +│ 5. Install │ • Copy to base44/plugins/ +│ │ • Update config.jsonc +│ │ • Generate lock file +└─────────────────────┘ + │ + ▼ +┌─────────────────────┐ +│ 6. Post-Install │ • Run plugin setup hooks +│ │ • Display next steps +│ │ • Suggest extensions +└─────────────────────┘ +``` + +### 5.3 Installed Plugin Storage + +``` +my-app/ +├── base44/ +│ ├── config.jsonc +│ ├── .app.jsonc +│ ├── plugins/ # NEW: Installed plugins +│ │ ├── @base44/ +│ │ │ ├── auth/ # Full plugin contents +│ │ │ │ ├── plugin.jsonc +│ │ │ │ ├── entities/ +│ │ │ │ └── functions/ +│ │ │ └── email/ +│ │ └── @acme/ +│ │ └── payments/ +│ └── plugins.lock.jsonc # NEW: Lock file +``` + +### 5.4 Lock File (`plugins.lock.jsonc`) + +```jsonc +{ + "lockfileVersion": 1, + "plugins": { + "@base44/auth": { + "version": "1.2.3", + "resolved": "https://registry.base44.com/@base44/auth/-/auth-1.2.3.tgz", + "integrity": "sha512-abc123...", + "dependencies": { + "@base44/email": "2.0.0" + } + }, + "@base44/email": { + "version": "2.0.0", + "resolved": "https://registry.base44.com/@base44/email/-/email-2.0.0.tgz", + "integrity": "sha512-def456..." + } + } +} +``` + +--- + +## 6. CLI Commands + +### 6.1 New Plugin Commands + +```bash +# Plugin management +base44 plugins add # Install a plugin +base44 plugins remove # Remove a plugin +base44 plugins list # List installed plugins +base44 plugins update [plugin] # Update plugin(s) +base44 plugins info # Show plugin details + +# Plugin development +base44 plugins init # Initialize new plugin project +base44 plugins validate # Validate plugin structure +base44 plugins publish # Publish to Base44 registry +base44 plugins pack # Create distributable archive + +# Extension management +base44 plugins extend # Scaffold extension for a plugin +``` + +### 6.2 Command Examples + +```bash +# Install auth plugin +$ base44 plugins add @base44/auth + +◐ Resolving @base44/auth... +✓ Found @base44/auth@1.2.3 + +◐ Checking dependencies... +✓ Requires @base44/email@^2.0.0 +◐ Installing @base44/email@2.0.0... +✓ Installed @base44/email@2.0.0 + +◐ Installing @base44/auth@1.2.3... +✓ Plugin installed successfully + +Added entities: + • User + • Session + +Added functions: + • login + • logout + • refreshToken + • resetPassword + +Next steps: + 1. Configure the plugin in base44/config.jsonc + 2. Run 'base44 deploy' to deploy plugin resources + 3. Run 'base44 plugins extend @base44/auth' to customize + +# List installed plugins +$ base44 plugins list + +Installed plugins: +┌─────────────────┬─────────┬──────────┬───────────────────┐ +│ Name │ Version │ Entities │ Functions │ +├─────────────────┼─────────┼──────────┼───────────────────┤ +│ @base44/auth │ 1.2.3 │ 2 │ 4 │ +│ @base44/email │ 2.0.0 │ 1 │ 3 │ +│ @acme/payments │ 1.0.0 │ 3 │ 5 │ +└─────────────────┴─────────┴──────────┴───────────────────┘ + +# Create extension scaffolding +$ base44 plugins extend @base44/auth + +? Which resources do you want to extend? + ◉ User entity + ◯ Session entity + ◉ login function + ◯ logout function + +✓ Created extensions/@base44/auth/entities/user.extend.jsonc +✓ Created extensions/@base44/auth/functions/login/hooks.ts + +Edit these files to customize the plugin behavior. +``` + +--- + +## 7. Deploy Behavior + +### 7.1 Updated Deploy Flow + +``` +┌─────────────────────────────────────────────────────────────┐ +│ DEPLOY WITH PLUGINS │ +└─────────────────────────────────────────────────────────────┘ + +User runs: base44 deploy + + │ + ▼ +┌─────────────────────┐ +│ 1. Load Config │ • Read config.jsonc +│ │ • Parse plugin references +│ │ • Load lock file +└─────────────────────┘ + │ + ▼ +┌─────────────────────┐ +│ 2. Collect Plugins │ • Read installed plugins +│ │ • Resolve dependency order +│ │ • Check for conflicts +└─────────────────────┘ + │ + ▼ +┌─────────────────────┐ +│ 3. Load Extensions │ • Find extension files +│ │ • Validate against plugin +│ │ • Parse hooks/wrappers +└─────────────────────┘ + │ + ▼ +┌─────────────────────┐ +│ 4. Merge Entities │ • Plugin entities (base) +│ │ • + Extension properties +│ │ • + App entities +│ │ • Detect conflicts +└─────────────────────┘ + │ + ▼ +┌─────────────────────┐ +│ 5. Merge Functions │ • Plugin functions (base) +│ │ • + Hook injection +│ │ • + Wrappers applied +│ │ • + App functions +└─────────────────────┘ + │ + ▼ +┌─────────────────────┐ +│ 6. Deploy │ • Push merged entities +│ │ • Deploy merged functions +│ │ • Report results +└─────────────────────┘ +``` + +### 7.2 Namespace Strategy + +To prevent collisions, plugin resources are namespaced: + +| Resource Type | Naming Convention | Example | +|---------------|-------------------|---------| +| **Entities** | `{PluginName}_{EntityName}` | `Auth_User`, `Payments_Invoice` | +| **Functions** | `{pluginName}_{functionName}` | `auth_login`, `payments_charge` | + +**Configuration option** in `config.jsonc`: + +```jsonc +{ + "plugins": { + "installed": { "@base44/auth": "^1.0.0" }, + "config": { + "@base44/auth": { + // Use short names (no prefix) - opt-in for cleaner code + "useShortNames": true + } + } + } +} +``` + +--- + +## 8. Plugin Development + +### 8.1 Creating a New Plugin + +```bash +$ base44 plugins init + +? Plugin name: @myorg/notifications +? Description: Push notification system for Base44 apps +? Author: My Organization +? License: MIT + +✓ Created plugin structure: + +my-plugin/ +├── plugin.jsonc +├── entities/ +│ └── .gitkeep +├── functions/ +│ └── .gitkeep +├── README.md +└── package.json + +Next steps: + 1. Add entities to entities/ + 2. Add functions to functions/ + 3. Run 'base44 plugins validate' to check structure + 4. Run 'base44 plugins publish' when ready +``` + +### 8.2 Plugin Testing + +```bash +# Validate plugin structure +$ base44 plugins validate + +Validating plugin... +✓ plugin.jsonc is valid +✓ All exported entities found +✓ All exported functions found +✓ No circular dependencies +✓ Extension points are valid + +Plugin is ready for publishing! + +# Test plugin locally in an app +$ cd ../my-test-app +$ base44 plugins add ../my-plugin # Install from local path +$ base44 deploy # Deploy and test +``` + +### 8.3 Publishing + +```bash +$ base44 plugins publish + +◐ Validating plugin... +✓ Plugin structure valid + +◐ Checking registry... +? Version 1.0.0 does not exist. Publish? Yes + +◐ Packaging plugin... +✓ Created @myorg-notifications-1.0.0.tgz (12.3 KB) + +◐ Publishing to Base44 registry... +✓ Published @myorg/notifications@1.0.0 + +View at: https://registry.base44.com/plugins/@myorg/notifications +``` + +--- + +## 9. Error Handling + +### 9.1 Conflict Detection + +```bash +$ base44 deploy + +Error: Entity name conflict detected + +The entity "User" is defined in multiple places: + • Plugin @base44/auth (User) + • Plugin @acme/identity (User) + +Resolution options: + 1. Remove one of the conflicting plugins + 2. Enable namespacing for one or both plugins: + + "plugins": { + "config": { + "@acme/identity": { "useShortNames": false } + } + } +``` + +### 9.2 Extension Validation + +```bash +$ base44 deploy + +Error: Invalid extension for @base44/auth + +extensions/@base44/auth/entities/user.extend.jsonc: + • Property "email" cannot be overridden (plugin disallows this) + • Property "status" uses reserved name + +Fix the extension file and try again. +``` + +### 9.3 Version Conflicts + +```bash +$ base44 plugins add @acme/dashboard + +Error: Dependency conflict + +@acme/dashboard requires @base44/auth@^2.0.0 +But you have @base44/auth@1.2.3 installed + +Options: + 1. Update @base44/auth: base44 plugins update @base44/auth + 2. Install compatible version: base44 plugins add @acme/dashboard@0.9.0 +``` + +--- + +## 10. Security Considerations + +### 10.1 Plugin Trust Model + +| Level | Description | Requirements | +|-------|-------------|--------------| +| **Official** | Published by Base44 | `@base44/*` namespace, verified | +| **Verified** | Community, reviewed | Passed security audit | +| **Community** | Any publisher | Standard npm-style trust | +| **Local** | Local/git sources | User responsibility | + +### 10.2 Permissions + +Plugins can declare required permissions: + +```jsonc +// plugin.jsonc +{ + "permissions": { + "network": ["api.stripe.com", "hooks.slack.com"], + "entities": ["read:*", "write:own"], + "secrets": ["STRIPE_API_KEY"] + } +} +``` + +Host apps must approve permissions: + +```bash +$ base44 plugins add @acme/payments + +⚠️ This plugin requests the following permissions: + +Network access: + • api.stripe.com + • hooks.slack.com + +Entity access: + • Read all entities + • Write own entities + +Secrets: + • STRIPE_API_KEY + +? Grant these permissions? (y/N) +``` + +--- + +## 11. Future Considerations + +### 11.1 Potential Enhancements + +1. **Plugin Marketplace UI**: Web-based discovery and installation +2. **Plugin Analytics**: Usage metrics, error tracking +3. **Plugin Versioning**: Automatic updates, changelogs +4. **Plugin Composition**: Plugins that depend on other plugins +5. **Plugin Templates**: Scaffold apps from plugin combinations +6. **Private Registries**: Enterprise plugin hosting + +### 11.2 Migration Path + +For existing apps adopting plugins: + +```bash +# Convert existing entities/functions to a plugin +$ base44 plugins extract --name @myorg/core + +This will: + 1. Create plugin structure from current resources + 2. Move entities/ and functions/ to plugin + 3. Update config.jsonc to reference the plugin + +? Proceed? Yes + +✓ Created base44/plugins/@myorg/core/ +✓ Moved 5 entities and 8 functions +✓ Updated config.jsonc + +Your app now uses the @myorg/core plugin! +``` + +--- + +## 12. Summary + +The Plugin System introduces a powerful abstraction for sharing and extending Base44 resources: + +| Feature | Benefit | +|---------|---------| +| **Reusable Packages** | Share entities & functions across projects | +| **Version Control** | Lock files ensure reproducible deployments | +| **Extensions** | Customize plugins without forking | +| **Hooks & Wrappers** | Inject custom logic into plugin functions | +| **Multiple Sources** | Install from registry, npm, git, or local | +| **Namespace Safety** | Prevent resource name collisions | +| **Security Model** | Permission system for plugin capabilities | + +This system enables Base44 to evolve from a single-app platform to a composable ecosystem of reusable backend components. From 777bf02723a5fcd665dae618e32ff5769e996c32 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 26 Jan 2026 13:33:10 +0000 Subject: [PATCH 2/4] docs: add competitive analysis for plugin distribution strategies Research on how other platforms handle plugins: - Terraform: Own registry with GPG signing - VS Code: Marketplace with verified publisher badges - Figma: Own marketplace with human review - Shopify/Heroku/Gatsby: npm-only approach - Strapi/Backstage: Hybrid npm + own marketplace - WordPress: SVN with mandatory human review Includes recommendation for phased hybrid approach: 1. npm-first MVP 2. Base44 registry for discoverability 3. Enterprise features (private registry, signing) --- docs/plans/plugin-system-plan.md | 140 ++++++++++++++++++++++++++++++- 1 file changed, 139 insertions(+), 1 deletion(-) diff --git a/docs/plans/plugin-system-plan.md b/docs/plans/plugin-system-plan.md index 9f4c3854..829f09e6 100644 --- a/docs/plans/plugin-system-plan.md +++ b/docs/plans/plugin-system-plan.md @@ -871,7 +871,145 @@ Your app now uses the @myorg/core plugin! --- -## 12. Summary +## 12. Competitive Analysis: How Other Platforms Handle Plugins + +### 12.1 Overview Comparison + +| Platform | Registry Type | Installation Method | Verification/Trust | Versioning | +|----------|---------------|---------------------|-------------------|------------| +| **Terraform** | Own registry (registry.terraform.io) | CLI (`terraform init`) | GPG signing + tier badges | Semantic versioning | +| **VS Code** | Own marketplace + Open VSX | CLI/GUI/VSIX files | Verified publisher badge + signatures | Semantic versioning | +| **Figma** | Own marketplace (Figma Community) | In-app installation | Figma review process + org approval | Version tracking | +| **Shopify CLI** | npm | npm/CLI (`npm init @shopify/app`) | npm package trust | Semantic versioning | +| **Heroku CLI** | npm | CLI (`heroku plugins:install`) | npm trust only | Semantic versioning | +| **Gatsby** | npm + Plugin Library | npm (`npm install`) | Official badge for Gatsby-maintained | Semantic versioning | +| **Strapi** | npm + Own marketplace | npm + in-app browser | Reviewed badge (checkmark) | Semantic versioning | +| **WordPress** | Own repository (wordpress.org) | WP Admin/CLI | Human review + security scans | WordPress versioning | +| **Backstage** | npm + Spotify Marketplace | npm | Partner verification | Semantic versioning | + +### 12.2 Registry Approaches + +#### A. Own Registry Only (Terraform, Figma, WordPress) + +**Terraform (HashiCorp)** +- Custom registry at `registry.terraform.io` +- Providers auto-downloaded during `terraform init` +- **GPG Signing Required** for all releases +- Three-tier trust system: + 1. HashiCorp-signed (official) + 2. Partner-signed (verified third-party) + 3. Self-signed (community) + +**Figma** +- Centralized Figma Community marketplace +- All public plugins reviewed before listing +- Organization admins can curate approved lists +- 15% platform fee for paid plugins + +**WordPress** +- SVN-based repository (60,000+ plugins) +- **Most rigorous: mandatory human review** (14+ days) +- 2FA required for submitting (as of 2024) +- Security team can patch vulnerable plugins +- GPL license required + +#### B. npm Only (Shopify, Heroku, Gatsby) + +**Shopify CLI** +- Fully npm-based modular architecture +- Plugins are npm packages: `@shopify/theme`, `@shopify/app` +- Also available via Homebrew on macOS +- Relies entirely on npm's trust mechanisms + +**Heroku CLI** +- Built on [oclif](https://oclif.io/) (Open CLI Framework) +- `heroku plugins:install PLUGINNAME` (npm package) +- Can restrict to specific npm scopes +- No additional verification layer + +**Gatsby** +- All plugins distributed via npm +- Gatsby Plugin Library is searchable directory (1,750+ plugins) +- "Official" badge for Gatsby-maintained plugins only + +#### C. Hybrid: npm + Own Marketplace (Strapi, VS Code, Backstage) + +**Strapi** +- Must be on npm first, then submit to Strapi Market +- In-app marketplace browser in admin panel +- "Reviewed" badge (checkmark) for plugins passing review +- 1-2 day listing time after submission + +**VS Code** +- Primary: Visual Studio Marketplace (Azure DevOps backed) +- Alternative: Open VSX Registry for forks like VSCodium +- New (2025): Private Marketplace for enterprise +- Verified publisher badge + extension signing + +**Backstage (Spotify)** +- Plugins are npm packages +- Spotify Marketplace for partner/official plugins +- Bundle subscription includes enterprise features + +### 12.3 Verification Spectrum + +From least to most rigorous: + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ VERIFICATION RIGOR │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ NONE BADGE/REVIEW CRYPTO SIGNING HUMAN REVIEW │ +│ │ │ │ │ │ +│ ▼ ▼ ▼ ▼ │ +│ │ +│ Heroku Strapi Terraform WordPress │ +│ Gatsby VS Code Figma │ +│ Shopify Backstage │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +### 12.4 Key Patterns & Insights + +| Approach | Pros | Cons | +|----------|------|------| +| **Own Registry Only** | Full control, custom verification, quality curation | Development overhead, adoption friction | +| **npm Only** | No infrastructure cost, familiar tooling, fast to implement | Limited verification, trust delegated to npm | +| **Hybrid (npm + Own)** | Best of both worlds, discoverability + trust | Complexity, potential sync issues | + +### 12.5 Recommendations for Base44 + +Based on this analysis, we recommend a **phased hybrid approach**: + +**Phase 1: npm-First (MVP)** +- Plugins are npm packages with `base44-plugin-*` naming convention +- `base44 plugins add ` installs from npm +- Official plugins under `@base44/*` scope +- Leverage existing npm infrastructure + +**Phase 2: Base44 Registry (Growth)** +- Build searchable plugin directory at `plugins.base44.com` +- Index npm packages that match plugin schema +- Add "Verified" badges for reviewed plugins +- In-CLI browsing: `base44 plugins search` + +**Phase 3: Enterprise Features (Scale)** +- Private registry support for organizations +- GPG signing for official plugins +- Permission/capability review process +- Plugin analytics and usage metrics + +**Rationale:** +- Shopify/Heroku prove npm-only works well for developer tools +- Strapi's hybrid model shows gradual evolution path +- WordPress's review rigor is overkill for initial launch +- Terraform's signing is gold standard for security-critical infra + +--- + +## 13. Summary The Plugin System introduces a powerful abstraction for sharing and extending Base44 resources: From 5ecb63c2a9a25ce666528bdcbee6dc208d032746 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 26 Jan 2026 13:43:46 +0000 Subject: [PATCH 3/4] docs: update plugin plan for npm-first phased approach Updates product design based on competitive analysis: - Add phased rollout summary to executive summary - Update plugin structure to use package.json + base44.plugin.jsonc - Make npm the primary distribution channel (Phase 1) - Add phase indicators to CLI commands section - Update installation flow for npm-first resolution - Update lock file to reference npm registry - Update publishing workflow: npm publish first, then optional Base44 registry registration (Phase 2+) This aligns with patterns from Shopify CLI, Heroku CLI, and Strapi while planning for future Base44 registry. --- docs/plans/plugin-system-plan.md | 229 ++++++++++++++++++++++++------- 1 file changed, 180 insertions(+), 49 deletions(-) diff --git a/docs/plans/plugin-system-plan.md b/docs/plans/plugin-system-plan.md index 829f09e6..ee442fc8 100644 --- a/docs/plans/plugin-system-plan.md +++ b/docs/plans/plugin-system-plan.md @@ -4,6 +4,18 @@ This document outlines the design for a **Plugin System** in the Base44 CLI. Plugins are reusable packages of **entities (schemas)** and **backend functions** that can be shared across multiple Base44 applications. Host applications can install plugins and optionally extend their schemas and functions. +### Phased Rollout Strategy + +Based on [competitive analysis](#12-competitive-analysis-how-other-platforms-handle-plugins), we recommend an **npm-first phased approach**: + +| Phase | Focus | Key Features | +|-------|-------|--------------| +| **Phase 1 (MVP)** | npm-first | Plugins are npm packages; install via `base44 plugins add ` | +| **Phase 2** | Discoverability | Base44 registry at `plugins.base44.com`; `base44 plugins search` | +| **Phase 3** | Enterprise | Private registries, GPG signing, security audits | + +This approach minimizes initial infrastructure while enabling future growth. + --- ## 1. Core Concepts @@ -57,11 +69,15 @@ Plugins enable: ## 2. Plugin Structure +> **Distribution Strategy:** Plugins are npm packages first, enabling immediate ecosystem integration. +> See [Section 12.5](#125-recommendations-for-base44) for the phased rollout plan. + ### 2.1 Directory Layout ``` my-plugin/ -├── plugin.jsonc # Plugin manifest (required) +├── package.json # npm package manifest (required for distribution) +├── base44.plugin.jsonc # Base44 plugin config (required) ├── entities/ │ ├── user.jsonc │ └── session.jsonc @@ -75,25 +91,53 @@ my-plugin/ └── README.md # Documentation ``` -### 2.2 Plugin Manifest (`plugin.jsonc`) +### 2.2 Package Manifest (`package.json`) -```jsonc -{ - // Required fields - "name": "@base44/auth", // Unique identifier (npm-style naming) - "version": "1.0.0", // Semantic versioning +Since plugins are distributed via npm, they use standard `package.json`: - // Optional metadata +```json +{ + "name": "@base44/auth", + "version": "1.0.0", "description": "Authentication plugin for Base44 apps", "author": "Base44 Team", "license": "MIT", - "repository": "https://github.com/base44/auth-plugin", + "repository": { + "type": "git", + "url": "https://github.com/base44/auth-plugin" + }, + + "keywords": ["base44-plugin", "authentication", "auth"], + + "base44": { + "type": "plugin", + "minCliVersion": "1.0.0" + }, - // Plugin dependencies (other plugins this depends on) "dependencies": { "@base44/email": "^2.0.0" }, + "files": [ + "base44.plugin.jsonc", + "entities/", + "functions/", + "README.md" + ] +} +``` + +**Key conventions:** +- `keywords` must include `"base44-plugin"` for discoverability +- `base44.type` field identifies this as a Base44 plugin +- `files` array specifies what gets published to npm + +### 2.3 Plugin Config (`base44.plugin.jsonc`) + +Base44-specific configuration lives in a separate file: + +```jsonc +{ // Resource configuration "entities": { "directory": "entities", // Default: "entities" @@ -118,11 +162,27 @@ my-plugin/ "hooks": ["beforeLogin", "afterLogin"] // Available hooks } } + }, + + // Plugin configuration schema (validated at install time) + "configSchema": { + "type": "object", + "properties": { + "sessionDuration": { + "type": "string", + "default": "24h", + "description": "How long sessions remain valid" + }, + "requireEmailVerification": { + "type": "boolean", + "default": false + } + } } } ``` -### 2.3 Plugin Entity Schema +### 2.4 Plugin Entity Schema Plugin entities follow the same format as app entities, with additional plugin-specific metadata: @@ -384,22 +444,38 @@ export default wrapFunction(originalLogin, { ## 5. Plugin Installation +> **Phased Approach:** Installation evolves across phases. +> - **Phase 1 (MVP):** npm-only installation +> - **Phase 2:** Add Base44 registry as discovery layer +> - **Phase 3:** Enterprise private registries + ### 5.1 Installation Sources -Plugins can be installed from multiple sources: +Plugins can be installed from multiple sources (npm is primary): + +| Source | Command | Phase | Example | +|--------|---------|-------|---------| +| **npm Registry** | `base44 plugins add ` | 1 (MVP) | `base44 plugins add @base44/auth` | +| **Local Path** | `base44 plugins add ` | 1 (MVP) | `base44 plugins add ../my-plugin` | +| **Git Repository** | `base44 plugins add ` | 1 (MVP) | `base44 plugins add github:acme/payments` | +| **Base44 Registry** | `base44 plugins add ` | 2 | `base44 plugins add auth` (shorthand) | + +**Phase 1 Resolution Order:** +1. Check if input is a local path → install from filesystem +2. Check if input is a git URL → clone and install +3. Otherwise → resolve from npm registry -| Source | Command | Example | -|--------|---------|---------| -| **Base44 Registry** | `base44 plugins add ` | `base44 plugins add @base44/auth` | -| **npm Registry** | `base44 plugins add ` | `base44 plugins add base44-auth-plugin` | -| **Git Repository** | `base44 plugins add ` | `base44 plugins add github:acme/payments` | -| **Local Path** | `base44 plugins add ` | `base44 plugins add ../my-plugin` | +**Phase 2+ Resolution Order:** +1. Check if input is a local path → install from filesystem +2. Check if input is a git URL → clone and install +3. Check Base44 registry for shorthand names → resolve to npm package +4. Fall back to npm registry directly -### 5.2 Installation Flow +### 5.2 Installation Flow (Phase 1 - npm-first) ``` ┌─────────────────────────────────────────────────────────────┐ -│ PLUGIN INSTALLATION FLOW │ +│ PLUGIN INSTALLATION FLOW (npm-first) │ └─────────────────────────────────────────────────────────────┘ User runs: base44 plugins add @base44/auth @@ -407,16 +483,16 @@ User runs: base44 plugins add @base44/auth │ ▼ ┌─────────────────────┐ -│ 1. Resolve Plugin │ • Check Base44 registry -│ │ • Fall back to npm -│ │ • Parse git URLs +│ 1. Resolve Plugin │ • Parse input (npm package, git, local) +│ │ • Query npm registry for metadata +│ │ • Check base44.type === "plugin" └─────────────────────┘ │ ▼ ┌─────────────────────┐ -│ 2. Fetch Plugin │ • Download package -│ │ • Verify checksum -│ │ • Extract to temp +│ 2. Fetch Plugin │ • npm pack / download tarball +│ │ • Verify integrity (npm checksums) +│ │ • Extract to temp directory └─────────────────────┘ │ ▼ @@ -469,13 +545,15 @@ my-app/ ### 5.4 Lock File (`plugins.lock.jsonc`) +The lock file uses npm registry URLs (Phase 1) or Base44 registry (Phase 2+): + ```jsonc { "lockfileVersion": 1, "plugins": { "@base44/auth": { "version": "1.2.3", - "resolved": "https://registry.base44.com/@base44/auth/-/auth-1.2.3.tgz", + "resolved": "https://registry.npmjs.org/@base44/auth/-/auth-1.2.3.tgz", "integrity": "sha512-abc123...", "dependencies": { "@base44/email": "2.0.0" @@ -483,49 +561,72 @@ my-app/ }, "@base44/email": { "version": "2.0.0", - "resolved": "https://registry.base44.com/@base44/email/-/email-2.0.0.tgz", + "resolved": "https://registry.npmjs.org/@base44/email/-/email-2.0.0.tgz", "integrity": "sha512-def456..." } } } ``` +**Note:** In Phase 2+, the `resolved` URL may point to `registry.base44.com` for plugins registered there, while still supporting npm URLs for community plugins. + --- ## 6. CLI Commands ### 6.1 New Plugin Commands +Commands are introduced across phases: + ```bash +# ═══════════════════════════════════════════════════════════════ +# PHASE 1 (MVP) - Core plugin management +# ═══════════════════════════════════════════════════════════════ + # Plugin management -base44 plugins add # Install a plugin +base44 plugins add # Install from npm/git/local base44 plugins remove # Remove a plugin base44 plugins list # List installed plugins base44 plugins update [plugin] # Update plugin(s) -base44 plugins info # Show plugin details +base44 plugins info # Show plugin details (from npm) # Plugin development base44 plugins init # Initialize new plugin project base44 plugins validate # Validate plugin structure -base44 plugins publish # Publish to Base44 registry -base44 plugins pack # Create distributable archive +base44 plugins pack # Create distributable tarball # Extension management base44 plugins extend # Scaffold extension for a plugin + +# ═══════════════════════════════════════════════════════════════ +# PHASE 2 - Base44 Registry integration +# ═══════════════════════════════════════════════════════════════ + +base44 plugins search # Search Base44 plugin registry +base44 plugins publish # Publish to Base44 registry +base44 plugins browse # Open registry in browser + +# ═══════════════════════════════════════════════════════════════ +# PHASE 3 - Enterprise features +# ═══════════════════════════════════════════════════════════════ + +base44 plugins config registry # Set private registry URL +base44 plugins verify # Verify plugin signatures +base44 plugins audit # Security audit of plugins ``` ### 6.2 Command Examples ```bash -# Install auth plugin +# Install auth plugin (from npm registry) $ base44 plugins add @base44/auth -◐ Resolving @base44/auth... -✓ Found @base44/auth@1.2.3 +◐ Resolving @base44/auth from npm... +✓ Found @base44/auth@1.2.3 on npm ◐ Checking dependencies... -✓ Requires @base44/email@^2.0.0 -◐ Installing @base44/email@2.0.0... + └─ @base44/email@^2.0.0 (required) +◐ Installing @base44/email@2.0.0 from npm... ✓ Installed @base44/email@2.0.0 ◐ Installing @base44/auth@1.2.3... @@ -546,6 +647,16 @@ Next steps: 2. Run 'base44 deploy' to deploy plugin resources 3. Run 'base44 plugins extend @base44/auth' to customize +# Install from git repository +$ base44 plugins add github:acme/payments-plugin + +◐ Cloning github:acme/payments-plugin... +✓ Cloned to temp directory +◐ Validating plugin structure... +✓ Found base44.plugin.jsonc +◐ Installing acme-payments@0.5.0... +✓ Plugin installed successfully + # List installed plugins $ base44 plugins list @@ -674,19 +785,19 @@ $ base44 plugins init ✓ Created plugin structure: my-plugin/ -├── plugin.jsonc +├── package.json # npm package manifest +├── base44.plugin.jsonc # Base44 plugin config ├── entities/ │ └── .gitkeep ├── functions/ │ └── .gitkeep -├── README.md -└── package.json +└── README.md Next steps: 1. Add entities to entities/ 2. Add functions to functions/ 3. Run 'base44 plugins validate' to check structure - 4. Run 'base44 plugins publish' when ready + 4. Run 'npm publish' to publish to npm (Phase 1) ``` ### 8.2 Plugin Testing @@ -696,7 +807,10 @@ Next steps: $ base44 plugins validate Validating plugin... -✓ plugin.jsonc is valid +✓ package.json is valid +✓ base44.plugin.jsonc is valid +✓ package.json has "base44-plugin" keyword +✓ package.json has base44.type = "plugin" ✓ All exported entities found ✓ All exported functions found ✓ No circular dependencies @@ -712,24 +826,41 @@ $ base44 deploy # Deploy and test ### 8.3 Publishing +**Phase 1 (MVP): Publish to npm** + +```bash +# Standard npm publishing workflow +$ npm login +$ npm publish --access public + +✓ Published @myorg/notifications@1.0.0 to npm + +# Users can now install with: +# base44 plugins add @myorg/notifications +``` + +**Phase 2+: Register with Base44 (optional, for discoverability)** + ```bash $ base44 plugins publish ◐ Validating plugin... ✓ Plugin structure valid -◐ Checking registry... -? Version 1.0.0 does not exist. Publish? Yes +◐ Checking npm registry... +✓ Found @myorg/notifications@1.0.0 on npm -◐ Packaging plugin... -✓ Created @myorg-notifications-1.0.0.tgz (12.3 KB) +◐ Registering with Base44... +? Add to Base44 plugin directory? Yes +? Categories: [notifications, messaging] -◐ Publishing to Base44 registry... -✓ Published @myorg/notifications@1.0.0 +✓ Registered @myorg/notifications@1.0.0 -View at: https://registry.base44.com/plugins/@myorg/notifications +View at: https://plugins.base44.com/@myorg/notifications ``` +**Note:** In Phase 2+, `base44 plugins publish` registers an existing npm package with the Base44 directory for discoverability. The actual package still lives on npm. + --- ## 9. Error Handling From 366268204461a15c35797fa20e506334525e205f Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 26 Jan 2026 13:51:10 +0000 Subject: [PATCH 4/4] docs: make BE function extensions optional in plugin plan Updates to clarify core vs optional features: - Entity extensions: Core feature (Phase 1) - Function hooks/wrappers: Optional, future consideration Changes: - Update Section 4 header with core vs optional callout - Mark Section 4.2 (function hooks) as optional/future - Mark Section 4.3 (function wrapping) as optional/future - Update plugin config to comment out function hooks - Update extensions directory to show entity-only structure - Update summary table with status column (Core/Optional/Phase 3) - Update architecture diagram to show "Entity Extensions (Core)" For Phase 1, host apps can create their own functions that call plugin functions if custom logic is needed. --- docs/plans/plugin-system-plan.md | 61 ++++++++++++++++++-------------- 1 file changed, 34 insertions(+), 27 deletions(-) diff --git a/docs/plans/plugin-system-plan.md b/docs/plans/plugin-system-plan.md index ee442fc8..ae9d9852 100644 --- a/docs/plans/plugin-system-plan.md +++ b/docs/plans/plugin-system-plan.md @@ -57,9 +57,8 @@ Plugins enable: │ └─────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ -│ │ EXTENSIONS │ │ +│ │ ENTITY EXTENSIONS (Core) │ │ │ │ User entity + { companyId, role } │ │ -│ │ login() + custom validation │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘ @@ -151,17 +150,19 @@ Base44-specific configuration lives in a separate file: // Extension points - what can host apps customize "extensible": { + // Entity extensions (Core - Phase 1) "entities": { "User": { "allowAddProperties": true, // Host can add fields "allowOverrideProperties": false // Host cannot change existing fields } - }, - "functions": { - "login": { - "hooks": ["beforeLogin", "afterLogin"] // Available hooks - } } + // Function hooks (Optional - Future consideration) + // "functions": { + // "login": { + // "hooks": ["beforeLogin", "afterLogin"] + // } + // } }, // Plugin configuration schema (validated at install time) @@ -262,7 +263,7 @@ Plugin entities follow the same format as app entities, with additional plugin-s ### 3.2 Plugin Extensions Directory -Host apps can extend plugins through an `extensions/` directory: +Host apps can extend plugin entities through an `extensions/` directory: ``` my-app/ @@ -274,18 +275,19 @@ my-app/ └── extensions/ # NEW: Plugin extensions └── @base44/ └── auth/ - ├── entities/ - │ └── user.extend.jsonc - └── functions/ - └── login/ - └── hooks.ts + └── entities/ + └── user.extend.jsonc ``` --- ## 4. Extension Mechanism -### 4.1 Extending Entity Schemas +> **Core vs Optional:** +> - **Entity Extensions** (4.1): Core feature - available in Phase 1 +> - **Function Extensions** (4.2, 4.3): Optional - future consideration + +### 4.1 Extending Entity Schemas (Core) Host apps can extend plugin entities by adding new properties: @@ -346,9 +348,12 @@ Host apps can extend plugin entities by adding new properties: } ``` -### 4.2 Extending Backend Functions +### 4.2 Extending Backend Functions (Optional - Future) -Host apps can hook into plugin functions at defined extension points: +> **Status:** This feature is optional and may be considered for future phases. +> For Phase 1, host apps can create their own functions that call plugin functions. + +Host apps could hook into plugin functions at defined extension points: ```typescript // extensions/@base44/auth/functions/login/hooks.ts @@ -401,9 +406,11 @@ export const afterLogin: AfterLoginHook = async (context) => { }; ``` -### 4.3 Function Wrapping (Advanced) +### 4.3 Function Wrapping (Optional - Future, Advanced) + +> **Status:** Advanced feature for future consideration. -For more control, host apps can wrap entire plugin functions: +For more control, host apps could wrap entire plugin functions: ```typescript // extensions/@base44/auth/functions/login/wrapper.ts @@ -1144,14 +1151,14 @@ Based on this analysis, we recommend a **phased hybrid approach**: The Plugin System introduces a powerful abstraction for sharing and extending Base44 resources: -| Feature | Benefit | -|---------|---------| -| **Reusable Packages** | Share entities & functions across projects | -| **Version Control** | Lock files ensure reproducible deployments | -| **Extensions** | Customize plugins without forking | -| **Hooks & Wrappers** | Inject custom logic into plugin functions | -| **Multiple Sources** | Install from registry, npm, git, or local | -| **Namespace Safety** | Prevent resource name collisions | -| **Security Model** | Permission system for plugin capabilities | +| Feature | Status | Benefit | +|---------|--------|---------| +| **Reusable Packages** | Core | Share entities & functions across projects | +| **Version Control** | Core | Lock files ensure reproducible deployments | +| **Entity Extensions** | Core | Add properties to plugin schemas without forking | +| **Multiple Sources** | Core | Install from npm, git, or local | +| **Namespace Safety** | Core | Prevent resource name collisions | +| **Function Hooks** | Optional | Inject custom logic into plugin functions (future) | +| **Security Model** | Phase 3 | Permission system for plugin capabilities | This system enables Base44 to evolve from a single-app platform to a composable ecosystem of reusable backend components.