@djangocfg/ext-base 1.0.1 → 1.0.3

package/README.md

@@ -1,3 +1,11 @@
+<div align="center">
+
+![DjangoCFG Extension Preview](https://unpkg.com/@djangocfg/ext-base@latest/preview.png)
+
+**[📦 View in Marketplace](https://hub.djangocfg.com/extensions/djangocfg-ext-base)** • **[📖 Documentation](https://djangocfg.com)** • **[⭐ GitHub](https://github.com/markolofsen/django-cfg)**
+
+</div>
+
 # @djangocfg/ext-base
 
 Base utilities and common code for building DjangoCFG extensions.
@@ -25,50 +33,67 @@ pnpm add @djangocfg/ext-base
 
 ## CLI Usage
 
-The package includes a CLI tool for managing DjangoCFG extensions:
+The package includes a CLI tool for creating new DjangoCFG extensions:
 
 ```bash
-# List available extensions
-djangocfg-ext list
-
-# Show extension info
-djangocfg-ext info ext-leads
-
-# Interactive installation wizard
-djangocfg-ext install
-
-# Initialize extension in your project
-djangocfg-ext init
+# Create a new extension with interactive wizard
+djangocfg-ext create
 
 # Show help
 djangocfg-ext help
 ```
 
-### Available Extensions
+The CLI will guide you through creating a new extension with proper structure and configuration using the `createExtensionConfig` helper.
 
-- **@djangocfg/ext-leads** - Lead management and contact forms
-- **@djangocfg/ext-payments** - Payment processing with multiple providers
-- **@djangocfg/ext-newsletter** - Newsletter and email campaigns
-- **@djangocfg/ext-support** - Customer support and ticketing
-- **@djangocfg/ext-knowbase** - Knowledge base and documentation
+**Features:**
+- Interactive prompts for package name, description, icon, and category
+- Automatic npm registry validation to prevent duplicate package names
+- Support for both scoped (`@my-org/my-extension`) and unscoped (`my-extension`) package names
+- Template generation with proper placeholder replacement
 
 ## Quick Start
 
 ### 1. Create extension metadata
 
+Use the `createExtensionConfig` helper to automatically pull data from package.json:
+
 ```typescript
 // src/config.ts
-import type { ExtensionMetadata } from '@djangocfg/ext-base';
+import { createExtensionConfig } from '@djangocfg/ext-base';
+import packageJson from '../package.json';
 
-export const extensionConfig: ExtensionMetadata = {
+export const extensionConfig = createExtensionConfig(packageJson, {
   name: 'my-extension',
-  version: '1.0.0',
   displayName: 'My Extension',
-  description: 'Amazing extension functionality',
-  icon: '🚀',
-};
+  icon: 'Rocket', // Lucide icon name
+  category: 'utilities',
+  features: [
+    'Feature 1',
+    'Feature 2',
+    'Feature 3',
+  ],
+  minVersion: '2.0.0',
+  examples: [
+    {
+      title: 'Basic Usage',
+      description: 'How to use this extension',
+      code: `import { MyComponent } from '@your-org/my-extension';`,
+      language: 'tsx',
+    },
+  ],
+});
 ```
 
+This automatically imports from package.json:
+- version
+- author
+- description
+- license
+- homepage
+- githubUrl (from repository)
+- keywords
+- peerDependencies
+
 ### 2. Create extension provider
 
 ```typescript
@@ -103,6 +128,58 @@ export default function RootLayout({ children }) {
 
 ## Core Features
 
+### Extension Config Helper
+
+The `createExtensionConfig` helper creates a typed extension configuration by combining package.json data with manual metadata:
+
+```typescript
+import { createExtensionConfig, type ExtensionConfigInput } from '@djangocfg/ext-base';
+import packageJson from '../package.json';
+
+export const extensionConfig = createExtensionConfig(packageJson, {
+  // Required fields
+  name: 'my-extension',
+  displayName: 'My Extension',
+  icon: 'Package', // Lucide icon name
+  category: 'utilities', // 'forms' | 'payments' | 'content' | 'support' | 'utilities' | 'analytics' | 'security' | 'integration' | 'other'
+  features: ['Feature list for marketplace'],
+
+  // Optional fields
+  minVersion: '2.0.0',
+  githubStars: 100,
+  examples: [
+    {
+      title: 'Example title',
+      description: 'Example description',
+      code: 'import { Component } from "@your-org/my-extension";',
+      language: 'tsx',
+    },
+  ],
+});
+```
+
+**Automatically imported from package.json:**
+- `version` - Package version
+- `author` - Author name (from string or object)
+- `description` - Package description
+- `license` - License type
+- `homepage` - Homepage URL
+- `githubUrl` - Repository URL
+- `keywords` - Keywords array
+- `peerDependencies` - Peer dependencies (workspace:* auto-replaced with latest)
+- `packageDependencies` - Dependencies from package.json (workspace:* auto-replaced with latest)
+
+**Auto-generated:**
+- `npmUrl` - npm package URL (`https://www.npmjs.com/package/[name]`)
+- `marketplaceId` - URL-safe ID (@ and / replaced with -), e.g. `@djangocfg/ext-newsletter` → `djangocfg-ext-newsletter`
+- `marketplaceUrl` - Marketplace URL (only for official @djangocfg extensions): `https://hub.djangocfg.com/extensions/[marketplaceId]`
+- `installCommand` - pnpm install command
+- `downloadUrl` - npm tarball download URL
+- `preview` - Preview image URL (`https://unpkg.com/[name]@latest/preview.png`)
+- `tags` - Same as keywords
+
+> **Note:** All `workspace:*` dependencies are automatically replaced with `latest` for marketplace display.
+
 ### Environment Configuration
 
 ```typescript
@@ -201,16 +278,63 @@ function MyComponent() {
 | `@djangocfg/ext-base/auth` | Auth re-exports (useAuth, types) | Client components only |
 | `@djangocfg/ext-base/api` | API utilities (createExtensionAPI, getSharedAuthStorage) | Server & client components |
 
+**For your own extensions:**
+- Use `@your-org/ext-name/config` to import extension metadata without loading React components (server-safe)
+- This is the recommended way to import `extensionConfig` in server components and build tools
+
+## Extension Categories
+
+The package exports a standardized list of extension categories:
+
+```typescript
+import { EXTENSION_CATEGORIES } from '@djangocfg/ext-base';
+
+// Array of { title: string, value: ExtensionCategory }
+EXTENSION_CATEGORIES.forEach(category => {
+  console.log(category.title, category.value);
+  // Forms, forms
+  // Payments, payments
+  // Content, content
+  // Support, support
+  // Utilities, utilities
+  // Analytics, analytics
+  // Security, security
+  // Integration, integration
+  // Other, other
+});
+```
+
+Available categories:
+- `forms` - Forms, CRM, Lead Management
+- `payments` - Payment Processing, Billing
+- `content` - Content Management, Marketing
+- `support` - Support, Helpdesk, Tickets
+- `utilities` - Tools, Base, Infrastructure
+- `analytics` - Analytics, Tracking, Monitoring
+- `security` - Security, Authentication, Authorization
+- `integration` - Third-party Integrations
+- `other` - Other/Uncategorized
+
 ## TypeScript Types
 
 ```typescript
 import type {
+  // Extension configuration
   ExtensionMetadata,
+  ExtensionConfigInput,
+  ExtensionCategory,
+  ExtensionExample,
+
+  // Provider
   ExtensionProviderProps,
+
+  // Pagination
   PaginatedResponse,
   PaginationParams,
   PaginationState,
   InfinitePaginationReturn,
+
+  // Utilities
   ExtensionLogger,
   ExtensionError,
 } from '@djangocfg/ext-base';
@@ -218,11 +342,16 @@ import type {
 
 ## Best Practices
 
+- Use `createExtensionConfig` helper to maintain Single Source of Truth from package.json
 - Always wrap your extension with `ExtensionProvider` for proper registration
-- Define complete metadata in `config.ts`
+- Use Lucide icon names (not emoji) for `icon` field
+- **Include a `preview.png` file** in your extension root (1200x630px recommended) - it will be automatically served via unpkg
+- Include comprehensive `features` list for marketplace visibility
+- Provide code `examples` with proper syntax highlighting
 - Use provided pagination hooks for consistent data fetching
 - Use `createExtensionLogger` with consistent tags for structured logging
 - Separate client-only code using `/hooks` entry point
+- List `preview.png` in your package.json `files` array for npm publication
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ext-base",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Base utilities and common code for DjangoCFG extensions",
   "keywords": [
     "django",
@@ -15,7 +15,7 @@
     "name": "DjangoCFG",
     "url": "https://djangocfg.com"
   },
-  "homepage": "https://djangocfg.com",
+  "homepage": "https://hub.djangocfg.com/extensions/djangocfg-ext-base",
   "repository": {
     "type": "git",
     "url": "https://github.com/markolofsen/django-cfg.git",
@@ -27,33 +27,35 @@
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.cjs",
-  "module": "./dist/index.mjs",
+  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
+      "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
     "./hooks": {
       "types": "./dist/hooks.d.ts",
-      "import": "./dist/hooks.mjs",
+      "import": "./dist/hooks.js",
       "require": "./dist/hooks.cjs"
     },
     "./auth": {
       "types": "./dist/auth.d.ts",
-      "import": "./dist/auth.mjs",
+      "import": "./dist/auth.js",
       "require": "./dist/auth.cjs"
     },
     "./api": {
       "types": "./dist/api.d.ts",
-      "import": "./dist/api.mjs",
+      "import": "./dist/api.js",
       "require": "./dist/api.cjs"
     }
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "preview.png",
+    "templates"
   ],
   "bin": {
     "djangocfg-ext": "./dist/cli.mjs"
@@ -64,6 +66,7 @@
     "check": "tsc --noEmit",
     "cli": "tsx src/cli/index.ts",
     "cli:help": "tsx src/cli/index.ts --help",
+    "cli:create": "tsx src/cli/index.ts create",
     "cli:list": "tsx src/cli/index.ts list",
     "cli:info": "tsx src/cli/index.ts info"
   },