@despia/local 1.0.1 → 1.0.3

package/README.md

@@ -343,7 +343,21 @@ Add to your `package.json`:
 Or run manually:
 
 ```bash
-npx despia-local [outputDir] [entryHtml]
+npx despia-local [outputDir] [entryHtml] [--output|-o manifestPath]
+```
+
+**Options:**
+- `--output`, `-o <path>` - Custom output path for manifest file (useful for hosting providers)
+- `--help`, `-h` - Show help message
+
+**Examples:**
+```bash
+# Default: generates manifest in outputDir/despia/local.json
+npx despia-local dist
+
+# Custom output location (e.g., for Vercel/Netlify)
+npx despia-local .next/static --output public/despia/local.json
+npx despia-local dist -o public/manifest.json
 ```
 
 ## Framework Support
@@ -418,48 +432,43 @@ export default {
 
 ### Next.js
 
-```javascript
-// next.config.js
-const withDespiaLocal = require('@despia/local/next');
+**Recommended: Client-Side Apps for Local/Offline Apps**
 
-module.exports = withDespiaLocal({
-  entryHtml: 'index.html',
-  outDir: '.next' // or 'out' for static export
-})({
-  // your Next.js config
-});
-```
+For local/offline apps, we **recommend using client-side frameworks** like React + Vite or Create React App instead of Next.js. Client-side apps are better suited for offline/local deployment because:
 
-**For static export:**
+- All features are client-side by default
+- No server-side dependencies
+- Simpler build and deployment
+- Better offline support
+
+See the [React/Vite](#react--vite) section for examples.
+
+**Supported: Static Export Only**
+
+If you're using Next.js, this plugin supports apps using `output: 'export'` (static export mode). 
 
 ```javascript
 // next.config.js
 const withDespiaLocal = require('@despia/local/next');
 
 module.exports = withDespiaLocal({
-  outDir: 'out', // Next.js static export directory
-  entryHtml: 'index.html'
+  entryHtml: 'index.html',
+  outDir: 'out' // Next.js static export directory
 })({
   output: 'export',
-  // ... rest of config
+  // your Next.js config
 });
 ```
 
-**Alternative: Webpack Plugin Approach**
+**For SSR Apps with Separate Static Build:**
 
-```javascript
-// next.config.js
-const DespiaLocalPlugin = require('@despia/local/webpack');
+If you need SSR for your main site but want a static build for the local app, Next.js can easily generate a separate static build. You can set up a mini CI/CD pipeline to:
 
-module.exports = {
-  webpack: (config) => {
-    config.plugins.push(
-      new DespiaLocalPlugin({ outDir: '.next' })
-    );
-    return config;
-  }
-};
-```
+- Keep your main site as SSR (better for SEO, dynamic content)
+- Generate a separate static export build for the local/offline app
+- Deploy both builds independently
+
+**Note**: Setting up the CI/CD pipeline for dual builds (SSR main site + static local app) requires custom configuration based on your hosting provider and build setup. You'll need to figure out the deployment strategy yourself - this plugin only handles manifest generation for the static export build.
 
 ### Nuxt
 
@@ -733,6 +742,37 @@ The generated manifest is then used by Despia during app hydration and updates t
 - Paths starting with `/` are preserved as-is
 - Windows backslashes are converted to forward slashes
 
+### Next.js Troubleshooting
+
+**Static Export Issues:**
+
+**Manifest not generated:**
+1. Ensure you're using `output: 'export'` in your `next.config.js`
+2. Verify the plugin is correctly configured with `withDespiaLocal()`
+3. Check that `out/` directory exists after build
+4. Ensure `entryHtml` matches your actual entry HTML file
+
+**Wrong directory:**
+- For static export: Use `out/` directory (Next.js default for static export)
+- Never use `.next/` for static export (that's for SSR builds)
+
+**Manifest not accessible:**
+- Manifest is generated in `out/despia/local.json`
+- Ensure your hosting provider serves files from the `out/` directory
+- Static export output should be served as static files
+
+**SSR Apps (Not Officially Supported):**
+
+**Important**: This plugin does **not** officially support Next.js SSR apps. SSR requires custom tooling specific to your hosting provider.
+
+If you choose to use post-build scripts for SSR (unsupported):
+1. Use `.next/static/` directory (client assets only)
+2. Never include `.next/server/` (server code, not needed)
+3. Customize the approach based on your hosting provider's requirements
+4. This is experimental and not guaranteed to work reliably
+
+For production SSR apps, implement provider-specific solutions rather than relying on this plugin.
+
 ## Contributing
 
 Contributions welcome! Please open an issue or submit a pull request.

package/generate-offline-manifest.js

@@ -5,30 +5,142 @@
  * Can be used with any build system by running after build completes
  * 
  * Usage:
- *   node generate-offline-manifest.js [outputDir] [entryHtml]
+ *   node generate-offline-manifest.js [outputDir] [entryHtml] [--output|-o manifestPath]
  * 
  * Examples:
  *   node generate-offline-manifest.js
  *   node generate-offline-manifest.js dist
  *   node generate-offline-manifest.js dist index.html
+ *   node generate-offline-manifest.js .next/static --output public/despia/local.json
+ *   node generate-offline-manifest.js dist -o public/despia/local.json
  */
 
 import { generateManifest } from './src/core.js';
-import { resolve } from 'path';
+import { resolve, join } from 'path';
+import { existsSync } from 'fs';
 
-// Get command line arguments
-const outputDir = process.argv[2] || 'dist';
-const entryHtml = process.argv[3] || 'index.html';
+// Parse command line arguments
+let outputDir = 'dist';
+let entryHtml = 'index.html';
+let manifestOutputPath = null;
+
+// Check for --help flag
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+  console.log(`
+Usage: despia-local [outputDir] [entryHtml] [options]
+
+Arguments:
+  outputDir              Directory to scan for assets (default: 'dist')
+  entryHtml              Entry HTML filename (default: 'index.html')
+
+Options:
+  --output, -o <path>    Custom output path for manifest file
+  --help, -h             Show this help message
+
+Examples:
+  despia-local
+  despia-local dist
+  despia-local dist index.html
+  despia-local .next/static --output public/despia/local.json
+  despia-local dist -o public/manifest.json
+  `);
+  process.exit(0);
+}
+
+// Parse arguments
+for (let i = 2; i < process.argv.length; i++) {
+  const arg = process.argv[i];
+  
+  if (arg === '--output' || arg === '-o') {
+    manifestOutputPath = process.argv[++i];
+    if (!manifestOutputPath) {
+      console.error('❌ Error: --output/-o requires a path argument');
+      process.exit(1);
+    }
+  } else if (outputDir === 'dist' && !arg.startsWith('-')) {
+    outputDir = arg;
+  } else if (!arg.startsWith('-') && entryHtml === 'index.html' && manifestOutputPath === null) {
+    entryHtml = arg;
+  }
+}
+
+// Detect Next.js SSR context
+const isNextJsDir = outputDir.includes('.next');
+const isNextJsStatic = outputDir.includes('.next/static') || outputDir === '.next/static';
+const isNextJsRoot = outputDir === '.next';
+const isNextJsServer = outputDir.includes('.next/server');
+
+// Determine if we should skip entryHtml (for SSR apps)
+const skipEntryHtml = isNextJsStatic || isNextJsServer;
+
+// Provide helpful messages for Next.js
+if (isNextJsDir && !isNextJsStatic && !isNextJsServer) {
+  if (isNextJsRoot) {
+    console.warn('⚠ Warning: Scanning .next/ directory directly.');
+    console.warn('💡 For SSR apps, use: despia-local .next/static');
+    console.warn('💡 For static export, use: despia-local out');
+  }
+}
+
+if (isNextJsServer) {
+  console.error('❌ Error: .next/server/ contains server-side code, not client assets.');
+  console.error('💡 For SSR apps, use: despia-local .next/static');
+  process.exit(1);
+}
 
 try {
-  console.log(`Scanning ${resolve(process.cwd(), outputDir)} for assets...`);
-  const paths = generateManifest({ outputDir, entryHtml });
+  const resolvedPath = resolve(process.cwd(), outputDir);
+  console.log(`Scanning ${resolvedPath} for assets...`);
+  
+  // Check if directory exists, and provide helpful suggestions for Next.js
+  if (!existsSync(resolvedPath)) {
+    if (isNextJsRoot) {
+      console.error(`❌ Directory "${resolvedPath}" does not exist.`);
+      console.error('💡 For SSR apps, try: despia-local .next/static');
+      console.error('💡 For static export, try: despia-local out');
+    }
+    throw new Error(`Output directory "${resolvedPath}" does not exist.`);
+  }
   
-  console.log(`✓ Generated despia/local.json`);
+  // Check for Next.js static directory and suggest if scanning wrong location
+  if (isNextJsRoot && existsSync(join(resolvedPath, 'static'))) {
+    console.warn('⚠ Found .next/static/ subdirectory.');
+    console.warn('💡 For SSR apps, consider scanning .next/static directly for better results.');
+  }
+  
+  const paths = generateManifest({ 
+    outputDir, 
+    entryHtml,
+    skipEntryHtml,
+    manifestOutputPath
+  });
+  
+  const manifestLocation = manifestOutputPath || join(outputDir, 'despia', 'local.json');
+  console.log(`✓ Generated ${manifestLocation}`);
   console.log(`✓ Included ${paths.length} assets`);
-  console.log(`✓ Entry HTML: /${entryHtml}`);
+  if (!skipEntryHtml) {
+    console.log(`✓ Entry HTML: /${entryHtml}`);
+  } else {
+    console.log(`✓ Skipped entry HTML (SSR mode)`);
+  }
+  
+  // Provide helpful hint if using default location for Next.js SSR
+  if (isNextJsStatic && !manifestOutputPath) {
+    console.log('');
+    console.log('💡 Tip: For hosting providers (Vercel, Netlify, etc.), consider using:');
+    console.log(`   despia-local .next/static --output public/despia/local.json`);
+  }
 } catch (error) {
-  console.error(`Error: ${error.message}`);
-  console.error('Please run this script after your build completes.');
+  console.error(`❌ Error: ${error.message}`);
+  console.error('💡 Please run this script after your build completes.');
+  
+  // Additional help for Next.js
+  if (isNextJsDir) {
+    console.error('');
+    console.error('Next.js tips:');
+    console.error('  - SSR apps: Use "despia-local .next/static"');
+    console.error('  - Static export: Use "despia-local out"');
+  }
+  
   process.exit(1);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@despia/local",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Universal build plugin to generate despia/local.json manifest for offline caching in Despia web-native apps. Supports Vite, Webpack, Rollup, Next.js, Nuxt, SvelteKit, Astro, Remix, esbuild, Parcel, and more.",
   "type": "module",
   "main": "./src/core.js",

package/src/core.js

@@ -48,14 +48,20 @@ export function collectFiles(dir, baseDir = dir) {
 /**
  * Generate the offline manifest file
  * @param {Object} options
- * @param {string} options.outputDir - Output directory path
+ * @param {string} options.outputDir - Output directory path (where to scan for assets)
  * @param {string} options.entryHtml - Entry HTML filename (default: 'index.html')
  * @param {string[]} options.additionalPaths - Additional paths to include
+ * @param {boolean} options.skipEntryHtml - Skip adding entry HTML to manifest (for SSR apps)
+ * @param {string} options.manifestOutputPath - Custom path for manifest file (default: outputDir/despia/local.json)
  * @returns {string[]} Array of all asset paths
  */
-export function generateManifest({ outputDir, entryHtml = 'index.html', additionalPaths = [] }) {
+export function generateManifest({ outputDir, entryHtml = 'index.html', additionalPaths = [], skipEntryHtml = false, manifestOutputPath = null }) {
   const outputPath = resolve(process.cwd(), outputDir);
-  const manifestPath = join(outputPath, 'despia', 'local.json');
+  
+  // Use custom manifest output path if provided, otherwise default to outputDir/despia/local.json
+  const manifestPath = manifestOutputPath
+    ? resolve(process.cwd(), manifestOutputPath)
+    : join(outputPath, 'despia', 'local.json');
   
   // Check if output directory exists
   if (!existsSync(outputPath)) {
@@ -71,19 +77,23 @@ export function generateManifest({ outputDir, entryHtml = 'index.html', addition
     assetPaths.add(normalizedPath);
   });
   
-  // Ensure entry HTML is included
-  const entryPath = entryHtml.startsWith('/') 
-    ? entryHtml 
-    : '/' + entryHtml;
-  assetPaths.add(entryPath);
+  // Ensure entry HTML is included (unless skipped for SSR apps)
+  if (!skipEntryHtml) {
+    const entryPath = entryHtml.startsWith('/') 
+      ? entryHtml 
+      : '/' + entryHtml;
+    assetPaths.add(entryPath);
+  }
   
   // Convert to sorted array
   const sortedPaths = Array.from(assetPaths).sort();
   
-  // Create despia directory if it doesn't exist
-  const despiaDir = join(outputPath, 'despia');
-  if (!existsSync(despiaDir)) {
-    mkdirSync(despiaDir, { recursive: true });
+  // Create directory for manifest if it doesn't exist
+  const manifestDir = manifestOutputPath 
+    ? resolve(manifestPath, '..') 
+    : join(outputPath, 'despia');
+  if (!existsSync(manifestDir)) {
+    mkdirSync(manifestDir, { recursive: true });
   }
   
   // Write formatted JSON array

package/src/next.js

@@ -1,15 +1,25 @@
 /**
  * Next.js integration for generating despia/local.json manifest
  * 
- * Usage in next.config.js:
+ * Usage for static export:
  *   const withDespiaLocal = require('@despia/local/next');
  *   module.exports = withDespiaLocal({
  *     entryHtml: 'index.html',
- *     outDir: '.next' // or 'out' for static export
+ *     outDir: 'out' // Next.js static export directory
  *   })({
- *     // your next config
+ *     output: 'export',
+ *     // your Next.js config
  *   });
  * 
+ * For SSR apps, use the post-build script approach:
+ *   // package.json
+ *   {
+ *     "scripts": {
+ *       "build": "next build",
+ *       "postbuild": "despia-local .next/static --output public/despia/local.json"
+ *     }
+ *   }
+ * 
  * Or use the webpack plugin approach:
  *   const DespiaLocalPlugin = require('@despia/local/webpack');
  *   module.exports = {

package/src/webpack.js

@@ -3,49 +3,147 @@
  */
 
 import { generateManifest } from './core.js';
+import { readdirSync } from 'fs';
+import { join, relative, extname } from 'path';
 
 class DespiaLocalPlugin {
   constructor(options = {}) {
     this.options = {
       outDir: options.outDir || 'dist',
       entryHtml: options.entryHtml || 'index.html',
+      skipEntryHtml: options.skipEntryHtml || false,
+      extensions: options.extensions || ['.js', '.css', '.mjs', '.woff', '.woff2', '.ttf', '.eot', '.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', '.ico', '.json', '.xml', '.txt'],
+      publicDir: options.publicDir || null,
       ...options
     };
   }
 
+  /**
+   * Scan public directory for static assets
+   */
+  scanPublicDir(dir, baseDir, assets) {
+    try {
+      const entries = readdirSync(dir, { withFileTypes: true });
+
+      for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+
+        if (entry.isDirectory()) {
+          // Skip despia folder to avoid circular reference
+          if (entry.name !== 'despia') {
+            this.scanPublicDir(fullPath, baseDir, assets);
+          }
+        } else {
+          const ext = extname(entry.name).toLowerCase();
+          if (this.options.extensions.includes(ext)) {
+            const relativePath = '/' + relative(baseDir, fullPath).replace(/\\/g, '/');
+            assets.add(relativePath);
+          }
+        }
+      }
+    } catch (e) {
+      // Ignore permission errors
+    }
+  }
+
   apply(compiler) {
     const pluginName = 'DespiaLocalPlugin';
+    const isNextJs = this.options.isNextJs || false;
+    const injectIntoAssets = this.options.injectIntoAssets || false;
     
-    compiler.hooks.afterEmit.tapAsync(pluginName, (compilation, callback) => {
-      // Get output path from webpack compiler
-      const outputPath = compilation.compiler.outputPath || this.options.outDir;
-      const additionalPaths = [];
+    // For Next.js: Use 'emit' phase to inject into compilation.assets
+    // For other bundlers: Use 'afterEmit' phase to write to filesystem
+    const hook = injectIntoAssets ? compiler.hooks.emit : compiler.hooks.afterEmit;
+    
+    hook.tapAsync(pluginName, (compilation, callback) => {
+      // Detect if this is a Next.js server build
+      // Next.js server builds have specific compiler name patterns
+      const compilerName = compilation.compiler.name || '';
+      const isNextJsServerBuild = (compilerName.includes('server') || 
+                                   compilerName.includes('Server') ||
+                                   compilation.compiler.options?.target === 'node') &&
+                                   isNextJs;
       
-      // Collect all emitted assets
-      for (const [filename, asset] of Object.entries(compilation.assets)) {
-        if (asset) {
-          const rootRelativePath = '/' + filename.replace(/\\/g, '/');
-          additionalPaths.push(rootRelativePath);
-        }
+      // Skip manifest generation for server builds (SSR apps don't need server-side assets)
+      if (isNextJsServerBuild) {
+        callback();
+        return;
       }
       
-      // Also collect from compilation.getAssets() if available (webpack 5)
-      if (compilation.getAssets) {
-        for (const asset of compilation.getAssets()) {
-          const rootRelativePath = '/' + asset.name.replace(/\\/g, '/');
-          additionalPaths.push(rootRelativePath);
-        }
-      }
+      const assets = new Set();
       
-      try {
-        const paths = generateManifest({
-          outputDir: outputPath,
-          entryHtml: this.options.entryHtml,
-          additionalPaths
-        });
-        console.log(`✓ Generated despia/local.json with ${paths.length} assets`);
-      } catch (error) {
-        console.error('Error generating despia/local.json:', error.message);
+      if (injectIntoAssets && isNextJs) {
+        // Next.js mode: Collect from webpack compilation and public folder
+        
+        // 1. Collect all webpack-generated assets from .next/static
+        for (const filename of Object.keys(compilation.assets)) {
+          if (filename === this.options.manifestPath) {
+            continue; // Skip the manifest file itself
+          }
+          
+          const ext = extname(filename).toLowerCase();
+          if (this.options.extensions.includes(ext)) {
+            // Next.js serves these at /_next/static/...
+            assets.add(`/_next/static/${filename}`);
+          }
+        }
+        
+        // 2. Scan /public folder for static assets
+        if (this.options.publicDir) {
+          this.scanPublicDir(this.options.publicDir, this.options.publicDir, assets);
+        }
+        
+        // 3. Generate sorted array (Despia format - just a JSON array)
+        const manifest = JSON.stringify([...assets].sort(), null, 2);
+        
+        // 4. Inject into webpack output at despia/local.json
+        const manifestPath = this.options.manifestPath || 'despia/local.json';
+        compilation.assets[manifestPath] = {
+          source: () => manifest,
+          size: () => Buffer.byteLength(manifest, 'utf8')
+        };
+        
+        console.log(`✓ Injected despia/local.json into build with ${assets.size} assets`);
+      } else {
+        // Traditional mode: Write to filesystem (for other bundlers)
+        const additionalPaths = new Set();
+        
+        // Collect all emitted assets from compilation
+        for (const [filename, asset] of Object.entries(compilation.assets)) {
+          if (asset && filename !== this.options.manifestPath) {
+            let rootRelativePath = filename.replace(/\\/g, '/');
+            if (!rootRelativePath.startsWith('/')) {
+              rootRelativePath = '/' + rootRelativePath;
+            }
+            additionalPaths.add(rootRelativePath);
+          }
+        }
+        
+        // Also collect from compilation.getAssets() if available (webpack 5)
+        if (compilation.getAssets) {
+          for (const asset of compilation.getAssets()) {
+            if (asset.name !== this.options.manifestPath) {
+              let assetPath = asset.name.replace(/\\/g, '/');
+              if (!assetPath.startsWith('/')) {
+                assetPath = '/' + assetPath;
+              }
+              additionalPaths.add(assetPath);
+            }
+          }
+        }
+        
+        try {
+          const outputPath = compilation.compiler.outputPath || this.options.outDir;
+          const paths = generateManifest({
+            outputDir: outputPath,
+            entryHtml: this.options.entryHtml,
+            additionalPaths: Array.from(additionalPaths),
+            skipEntryHtml: this.options.skipEntryHtml
+          });
+          console.log(`✓ Generated despia/local.json with ${paths.length} assets`);
+        } catch (error) {
+          console.error('Error generating despia/local.json:', error.message);
+        }
       }
       
       callback();