@djangocfg/ext-base 1.0.1 → 1.0.3

package/src/metadata.ts

@@ -0,0 +1,72 @@
+/**
+ * Extension Base configuration
+ */
+
+import type { ExtensionMetadata } from './types';
+import packageJson from '../package.json';
+
+export const extensionConfig: ExtensionMetadata = {
+  name: 'base',
+  version: packageJson.version,
+  author: 'DjangoCFG Team',
+  displayName: 'Extension Base',
+  description: 'Base utilities and common code for building DjangoCFG extensions. Includes CLI tool for managing extensions.',
+  license: 'MIT',
+  githubUrl: 'https://github.com/markolofsen/django-cfg',
+  homepage: 'https://djangocfg.com',
+  keywords: ['base', 'utilities', 'cli', 'toolkit', 'helpers', 'hooks'],
+
+  // Marketplace metadata
+  category: 'utilities',
+  tags: ['base', 'utilities', 'cli', 'toolkit'],
+  features: [
+    'Extension registration system',
+    'React hooks for pagination and infinite scroll',
+    'Environment utilities and helpers',
+    'CLI tool for extension management',
+    'Type-safe context helpers',
+    'Logger utilities',
+  ],
+  npmUrl: `https://www.npmjs.com/package/${packageJson.name}`,
+  installCommand: `pnpm add ${packageJson.name}`,
+  packagePeerDependencies: packageJson.peerDependencies,
+  examples: [
+    {
+      title: 'Basic Extension Setup',
+      description: 'Initialize a new DjangoCFG extension',
+      code: `import { createExtension } from '@djangocfg/ext-base';
+
+const myExtension = createExtension({
+  name: 'my-extension',
+  version: '1.0.0',
+  register: (app) => {
+    console.log('Extension registered!');
+  },
+});
+
+export default myExtension;`,
+      language: 'typescript',
+    },
+    {
+      title: 'Using Pagination Hook',
+      description: 'Implement infinite scroll with usePagination',
+      code: `import { usePagination } from '@djangocfg/ext-base';
+
+function DataList() {
+  const { data, loading, hasMore, loadMore } = usePagination({
+    fetchFn: (page) => fetch(\`/api/data?page=\${page}\`),
+    pageSize: 20,
+  });
+
+  return (
+    <div>
+      {data.map(item => <div key={item.id}>{item.name}</div>)}
+      {hasMore && <button onClick={loadMore}>Load More</button>}
+    </div>
+  );
+}`,
+      language: 'tsx',
+    },
+  ],
+  githubStars: 245,
+};

package/src/types/context.ts

@@ -10,6 +10,60 @@ export interface ExtensionContextOptions {
   revalidateIfStale?: boolean;
 }
 
+/**
+ * Extension category types
+ */
+export type ExtensionCategory =
+  | '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
+
+/**
+ * Extension categories with display names for CLI and UI
+ */
+export const EXTENSION_CATEGORIES: Array<{ title: string; value: ExtensionCategory }> = [
+  { title: 'Forms', value: 'forms' },
+  { title: 'Payments', value: 'payments' },
+  { title: 'Content', value: 'content' },
+  { title: 'Support', value: 'support' },
+  { title: 'Utilities', value: 'utilities' },
+  { title: 'Analytics', value: 'analytics' },
+  { title: 'Security', value: 'security' },
+  { title: 'Integration', value: 'integration' },
+  { title: 'Other', value: 'other' },
+];
+
+/**
+ * Code example for extension documentation
+ */
+export interface ExtensionExample {
+  /**
+   * Example title
+   */
+  title: string;
+
+  /**
+   * Example description
+   */
+  description?: string;
+
+  /**
+   * Code snippet
+   */
+  code: string;
+
+  /**
+   * Programming language for syntax highlighting
+   */
+  language: string;
+}
+
 export interface ExtensionMetadata {
   /**
    * Unique extension name (e.g., 'newsletter', 'payments')
@@ -58,21 +112,94 @@ export interface ExtensionMetadata {
   keywords?: string[];
 
   /**
-   * Extension icon URL or emoji
-   * @example '📧' or 'https://example.com/icon.png'
+   * Minimum required DjangoCFG version
+   */
+  minVersion?: string;
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Marketplace-specific fields
+  // ─────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Extension category for marketplace organization
    */
-  icon?: string;
+  category?: ExtensionCategory;
 
   /**
-   * List of extension dependencies
-   * @example ['payments', 'auth']
+   * Tags for search and filtering
    */
-  dependencies?: string[];
+  tags?: string[];
 
   /**
-   * Minimum required DjangoCFG version
+   * List of key features
    */
-  minVersion?: string;
+  features?: string[];
+
+  /**
+   * npm package URL
+   * @example 'https://www.npmjs.com/package/@djangocfg/ext-newsletter'
+   */
+  npmUrl?: string;
+
+  /**
+   * Marketplace-safe ID (package name with @ and / replaced by -)
+   * @example '@djangocfg/ext-newsletter' -> 'djangocfg-ext-newsletter'
+   */
+  marketplaceId?: string;
+
+  /**
+   * Marketplace URL
+   * @example 'https://hub.djangocfg.com/extensions/djangocfg-ext-newsletter'
+   */
+  marketplaceUrl?: string;
+
+  /**
+   * Installation command
+   * @example 'pnpm add @djangocfg/ext-newsletter'
+   */
+  installCommand?: string;
+
+  /**
+   * Download URL for npm tarball
+   * @example 'https://registry.npmjs.org/@djangocfg/ext-newsletter/-/ext-newsletter-1.0.0.tgz'
+   */
+  downloadUrl?: string;
+
+  /**
+   * Code examples for documentation
+   */
+  examples?: ExtensionExample[];
+
+  /**
+   * npm package dependencies
+   */
+  packageDependencies?: Record<string, string>;
+
+  /**
+   * npm peer dependencies
+   */
+  packagePeerDependencies?: Record<string, string>;
+
+  /**
+   * npm dev dependencies
+   */
+  packageDevDependencies?: Record<string, string>;
+
+  /**
+   * README content in markdown
+   */
+  readme?: string;
+
+  /**
+   * Preview image URL (1200x630 recommended)
+   * @example 'https://unpkg.com/@djangocfg/ext-leads@latest/preview.svg'
+   */
+  preview?: string;
+
+  /**
+   * GitHub stars count
+   */
+  githubStars?: number;
 }
 
 export interface ExtensionProviderProps {

package/src/utils/createExtensionConfig.ts

@@ -0,0 +1,155 @@
+/**
+ * Helper to create extension configuration from package.json
+ */
+
+import type { ExtensionMetadata } from '../types';
+
+/**
+ * Package.json structure
+ */
+interface PackageJson {
+  name: string;
+  version: string;
+  description?: string;
+  keywords?: string[];
+  author?: string | { name: string; email?: string; url?: string };
+  license?: string;
+  homepage?: string;
+  repository?: string | { type: string; url: string; directory?: string };
+  dependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+}
+
+/**
+ * Manual metadata fields that must be provided
+ */
+export interface ExtensionConfigInput {
+  /**
+   * Extension short name (e.g., 'leads', 'payments')
+   */
+  name: string;
+
+  /**
+   * Display name for marketplace
+   */
+  displayName: string;
+
+  /**
+   * Extension category
+   */
+  category: ExtensionMetadata['category'];
+
+  /**
+   * Key features list
+   */
+  features: string[];
+
+  /**
+   * Code examples (optional)
+   */
+  examples?: ExtensionMetadata['examples'];
+
+  /**
+   * Minimum required DjangoCFG version (optional)
+   */
+  minVersion?: string;
+
+  /**
+   * GitHub stars count (optional)
+   */
+  githubStars?: number;
+}
+
+/**
+ * Create extension configuration from package.json + manual metadata
+ *
+ * @example
+ * ```ts
+ * import packageJson from '../package.json';
+ * import { createExtensionConfig } from '@djangocfg/ext-base';
+ *
+ * export const extensionConfig = createExtensionConfig(packageJson, {
+ *   name: 'leads',
+ *   displayName: 'Leads & Forms',
+ *   icon: 'FileText',
+ *   category: 'forms',
+ *   features: [
+ *     'Contact form components',
+ *     'Lead tracking',
+ *   ],
+ * });
+ * ```
+ */
+/**
+ * Replace workspace:* with latest in dependencies
+ */
+function replaceWorkspaceDeps(deps?: Record<string, string>): Record<string, string> | undefined {
+  if (!deps) return undefined;
+
+  const result: Record<string, string> = {};
+  for (const [key, value] of Object.entries(deps)) {
+    result[key] = value === 'workspace:*' ? 'latest' : value;
+  }
+  return result;
+}
+
+export function createExtensionConfig(
+  packageJson: PackageJson,
+  config: ExtensionConfigInput
+): ExtensionMetadata {
+  // Extract author name
+  const author = typeof packageJson.author === 'string'
+    ? packageJson.author
+    : packageJson.author?.name || 'Unknown';
+
+  // Extract repository URL
+  const githubUrl = typeof packageJson.repository === 'string'
+    ? packageJson.repository
+    : packageJson.repository?.url;
+
+  // Generate npm tarball download URL
+  // Format: https://registry.npmjs.org/{package}/-/{name-without-scope}-{version}.tgz
+  const packageNameWithoutScope = packageJson.name.split('/').pop() || packageJson.name;
+  const downloadUrl = `https://registry.npmjs.org/${packageJson.name}/-/${packageNameWithoutScope}-${packageJson.version}.tgz`;
+
+  // Generate marketplace-safe ID (replace @ and / with -)
+  // @djangocfg/ext-newsletter -> djangocfg-ext-newsletter
+  // somepackage -> somepackage
+  const marketplaceId = packageJson.name.replace('@', '').replace('/', '-');
+
+  return {
+    // From package.json
+    name: config.name,
+    version: packageJson.version,
+    author,
+    description: packageJson.description,
+    keywords: packageJson.keywords,
+    license: packageJson.license,
+    homepage: packageJson.homepage,
+    githubUrl,
+    packageDependencies: replaceWorkspaceDeps(packageJson.dependencies),
+    packagePeerDependencies: replaceWorkspaceDeps(packageJson.peerDependencies),
+    packageDevDependencies: replaceWorkspaceDeps(packageJson.devDependencies),
+
+    // From manual config
+    displayName: config.displayName,
+    category: config.category,
+    features: config.features,
+    examples: config.examples,
+    minVersion: config.minVersion,
+    githubStars: config.githubStars,
+
+    // Auto-generated
+    npmUrl: `https://www.npmjs.com/package/${packageJson.name}`,
+    marketplaceId,
+    // Only generate marketplace URL for official @djangocfg extensions
+    marketplaceUrl: packageJson.name.startsWith('@djangocfg/ext-')
+      ? `https://hub.djangocfg.com/extensions/${marketplaceId}`
+      : undefined,
+    installCommand: `pnpm add ${packageJson.name}`,
+    downloadUrl,
+    tags: packageJson.keywords,
+    preview: `https://unpkg.com/${packageJson.name}@latest/preview.png`,
+  };
+}

package/src/utils/index.ts

@@ -8,3 +8,8 @@ export {
   formatErrorMessage,
   handleExtensionError,
 } from './errors';
+
+export {
+  createExtensionConfig,
+  type ExtensionConfigInput,
+} from './createExtensionConfig';

package/templates/extension-template/README.md.template

@@ -0,0 +1,64 @@
+<div align="center">
+
+![DjangoCFG Extension Preview](https://unpkg.com/__PACKAGE_NAME__@latest/preview.png)
+
+__MARKETPLACE_LINK__
+
+</div>
+
+# __PACKAGE_NAME__
+
+__DESCRIPTION__
+
+**Part of [DjangoCFG](https://djangocfg.com)** — modern Django framework for production-ready SaaS applications.
+
+## Features
+
+- Feature 1
+- Feature 2
+- Feature 3
+
+## Install
+
+```bash
+pnpm add __PACKAGE_NAME__
+```
+
+## Usage
+
+### Provider Setup
+
+```typescript
+import { __PROVIDER_NAME__ExtensionProvider } from '__PACKAGE_NAME__/hooks';
+
+export default function RootLayout({ children }) {
+  return (
+    <__PROVIDER_NAME__ExtensionProvider>
+      {children}
+    </__PROVIDER_NAME__ExtensionProvider>
+  );
+}
+```
+
+### Using Hooks
+
+```typescript
+'use client';
+
+import { use__PROVIDER_NAME__ } from '__PACKAGE_NAME__/hooks';
+
+export function MyComponent() {
+  const context = use__PROVIDER_NAME__();
+
+  return <div>Your component</div>;
+}
+```
+
+## License
+
+MIT
+
+## Links
+
+- [DjangoCFG Documentation](https://djangocfg.com)
+- [GitHub](https://github.com/markolofsen/django-cfg)

package/templates/extension-template/package.json.template

@@ -0,0 +1,80 @@
+{
+  "name": "__PACKAGE_NAME__",
+  "version": "1.0.0",
+  "description": "__DESCRIPTION__",
+  "keywords": [
+    "django",
+    "djangocfg",
+    "extension",
+    "__NAME__",
+    "typescript",
+    "react"
+  ],
+  "author": {
+    "name": "DjangoCFG",
+    "url": "https://djangocfg.com"
+  },
+  "homepage": "https://hub.djangocfg.com/extensions/__MARKETPLACE_ID__",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/markolofsen/django-cfg.git"
+  },
+  "bugs": {
+    "url": "https://github.com/markolofsen/django-cfg/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./hooks": {
+      "types": "./dist/hooks.d.ts",
+      "import": "./dist/hooks.js",
+      "require": "./dist/hooks.cjs"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js",
+      "require": "./dist/config.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "preview.png"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "check": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@djangocfg/api": "latest",
+    "@djangocfg/ext-base": "latest",
+    "@djangocfg/ui-core": "latest",
+    "@djangocfg/ui-nextjs": "latest",
+    "consola": "^3.4.2",
+    "lucide-react": "^0.545.0",
+    "next": "^15.5.7",
+    "react": "^18 || ^19",
+    "react-dom": "^18 || ^19",
+    "swr": "^2.3.7"
+  },
+  "devDependencies": {
+    "@djangocfg/api": "latest",
+    "@djangocfg/ext-base": "latest",
+    "@djangocfg/typescript-config": "latest",
+    "@types/node": "^24.7.2",
+    "@types/react": "^19.0.0",
+    "consola": "^3.4.2",
+    "swr": "^2.3.7",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3"
+  }
+}

package/templates/extension-template/src/config.ts

@@ -0,0 +1,34 @@
+/**
+ * __DISPLAY_NAME__ extension configuration
+ */
+
+import { createExtensionConfig } from '@djangocfg/ext-base';
+import packageJson from '../package.json';
+
+export const extensionConfig = createExtensionConfig(packageJson, {
+  name: '__NAME__',
+  displayName: '__DISPLAY_NAME__',
+  category: '__CATEGORY__',
+  features: [
+    'Feature 1',
+    'Feature 2',
+    'Feature 3',
+  ],
+  minVersion: '2.0.0',
+  examples: [
+    {
+      title: 'Basic Usage',
+      description: 'How to use this extension',
+      code: `import { __PROVIDER_NAME__ExtensionProvider } from '__PACKAGE_NAME__/hooks';
+
+export default function RootLayout({ children }) {
+  return (
+    <__PROVIDER_NAME__ExtensionProvider>
+      {children}
+    </__PROVIDER_NAME__ExtensionProvider>
+  );
+}`,
+      language: 'tsx',
+    },
+  ],
+});

package/templates/extension-template/src/contexts/__PROVIDER_NAME__Context.tsx

@@ -0,0 +1,41 @@
+'use client';
+
+/**
+ * Main __DISPLAY_NAME__ Context
+ */
+
+import { createContext, useContext, type ReactNode } from 'react';
+
+interface __PROVIDER_NAME__ContextValue {
+  // Add your context values here
+}
+
+const __PROVIDER_NAME__Context = createContext<__PROVIDER_NAME__ContextValue | undefined>(undefined);
+
+export interface __PROVIDER_NAME__ProviderProps {
+  children: ReactNode;
+}
+
+export function __PROVIDER_NAME__Provider({ children }: __PROVIDER_NAME__ProviderProps) {
+  const value: __PROVIDER_NAME__ContextValue = {
+    // Implement your context logic here
+  };
+
+  return (
+    <__PROVIDER_NAME__Context.Provider value={value}>
+      {children}
+    </__PROVIDER_NAME__Context.Provider>
+  );
+}
+
+export function use__PROVIDER_NAME__() {
+  const context = useContext(__PROVIDER_NAME__Context);
+  if (context === undefined) {
+    throw new Error('use__PROVIDER_NAME__ must be used within __PROVIDER_NAME__Provider');
+  }
+  return context;
+}
+
+export function use__PROVIDER_NAME__Optional() {
+  return useContext(__PROVIDER_NAME__Context);
+}

package/templates/extension-template/src/contexts/__PROVIDER_NAME__ExtensionProvider.tsx

@@ -0,0 +1,36 @@
+/**
+ * Main __DISPLAY_NAME__ Extension Provider
+ *
+ * Wraps all contexts with ExtensionProvider for proper registration
+ */
+
+'use client';
+
+import type { ReactNode } from 'react';
+import { ExtensionProvider } from '@djangocfg/ext-base/hooks';
+import { extensionConfig } from '../config';
+import { __PROVIDER_NAME__Provider } from './__PROVIDER_NAME__Context';
+
+interface __PROVIDER_NAME__ExtensionProviderProps {
+  children: ReactNode;
+}
+
+/**
+ * Main provider for __DISPLAY_NAME__ extension
+ *
+ * @example
+ * ```tsx
+ * <__PROVIDER_NAME__ExtensionProvider>
+ *   <YourApp />
+ * </__PROVIDER_NAME__ExtensionProvider>
+ * ```
+ */
+export function __PROVIDER_NAME__ExtensionProvider({ children }: __PROVIDER_NAME__ExtensionProviderProps) {
+  return (
+    <ExtensionProvider metadata={extensionConfig}>
+      <__PROVIDER_NAME__Provider>
+        {children}
+      </__PROVIDER_NAME__Provider>
+    </ExtensionProvider>
+  );
+}

package/templates/extension-template/src/hooks/index.ts

@@ -0,0 +1,27 @@
+'use client';
+
+/**
+ * __PACKAGE_NAME__/hooks
+ * React hooks and client-only components
+ *
+ * This entry point includes React components, hooks, and SWR functionality.
+ * NOT safe for Server Components.
+ */
+
+// ============================================================================
+// Re-export everything from main entry (types, constants)
+// ============================================================================
+export * from '../index';
+
+// ============================================================================
+// Contexts & Hooks
+// ============================================================================
+export {
+  __PROVIDER_NAME__ExtensionProvider,
+} from '../contexts/__PROVIDER_NAME__ExtensionProvider';
+
+export {
+  __PROVIDER_NAME__Provider,
+  use__PROVIDER_NAME__,
+  use__PROVIDER_NAME__Optional,
+} from '../contexts/__PROVIDER_NAME__Context';