@donotdev/cli 0.0.5 → 0.0.6

package/templates/root-consumer/guides/SETUP_FUNCTIONS.md.example

@@ -4,6 +4,31 @@
 
 ---
 
+## ⚠️ CRITICAL: Import Rules for Functions
+
+**Functions run on Node.js - you MUST use `/server` imports or your function will crash on deploy.**
+
+```typescript
+// ✅ CORRECT - Functions MUST use /server imports
+import { getFirebaseAdminAuth } from '@donotdev/firebase/server';
+import { getFirebaseAdminFirestore } from '@donotdev/firebase/server';
+import { handleError } from '@donotdev/core/server';
+
+// ❌ WRONG - This will crash on deploy (pulls in React/client code)
+import { getAuth } from '@donotdev/firebase';
+import { getFirestore } from '@donotdev/firebase';
+import { handleError } from '@donotdev/core';
+```
+
+**Why?** Functions run in Node.js, not the browser. Client imports (`@donotdev/firebase`) include React and browser-only code that will crash your function.
+
+**Rule:** Always use `/server` suffix for:
+- `@donotdev/firebase/server` (not `@donotdev/firebase`)
+- `@donotdev/core/server` (not `@donotdev/core`)
+- `@donotdev/utils/server` (not `@donotdev/utils`)
+
+---
+
 ## Standard Use
 
 **Structure:**
@@ -59,4 +84,31 @@ export const createCheckoutSession = generic(stripeBackConfig);
 
 ---
 
+## Advanced: Custom Functions with Firebase
+
+**When writing custom functions that access Firestore/Auth, use `/server` imports:**
+
+```typescript
+import { onCall } from 'firebase-functions/v2/https';
+import { FUNCTION_CONFIG } from '@donotdev/functions/firebase';
+// ✅ MUST use /server imports in functions
+import { getFirebaseAdminFirestore } from '@donotdev/firebase/server';
+import { getFirebaseAdminAuth } from '@donotdev/firebase/server';
+import { handleError } from '@donotdev/core/server';
+
+export const myCustomFunction = onCall(FUNCTION_CONFIG, async (request) => {
+  const firestore = getFirebaseAdminFirestore();
+  const auth = getFirebaseAdminAuth();
+  
+  // Your custom logic here
+  const doc = await firestore.collection('users').doc(request.auth.uid).get();
+  
+  return { data: doc.data() };
+});
+```
+
+**Remember:** All Firebase imports in functions MUST use `@donotdev/firebase/server`, never `@donotdev/firebase`.
+
+---
+
 **Add functions, get backend. Framework handles the rest.**

package/templates/root-consumer/guides/SETUP_PAGES.md.example

@@ -111,8 +111,25 @@ import { useNavigate, Link } from '@donotdev/ui';
 const navigate = useNavigate();
 navigate('/about');
 <Link path="/about">About</Link>
+
+// Card with navigation (supports middle-click)
+import { Card } from '@donotdev/components';
+import { Link } from '@donotdev/ui';
+
+<Link
+  path="/about"
+  style={{ display: 'block', textDecoration: 'none', height: '100%' }}
+  aria-label="Learn more about About"
+>
+  <Card title="About" subtitle="Learn more" />
+</Link>
 ```
 
+**Navigation patterns:**
+- **Link component:** Use for text links, buttons, or wrapping other components
+- **Card navigation:** Wrap Card in Link for clickable cards with middle-click support
+- **onClick only:** Use `onClick={() => navigate()}` for actions that don't need middle-click
+
 **Pre-configured:** Navigation menu auto-generated, sitemap auto-built (if `generateSitemap: true`).
 
 ---

package/templates/root-consumer/guides/SETUP_PWA.md.example

@@ -0,0 +1,213 @@
+# PWA Setup
+
+**For AI Agents:** Enable PWA in config, add required app metadata. Framework handles service worker, manifest, and caching.
+
+---
+
+## Quick Start
+
+### 1. Add Required App Metadata
+
+PWA requires `name`, `shortName`, and `description` in your app config:
+
+```typescript
+// src/config/app.ts
+import type { AppConfig } from '@donotdev/core';
+
+export const appConfig: AppConfig = {
+  app: {
+    name: 'My App',              // Full app name (required for PWA)
+    shortName: 'App',            // Short name for home screen (required for PWA)
+    description: 'My app description', // App description (required for PWA)
+    url: 'https://myapp.com',
+  },
+  // ... rest of config
+};
+```
+
+### 2. Enable PWA in Build Config
+
+**For Vite apps:**
+
+```typescript
+// vite.config.ts
+import { defineViteConfig } from '@donotdev/core/vite';
+import { appConfig } from './src/config/app';
+
+export default defineViteConfig({
+  appConfig,
+  pwa: {
+    enabled: true,        // Enable PWA in production builds
+    devEnabled: false,   // Enable PWA in development (optional)
+  },
+});
+```
+
+**For Next.js apps:**
+
+```typescript
+// next.config.ts
+import { defineNextConfig } from '@donotdev/core/next';
+import { appConfig } from './src/config/app';
+
+export default defineNextConfig({
+  appConfig,
+  pwa: {
+    enabled: true,        // Enable PWA in production builds
+    devEnabled: false,   // Enable PWA in development (optional)
+  },
+});
+```
+
+**Done.** Framework automatically:
+- Generates `manifest.json` from app metadata
+- Creates service worker with Workbox
+- Discovers and precaches app icons
+- Sets up offline caching strategies
+
+---
+
+## What Gets Auto-Generated
+
+### Manifest (`manifest.json`)
+- **Name & description:** From `appConfig.app.name`, `shortName`, `description`
+- **Icons:** Auto-discovered from `public/` folder (favicon, apple-touch-icon, etc.)
+- **Theme colors:** Defaults to white background, black theme (customizable)
+- **Display mode:** `standalone` (app-like experience)
+
+### Service Worker (`sw.js`)
+- **Precaching:** All JS, CSS, HTML, icons, and fonts
+- **Runtime caching:** Smart defaults for API calls and images
+- **Offline support:** Navigation fallback to `/`
+- **Update strategy:** Prompts user to update when new version available
+
+### Icons
+Framework discovers icons from:
+- `public/favicon.svg` or `public/favicon.ico`
+- `public/apple-touch-icon.png`
+- Any icons generated by AssetPlugin
+
+---
+
+## Optional Configuration
+
+### Custom Manifest Values
+
+```typescript
+// vite.config.ts or next.config.ts
+export default defineViteConfig({
+  appConfig,
+  pwa: {
+    enabled: true,
+    manifest: {
+      // Override any manifest values
+      theme_color: '#667eea',
+      background_color: '#ffffff',
+      display: 'standalone',
+      orientation: 'portrait',
+    },
+  },
+});
+```
+
+### Custom Workbox Configuration
+
+```typescript
+pwa: {
+  enabled: true,
+  workbox: {
+    // Maximum file size to cache (default: 5MB)
+    maximumFileSizeToCacheInBytes: 5 * 1024 * 1024,
+    
+    // Custom precache patterns
+    globPatterns: ['**/*.{js,css,html,ico,png,svg,woff2}'],
+    globIgnores: ['**/node_modules/**'],
+    
+    // Runtime caching strategies
+    runtimeCaching: [
+      {
+        urlPattern: /^https:\/\/api\.example\.com\/.*/i,
+        handler: 'NetworkFirst',
+        options: {
+          cacheName: 'api-cache',
+          expiration: {
+            maxEntries: 50,
+            maxAgeSeconds: 60 * 60, // 1 hour
+          },
+        },
+      },
+    ],
+  },
+},
+```
+
+### Development Mode
+
+Enable PWA in development for testing:
+
+```typescript
+pwa: {
+  enabled: true,
+  devEnabled: true,  // Enable service worker in dev mode
+  debug: true,       // Enable debug logging
+},
+```
+
+**Note:** Service workers require HTTPS (or localhost). Use `server: { https: true }` in Vite config for local HTTPS.
+
+---
+
+## Testing PWA
+
+1. **Build for production:**
+   ```bash
+   bun run build
+   ```
+
+2. **Serve production build:**
+   ```bash
+   bun run preview  # Vite
+   # or
+   bun run start    # Next.js
+   ```
+
+3. **Test in browser:**
+   - Open DevTools → Application → Service Workers
+   - Check "Offline" checkbox to test offline mode
+   - Verify manifest in Application → Manifest
+   - Test "Add to Home Screen" prompt
+
+---
+
+## Requirements Checklist
+
+- [ ] `appConfig.app.name` defined
+- [ ] `appConfig.app.shortName` defined
+- [ ] `appConfig.app.description` defined
+- [ ] `pwa.enabled: true` in build config
+- [ ] Icons in `public/` folder (auto-discovered)
+- [ ] HTTPS in production (required for service workers)
+
+---
+
+## Troubleshooting
+
+**PWA not working:**
+- Check browser console for service worker errors
+- Verify HTTPS (required except localhost)
+- Check manifest.json exists in build output
+- Verify app metadata is complete
+
+**Icons not showing:**
+- Ensure icons exist in `public/` folder
+- Check icon formats (SVG, PNG, ICO supported)
+- Verify AssetPlugin discovered icons (check build logs)
+
+**Service worker not registering:**
+- Check browser console for registration errors
+- Verify HTTPS (service workers require secure context)
+- Clear browser cache and hard refresh
+
+---
+
+**Zero config. Override when needed.**