@djangocfg/ext-base 1.0.3 → 1.0.4

package/README.md

@@ -39,6 +39,15 @@ 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
 ```
@@ -50,6 +59,9 @@ The CLI will guide you through creating a new extension with proper structure an
 - 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
 
@@ -115,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 (
@@ -126,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
@@ -279,8 +379,17 @@ function MyComponent() {
 | `@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 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
 
@@ -342,17 +451,34 @@ 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 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
+- **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
+
+### 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
 
 MIT

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 };