@djangocfg/ext-base 1.0.2 → 1.0.4

package/README.md

@@ -2,6 +2,8 @@
 
 ![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
@@ -37,12 +39,30 @@ The package includes a CLI tool for creating new DjangoCFG extensions:
 # Create a new extension with interactive wizard
 djangocfg-ext create
 
+# Quick test extension (auto-cleanup + unique name)
+djangocfg-ext test
+
+# List all extensions in workspace
+djangocfg-ext list
+
+# Show extension info
+djangocfg-ext info <extension-name>
+
 # Show help
 djangocfg-ext help
 ```
 
 The CLI will guide you through creating a new extension with proper structure and configuration using the `createExtensionConfig` helper.
 
+**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
+- **Playground environment** with Next.js 15 for rapid development
+- Auto-dependency installation and type checking
+- Smart workspace detection for monorepos
+
 ## Quick Start
 
 ### 1. Create extension metadata
@@ -107,7 +127,7 @@ export function MyExtensionProvider({ children }) {
 ### 3. Use in your app
 
 ```typescript
-import { MyExtensionProvider } from '@your-org/my-extension/hooks';
+import { MyExtensionProvider } from '@your-org/my-extension';
 
 export default function RootLayout({ children }) {
   return (
@@ -118,6 +138,94 @@ export default function RootLayout({ children }) {
 }
 ```
 
+## Development Workflow
+
+Every extension created with the CLI includes a **playground** - a Next.js 15 development environment for rapid testing and iteration.
+
+### Starting the Playground
+
+```bash
+cd your-extension
+pnpm dev:playground
+```
+
+This command:
+1. ✅ Automatically builds your extension
+2. ✅ Starts Next.js dev server on port 3333
+3. ✅ Opens browser automatically
+4. ✅ Hot-reloads on source changes
+
+### Playground Features
+
+- **Next.js 15 App Router** with React 19
+- **Tailwind CSS v4** pre-configured
+- **BaseApp** wrapper with theme, auth, and SWR
+- **Auto-build** extension before starting (via `predev` script)
+- **Auto-open browser** when dev server is ready
+- **Hot reload** for instant feedback
+
+### Building for Production
+
+```bash
+# Build extension
+pnpm build
+
+# Build playground
+pnpm build:playground
+
+# Type check
+pnpm check
+```
+
+## Smart Provider Pattern
+
+Extensions support a **Smart Provider Pattern** that allows components to work both standalone and with manual provider wrapping.
+
+### Using withSmartProvider
+
+Create self-contained components that automatically wrap themselves with the provider when needed:
+
+```typescript
+import { withSmartProvider } from '@your-org/my-extension';
+
+// Your component
+function MyComponent() {
+  const { data } = useMyExtension();
+  return <div>{data}</div>;
+}
+
+// Wrap with smart provider
+export const MySmartComponent = withSmartProvider(MyComponent);
+```
+
+**Usage:**
+
+```typescript
+// Works standalone (auto-wrapped)
+<MySmartComponent />
+
+// Also works with manual provider (shares context)
+<MyExtensionProvider>
+  <MySmartComponent />
+  <MySmartComponent />
+</MyExtensionProvider>
+```
+
+**Benefits:**
+- ✅ Components work out-of-the-box without provider boilerplate
+- ✅ Multiple components can still share context when manually wrapped
+- ✅ Best of both worlds - simplicity and flexibility
+
+**When to use:**
+- Library components that should "just work"
+- Components that might be used in isolation
+- Reducing boilerplate for simple use cases
+
+**When to use manual provider:**
+- Multiple components need to share state
+- Performance optimization (single provider instance)
+- Explicit context boundaries
+
 ## Core Features
 
 ### Extension Config Helper
@@ -139,7 +247,6 @@ export const extensionConfig = createExtensionConfig(packageJson, {
   // Optional fields
   minVersion: '2.0.0',
   githubStars: 100,
-  relatedExtensions: ['other-extension'],
   examples: [
     {
       title: 'Example title',
@@ -159,13 +266,20 @@ export const extensionConfig = createExtensionConfig(packageJson, {
 - `homepage` - Homepage URL
 - `githubUrl` - Repository URL
 - `keywords` - Keywords array
-- `peerDependencies` - Peer dependencies
+- `peerDependencies` - Peer dependencies (workspace:* auto-replaced with latest)
+- `packageDependencies` - Dependencies from package.json (workspace:* auto-replaced with latest)
 
 **Auto-generated:**
-- `npmUrl` - npm package URL
+- `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
@@ -264,6 +378,52 @@ 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:**
+
+Extension templates automatically export:
+- `extensionConfig` - Extension metadata
+- `[Name]Provider` - Main provider component (wraps ExtensionProvider)
+- `use[Name]` - Context hook (required provider)
+- `use[Name]Optional` - Context hook (optional provider)
+- `withSmartProvider` - HOC for self-contained components
+
+**Server-safe imports:**
+- Use `@your-org/ext-name/config` to import extension metadata without loading React components
+- This is recommended for 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
@@ -291,14 +451,33 @@ import type {
 
 ## Best Practices
 
+### Configuration & Metadata
 - Use `createExtensionConfig` helper to maintain Single Source of Truth from package.json
-- Always wrap your extension with `ExtensionProvider` for proper registration
 - Use Lucide icon names (not emoji) for `icon` field
 - Include comprehensive `features` list for marketplace visibility
 - Provide code `examples` with proper syntax highlighting
-- Use provided pagination hooks for consistent data fetching
+- **Include a `preview.png` file** in your extension root (1200x630px recommended)
+- List `preview.png` in your package.json `files` array for npm publication
+
+### Development
+- Use the **playground** for rapid development (`pnpm dev:playground`)
+- Test your components in isolation before integrating
+- Run type checks before building (`pnpm check`)
 - Use `createExtensionLogger` with consistent tags for structured logging
-- Separate client-only code using `/hooks` entry point
+
+### Architecture
+- Always wrap your extension with `ExtensionProvider` for proper registration
+- Export main provider as `[Name]Provider` (not `[Name]ExtensionProvider`)
+- Use `withSmartProvider` for components that should work standalone
+- Prefer manual provider wrapping when components need shared state
+- Use provided pagination hooks for consistent data fetching
+- Separate client-only code appropriately
+
+### Publishing
+- Test with `pnpm build` before publishing
+- Verify preview image is accessible via unpkg
+- Ensure all peer dependencies are correctly listed
+- Include clear usage examples in README
 
 ## License
 

package/dist/api.cjs

@@ -0,0 +1,40 @@
+'use strict';
+
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/config.ts
+process.env.NODE_ENV === "development";
+process.env.NODE_ENV === "production";
+var isStaticBuild = process.env.STATIC_BUILD === "true";
+function getApiUrl() {
+  return process.env.NEXT_PUBLIC_API_URL || "/api";
+}
+
+// src/api/createExtensionAPI.ts
+function createExtensionAPI(APIClass) {
+  let storage;
+  try {
+    const { api: accountsApi } = __require("@djangocfg/api");
+    storage = accountsApi._storage;
+  } catch (error) {
+    storage = void 0;
+  }
+  const apiUrl = isStaticBuild ? "" : getApiUrl();
+  return new APIClass(apiUrl, storage ? { storage } : void 0);
+}
+function getSharedAuthStorage() {
+  try {
+    const { api: accountsApi } = __require("@djangocfg/api");
+    return accountsApi._storage;
+  } catch (error) {
+    return void 0;
+  }
+}
+
+exports.createExtensionAPI = createExtensionAPI;
+exports.getSharedAuthStorage = getSharedAuthStorage;

package/dist/api.d.cts

@@ -0,0 +1,35 @@
+/**
+ * Factory for creating extension API instances
+ *
+ * Provides consistent API setup across all extensions with shared authentication
+ */
+/**
+ * Creates an extension API instance with shared authentication storage
+ *
+ * @param APIClass - The generated API class from your extension
+ * @returns Configured API instance with shared auth storage
+ *
+ * @example
+ * ```typescript
+ * // In your extension's api/index.ts
+ * import { API } from './generated/ext_newsletter';
+ * import { createExtensionAPI } from '@djangocfg/ext-base/api';
+ *
+ * export const apiNewsletter = createExtensionAPI(API);
+ * ```
+ */
+declare function createExtensionAPI<T>(APIClass: new (url: string, options?: any) => T): T;
+/**
+ * Get shared authentication storage from accounts API
+ *
+ * @returns Storage instance or undefined if not available
+ *
+ * @example
+ * ```typescript
+ * const storage = getSharedAuthStorage();
+ * const api = new API(apiUrl, { storage });
+ * ```
+ */
+declare function getSharedAuthStorage(): any | undefined;
+
+export { createExtensionAPI, getSharedAuthStorage };

package/dist/api.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Factory for creating extension API instances
+ *
+ * Provides consistent API setup across all extensions with shared authentication
+ */
+/**
+ * Creates an extension API instance with shared authentication storage
+ *
+ * @param APIClass - The generated API class from your extension
+ * @returns Configured API instance with shared auth storage
+ *
+ * @example
+ * ```typescript
+ * // In your extension's api/index.ts
+ * import { API } from './generated/ext_newsletter';
+ * import { createExtensionAPI } from '@djangocfg/ext-base/api';
+ *
+ * export const apiNewsletter = createExtensionAPI(API);
+ * ```
+ */
+declare function createExtensionAPI<T>(APIClass: new (url: string, options?: any) => T): T;
+/**
+ * Get shared authentication storage from accounts API
+ *
+ * @returns Storage instance or undefined if not available
+ *
+ * @example
+ * ```typescript
+ * const storage = getSharedAuthStorage();
+ * const api = new API(apiUrl, { storage });
+ * ```
+ */
+declare function getSharedAuthStorage(): any | undefined;
+
+export { createExtensionAPI, getSharedAuthStorage };

package/dist/api.js

@@ -0,0 +1,2 @@
+export { createExtensionAPI, getSharedAuthStorage } from './chunk-VJEGYVBV.js';
+import './chunk-3RG5ZIWI.js';

package/dist/auth.cjs

@@ -0,0 +1,10 @@
+'use strict';
+
+var auth = require('@djangocfg/api/auth');
+
+
+
+Object.defineProperty(exports, "useAuth", {
+  enumerable: true,
+  get: function () { return auth.useAuth; }
+});

package/dist/auth.d.cts

@@ -0,0 +1 @@
+export { AuthContextType, UserProfile, useAuth } from '@djangocfg/api/auth';

package/dist/auth.d.ts

@@ -0,0 +1 @@
+export { AuthContextType, UserProfile, useAuth } from '@djangocfg/api/auth';

package/dist/auth.js

@@ -0,0 +1,2 @@
+import './chunk-3RG5ZIWI.js';
+export { useAuth } from '@djangocfg/api/auth';

package/dist/chunk-3RG5ZIWI.js

@@ -0,0 +1,8 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+export { __require };

package/dist/chunk-UXTBBEO5.js

@@ -0,0 +1,237 @@
+import { package_default } from './chunk-VJEGYVBV.js';
+import { createConsola } from 'consola';
+
+// src/types/context.ts
+var EXTENSION_CATEGORIES = [
+  { 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" }
+];
+
+// src/utils/createExtensionConfig.ts
+function replaceWorkspaceDeps(deps) {
+  if (!deps) return void 0;
+  const result = {};
+  for (const [key, value] of Object.entries(deps)) {
+    result[key] = value === "workspace:*" ? "latest" : value;
+  }
+  return result;
+}
+function createExtensionConfig(packageJson, config) {
+  const author = typeof packageJson.author === "string" ? packageJson.author : packageJson.author?.name || "Unknown";
+  const githubUrl = typeof packageJson.repository === "string" ? packageJson.repository : packageJson.repository?.url;
+  const packageNameWithoutScope = packageJson.name.split("/").pop() || packageJson.name;
+  const downloadUrl = `https://registry.npmjs.org/${packageJson.name}/-/${packageNameWithoutScope}-${packageJson.version}.tgz`;
+  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}` : void 0,
+    installCommand: `pnpm add ${packageJson.name}`,
+    downloadUrl,
+    tags: packageJson.keywords,
+    preview: `https://unpkg.com/${packageJson.name}@latest/preview.png`
+  };
+}
+
+// src/extensionConfig.ts
+var extensionConfig = createExtensionConfig(package_default, {
+  name: "base",
+  displayName: "Extension Base",
+  category: "utilities",
+  features: [
+    "CLI for creating extensions",
+    "Next.js 15 playground for rapid development",
+    "Smart Provider Pattern for flexible component usage",
+    "Extension context and provider system",
+    "Pagination hooks (standard & infinite scroll)",
+    "API client utilities with auth integration",
+    "Type-safe context creation helpers",
+    "Logging system with structured output",
+    "Environment detection (dev, prod, static)",
+    "TypeScript types and utilities"
+  ],
+  minVersion: "2.0.0",
+  examples: [
+    {
+      title: "Create Extension with CLI",
+      description: "Interactive wizard with playground environment",
+      code: `# Create extension with interactive wizard
+pnpm dlx @djangocfg/ext-base create
+
+# Quick test extension (auto-cleanup)
+pnpm dlx @djangocfg/ext-base test
+
+# List all extensions
+pnpm dlx @djangocfg/ext-base list`,
+      language: "bash"
+    },
+    {
+      title: "Development with Playground",
+      description: "Start Next.js playground for rapid testing",
+      code: `cd your-extension
+
+# Start playground (auto-builds extension + opens browser)
+pnpm dev:playground
+
+# Build for production
+pnpm build
+
+# Type check
+pnpm check`,
+      language: "bash"
+    },
+    {
+      title: "Smart Provider Pattern",
+      description: "Components that work standalone or with shared context",
+      code: `import { withSmartProvider } from '@your-org/my-extension';
+
+// Your component
+function MyComponent() {
+  const { data } = useMyExtension();
+  return <div>{data}</div>;
+}
+
+// Wrap with smart provider
+export const MySmartComponent = withSmartProvider(MyComponent);
+
+// Usage 1: Standalone (auto-wrapped)
+<MySmartComponent />
+
+// Usage 2: Manual provider (shared context)
+<MyExtensionProvider>
+  <MySmartComponent />
+  <MySmartComponent />
+</MyExtensionProvider>`,
+      language: "tsx"
+    },
+    {
+      title: "Extension Provider",
+      description: "Register and wrap your extension",
+      code: `import { ExtensionProvider } from '@djangocfg/ext-base/hooks';
+import { extensionConfig } from './config';
+
+export function MyExtensionProvider({ children }) {
+  return (
+    <ExtensionProvider metadata={extensionConfig}>
+      {children}
+    </ExtensionProvider>
+  );
+}`,
+      language: "tsx"
+    },
+    {
+      title: "Pagination Hooks",
+      description: "Built-in hooks for standard and infinite scroll",
+      code: `import { usePagination, useInfinitePagination } from '@djangocfg/ext-base/hooks';
+
+// Standard pagination
+const { items, page, totalPages, nextPage, prevPage } = usePagination({
+  keyPrefix: 'articles',
+  fetcher: async (page, pageSize) => api.articles.list({ page, page_size: pageSize }),
+  pageSize: 20,
+});
+
+// Infinite scroll
+const { items, isLoading, hasMore, loadMore } = useInfinitePagination({
+  keyPrefix: 'articles',
+  fetcher: async (page, pageSize) => api.articles.list({ page, page_size: pageSize }),
+  pageSize: 20,
+});`,
+      language: "tsx"
+    }
+  ]
+});
+
+// src/utils/errors.ts
+function isExtensionError(error) {
+  return typeof error === "object" && error !== null && "message" in error && "timestamp" in error;
+}
+function createExtensionError(error, code, details) {
+  const message = error instanceof Error ? error.message : String(error);
+  return {
+    message,
+    code,
+    details,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function formatErrorMessage(error) {
+  if (isExtensionError(error)) {
+    return error.code ? `[${error.code}] ${error.message}` : error.message;
+  }
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+function handleExtensionError(error, logger, callback) {
+  const extensionError = isExtensionError(error) ? error : createExtensionError(error);
+  if (logger) {
+    logger.error("Extension error:", extensionError);
+  }
+  if (callback) {
+    callback(extensionError);
+  }
+}
+var isDevelopment = process.env.NODE_ENV === "development";
+var LEVEL_MAP = {
+  debug: 4,
+  info: 3,
+  warn: 2,
+  error: 1
+};
+function createExtensionLogger(options) {
+  const { tag, level = "info", enabled = true } = options;
+  if (!enabled) {
+    const noop = () => {
+    };
+    return {
+      info: noop,
+      warn: noop,
+      error: noop,
+      debug: noop,
+      success: noop
+    };
+  }
+  const logLevel = isDevelopment ? LEVEL_MAP[level] : LEVEL_MAP.error;
+  const consola = createConsola({
+    level: logLevel
+  }).withTag(tag);
+  return {
+    info: (...args) => consola.info(...args),
+    warn: (...args) => consola.warn(...args),
+    error: (...args) => consola.error(...args),
+    debug: (...args) => consola.debug(...args),
+    success: (...args) => consola.success(...args)
+  };
+}
+
+export { EXTENSION_CATEGORIES, createExtensionConfig, createExtensionError, createExtensionLogger, extensionConfig, formatErrorMessage, handleExtensionError, isExtensionError };