@djangocfg/ext-base 1.0.3 → 1.0.4

package/templates/extension-template/playground/.gitignore.template

@@ -0,0 +1,34 @@
+# Dependencies
+node_modules/
+
+# Next.js
+.next/
+out/
+next-env.d.ts
+
+# Build
+dist/
+build/
+
+# Environment
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+
+# Misc
+.turbo/

package/templates/extension-template/playground/CLAUDE.md

@@ -0,0 +1,35 @@
+# DjangoCFG AI Documentation
+
+## MCP Server
+
+```json
+{
+    "mcpServers": {
+        "djangocfg-docs": {
+            "url": "https://mcp.djangocfg.com/mcp"
+        }
+    }
+}
+```
+
+## CLI
+
+```bash
+# In this project (uses workspace @djangocfg/nextjs)
+pnpm ai-docs search "database configuration"
+pnpm ai-docs mcp
+```
+
+## API
+
+```bash
+curl 'https://mcp.djangocfg.com/api/search?q=database&limit=5'
+```
+
+## TypeScript
+
+```ts
+import { search, getDocs } from '@djangocfg/nextjs/ai';
+
+const results = await search('database configuration');
+```

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

@@ -0,0 +1,76 @@
+# __DISPLAY_NAME__ - Development Playground
+
+This is a Next.js development environment for testing and developing the __DISPLAY_NAME__ extension.
+
+## Quick Start
+
+From the extension root directory, run:
+
+```bash
+# Install dependencies (first time only)
+pnpm install
+
+# Start the development server
+pnpm dev:playground
+```
+
+The playground will be available at **http://localhost:3333**
+
+## What's Included
+
+- **BaseApp Wrapper**: Pre-configured with auth, theme support, and SWR
+- **Hot Module Replacement**: Changes to `src/` files reload automatically
+- **Next.js 15**: Latest App Router with React 19
+- **TypeScript**: Full type safety
+
+## How to Use
+
+1. Open `playground/app/page.tsx`
+2. Import your extension components
+3. Add them to the page
+4. Save and see changes instantly
+
+Example:
+
+```tsx
+import { YourComponent } from '__PACKAGE_NAME__';
+
+export default function PlaygroundPage() {
+  return (
+    <BaseApp>
+      <__PROVIDER_NAME__Provider>
+        <div>
+          <YourComponent />
+        </div>
+      </__PROVIDER_NAME__Provider>
+    </BaseApp>
+  );
+}
+```
+
+## Available Features
+
+- ✅ Auth context via `useAuth()`
+- ✅ Theme switching (light/dark)
+- ✅ SWR data fetching
+- ✅ Error tracking
+- ✅ TypeScript support
+
+## Troubleshooting
+
+**Port 3333 already in use?**
+Edit `playground/package.json` and change the port:
+```json
+"dev": "next dev --port 3334"
+```
+
+**Module not found?**
+Make sure dependencies are installed:
+```bash
+pnpm install
+cd playground && pnpm install
+```
+
+---
+
+**[📖 Documentation](https://djangocfg.com/docs)** • **[⭐ GitHub](https://github.com/markolofsen/django-cfg)**

package/templates/extension-template/playground/app/globals.css.template

@@ -0,0 +1,19 @@
+/**
+ * Global styles for __DISPLAY_NAME__ playground
+ * Single entry point for all styles
+ *
+ * CRITICAL: Import order matters for Tailwind CSS v4!
+ * Theme variables MUST come BEFORE @import "tailwindcss"
+ */
+
+/* 1. Import UI package styles FIRST (contains theme variables) */
+@import "@djangocfg/ui-nextjs/styles";
+
+/* 2. Import layouts styles (may contain additional tokens) */
+@import "@djangocfg/layouts/styles";
+
+/* 3. Import Tailwind CSS v4 (AFTER theme variables) */
+@import "tailwindcss";
+
+/* 4. Load tailwindcss-animate plugin */
+@plugin "tailwindcss-animate";

package/templates/extension-template/playground/app/layout.tsx.template

@@ -0,0 +1,30 @@
+import type { Metadata } from 'next';
+import { Manrope } from 'next/font/google';
+import { BaseApp } from '@djangocfg/layouts';
+import './globals.css';
+
+export const metadata: Metadata = {
+  title: '__DISPLAY_NAME__ - Development Playground',
+  description: 'Development environment for __DISPLAY_NAME__ extension',
+};
+
+const manrope = Manrope({
+  subsets: ['latin', 'cyrillic'],
+  weight: ['400', '500', '600', '700', '800'],
+  variable: '--font-manrope',
+  display: 'swap',
+});
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body className={manrope.className} style={{ fontFamily: manrope.style.fontFamily }}>
+        <BaseApp>{children}</BaseApp>
+      </body>
+    </html>
+  );
+}

package/templates/extension-template/playground/app/page.tsx.template

@@ -0,0 +1,44 @@
+'use client';
+
+import { __PROVIDER_NAME__Provider } from '__PACKAGE_NAME__';
+
+/**
+ * Development playground for __DISPLAY_NAME__ extension
+ *
+ * This page demonstrates how to use the extension in a Next.js application.
+ * The extension is wrapped with __PROVIDER_NAME__Provider which provides
+ * extension-specific context and state management.
+ *
+ * BaseApp (from layout.tsx) provides:
+ * - Theme support (light/dark mode)
+ * - Auth context
+ * - SWR configuration
+ * - Error tracking
+ *
+ * To start development:
+ * 1. Run `pnpm dev:playground` from the extension root
+ * 2. Open http://localhost:3333 in your browser
+ * 3. Make changes to src/ files and see them hot-reload
+ */
+export default function PlaygroundPage() {
+  return (
+    <__PROVIDER_NAME__Provider>
+      <div style={{ padding: '2rem' }}>
+        <h1>__DISPLAY_NAME__ - Development Playground</h1>
+        <p>
+          This is a development environment for testing the __DISPLAY_NAME__ extension.
+        </p>
+
+        <div style={{ marginTop: '2rem', padding: '1rem', border: '1px solid #ccc', borderRadius: '8px' }}>
+          <h2>Add your components here</h2>
+          <p>
+            Import and render your extension components below to test them.
+          </p>
+
+          {/* TODO: Add your extension components here */}
+          {/* Example: <YourComponent /> */}
+        </div>
+      </div>
+    </__PROVIDER_NAME__Provider>
+  );
+}

package/templates/extension-template/playground/next.config.ts.template

@@ -0,0 +1,62 @@
+import type { NextConfig } from 'next';
+import type { Configuration as WebpackConfig, Compiler } from 'webpack';
+
+/**
+ * Simple webpack plugin to auto-open browser in dev mode
+ */
+class AutoOpenBrowserPlugin {
+  private opened = false;
+
+  apply(compiler: Compiler): void {
+    compiler.hooks.done.tap('AutoOpenBrowserPlugin', () => {
+      if (!this.opened) {
+        this.opened = true;
+        this.openBrowser();
+      }
+    });
+  }
+
+  private openBrowser(): void {
+    setTimeout(async () => {
+      try {
+        const { exec } = await import('child_process');
+        const port = process.env.PORT || '3333';
+        const url = `http://localhost:${port}`;
+
+        const command = process.platform === 'darwin'
+          ? 'open'
+          : process.platform === 'win32'
+          ? 'start'
+          : 'xdg-open';
+
+        exec(`${command} ${url}`, (error) => {
+          if (error) {
+            console.warn(`Failed to open browser: ${error.message}`);
+          }
+        });
+      } catch (error) {
+        console.warn('Failed to open browser');
+      }
+    }, 2000);
+  }
+}
+
+const nextConfig: NextConfig = {
+  reactStrictMode: true,
+  transpilePackages: [
+    '__PACKAGE_NAME__',
+    '@djangocfg/api',
+  ],
+  webpack: (config: WebpackConfig, { isServer, dev }) => {
+    // Auto-open browser in dev mode (client-side only)
+    if (dev && !isServer) {
+      if (!config.plugins) {
+        config.plugins = [];
+      }
+      config.plugins.push(new AutoOpenBrowserPlugin());
+    }
+    return config;
+  },
+};
+
+export default nextConfig;

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

@@ -0,0 +1,33 @@
+{
+  "name": "__PACKAGE_NAME__-playground",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Development playground for __DISPLAY_NAME__ extension",
+  "scripts": {
+    "predev": "cd .. && pnpm build",
+    "prebuild": "cd .. && pnpm build",
+    "dev": "next dev --port 3333",
+    "build": "next build",
+    "start": "next start",
+    "ai-docs": "pnpm exec djangocfg-docs"
+  },
+  "dependencies": {
+    "__PACKAGE_NAME__": "workspace:*",
+    "@djangocfg/layouts": "workspace:*",
+    "@djangocfg/ui-core": "workspace:*",
+    "@djangocfg/ui-nextjs": "workspace:*",
+    "@djangocfg/nextjs": "workspace:*",
+    "@djangocfg/api": "workspace:*",
+    "next": "15.5.7",
+    "react": "19.2.0",
+    "react-dom": "19.2.0",
+    "tailwindcss": "^4.1.14",
+    "tailwindcss-animate": "^1.0.7"
+  },
+  "devDependencies": {
+    "@types/node": "^24.7.2",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "typescript": "^5.9.3"
+  }
+}

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

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

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

@@ -4,7 +4,7 @@
  * Main __DISPLAY_NAME__ Context
  */
 
-import { createContext, useContext, type ReactNode } from 'react';
+import React, { createContext, useContext, type ReactNode } from 'react';
 
 interface __PROVIDER_NAME__ContextValue {
   // Add your context values here

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

@@ -7,6 +7,7 @@
 'use client';
 
 import type { ReactNode } from 'react';
+import React from 'react';
 import { ExtensionProvider } from '@djangocfg/ext-base/hooks';
 import { extensionConfig } from '../config';
 import { __PROVIDER_NAME__Provider } from './__PROVIDER_NAME__Context';

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

@@ -1,9 +1,6 @@
 /**
  * @djangocfg/ext-__NAME__
- * Server-safe entry point (no client-only code)
- *
- * Contains types and server-safe exports only.
- * For React hooks and SWR, use '@djangocfg/ext-__NAME__/hooks'
+ * Main entry point for __DISPLAY_NAME__ extension
  */
 
 // ============================================================================
@@ -15,3 +12,14 @@ export { extensionConfig } from './config';
 // Types
 // ============================================================================
 export type * from './types';
+
+// ============================================================================
+// Context & Providers (Client-side)
+// ============================================================================
+export { __PROVIDER_NAME__ExtensionProvider as __PROVIDER_NAME__Provider } from './contexts/__PROVIDER_NAME__ExtensionProvider';
+export { use__PROVIDER_NAME__, use__PROVIDER_NAME__Optional } from './contexts/__PROVIDER_NAME__Context';
+
+// ============================================================================
+// Smart Wrapper Utility
+// ============================================================================
+export { withSmartProvider } from './utils/withSmartProvider';

package/templates/extension-template/src/utils/withSmartProvider.tsx

@@ -0,0 +1,70 @@
+/**
+ * Smart Provider Wrapper
+ *
+ * Automatically wraps components with ExtensionProvider only if needed.
+ * If provider already exists in parent tree, reuses it.
+ *
+ * @example
+ * ```tsx
+ * // Component is automatically wrapped
+ * const SmartComponent = withSmartProvider(MyComponent);
+ *
+ * // Works standalone
+ * <SmartComponent />
+ *
+ * // Also works with manual provider (shares context)
+ * <__PROVIDER_NAME__Provider>
+ *   <SmartComponent />
+ *   <SmartComponent />
+ * </__PROVIDER_NAME__Provider>
+ * ```
+ */
+
+'use client';
+
+import React, { type ComponentType, type ReactNode } from 'react';
+import { __PROVIDER_NAME__ExtensionProvider } from '../contexts/__PROVIDER_NAME__ExtensionProvider';
+import { use__PROVIDER_NAME__Optional } from '../contexts/__PROVIDER_NAME__Context';
+
+/**
+ * HOC that wraps a component with smart provider detection
+ */
+export function withSmartProvider<P extends object>(
+  Component: ComponentType<P>
+): ComponentType<P> {
+  const WrappedComponent = (props: P) => {
+    return (
+      <SmartProviderWrapper>
+        <Component {...props} />
+      </SmartProviderWrapper>
+    );
+  };
+
+  WrappedComponent.displayName = `withSmartProvider(${Component.displayName || Component.name || 'Component'})`;
+
+  return WrappedComponent;
+}
+
+/**
+ * Smart wrapper that only creates provider if not already in tree
+ */
+function SmartProviderWrapper({ children }: { children: ReactNode }) {
+  const existingContext = use__PROVIDER_NAME__Optional();
+
+  // Provider already exists higher in tree - just render children
+  if (existingContext !== undefined) {
+    return <>{children}</>;
+  }
+
+  // No provider found - create one automatically
+  return (
+    <__PROVIDER_NAME__ExtensionProvider>
+      {children}
+    </__PROVIDER_NAME__ExtensionProvider>
+  );
+}
+
+/**
+ * Direct component export for manual usage
+ */
+export { SmartProviderWrapper };