@despia/local 1.0.1 → 1.0.2

package/README.md

@@ -418,19 +418,22 @@ export default {
 
 ### Next.js
 
+**For static export (recommended for static sites):**
+
 ```javascript
 // next.config.js
 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
 })({
+  output: 'export',
   // your Next.js config
 });
 ```
 
-**For static export:**
+**For static export (alternative):**
 
 ```javascript
 // next.config.js
@@ -445,22 +448,68 @@ module.exports = withDespiaLocal({
 });
 ```
 
-**Alternative: Webpack Plugin Approach**
+**Alternative: Webpack Plugin Approach (works best for static export):**
 
 ```javascript
 // next.config.js
 const DespiaLocalPlugin = require('@despia/local/webpack');
 
 module.exports = {
+  output: 'export', // For static export
   webpack: (config) => {
     config.plugins.push(
-      new DespiaLocalPlugin({ outDir: '.next' })
+      new DespiaLocalPlugin({ outDir: 'out' })
     );
     return config;
   }
 };
 ```
 
+**Note**: The webpack plugin approach works best for static export. For SSR apps, use the post-build script approach described below.
+
+**For SSR (Server-Side Rendering) apps:**
+
+SSR Next.js apps require special handling because:
+- Client assets are in `.next/static/` directory (not `.next/`)
+- No static HTML files exist (pages are server-rendered)
+- Manifest should only include client-side assets (JS, CSS, images)
+- Server-side code in `.next/server/` should NOT be included
+
+**Recommended approach for SSR (most reliable):**
+
+Use a post-build script in your `package.json`:
+
+```json
+{
+  "scripts": {
+    "build": "next build",
+    "postbuild": "despia-local .next/static"
+  }
+}
+```
+
+This approach:
+- Runs after Next.js build completes
+- Targets `.next/static/` where all client assets are stored
+- Works reliably for both SSR and static export
+- No `entryHtml` needed (SSR apps don't have static HTML files)
+
+**Alternative: Using the plugin (may have timing issues):**
+
+```javascript
+// next.config.js
+const withDespiaLocal = require('@despia/local/next');
+
+module.exports = withDespiaLocal({
+  // entryHtml is optional for SSR (not used)
+  outDir: '.next/static'  // Target client assets directory
+})({
+  // your Next.js config (SSR mode - no output: 'export')
+});
+```
+
+**Note**: The plugin approach may not work reliably for SSR because Next.js doesn't provide a reliable build completion hook. The post-build script approach is recommended for SSR apps.
+
 ### Nuxt
 
 ```javascript
@@ -733,6 +782,30 @@ 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 SSR Issues
+
+**Manifest not generated for SSR app:**
+
+1. Ensure you're targeting `.next/static/` directory (not `.next/`)
+2. Use the post-build script approach: `"postbuild": "despia-local .next/static"`
+3. Verify build completed successfully: `next build` should finish without errors
+4. Check that `.next/static/` directory exists after build
+5. The plugin approach may not work reliably for SSR - prefer post-build script
+
+**Missing assets in SSR manifest:**
+
+- SSR apps only need client assets (JS, CSS, images)
+- Server-side code in `.next/server/` is NOT included (correct behavior)
+- Only assets in `.next/static/` should be in the manifest
+- Verify you're scanning `.next/static/` not `.next/` or `.next/server/`
+
+**Wrong directory for SSR:**
+
+If you see errors about missing directories:
+- For SSR: Use `.next/static/` (client assets only)
+- For static export: Use `out/` (full static site)
+- Never use `.next/server/` (server code, not needed for manifest)
+
 ## Contributing
 
 Contributions welcome! Please open an issue or submit a pull request.

package/generate-offline-manifest.js

@@ -14,21 +14,81 @@
  */
 
 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';
 
+// 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.`);
+  }
+  
+  // 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 
+  });
   
   console.log(`✓ Generated despia/local.json`);
   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)`);
+  }
 } 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.2",
   "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

@@ -51,9 +51,10 @@ export function collectFiles(dir, baseDir = dir) {
  * @param {string} options.outputDir - Output directory path
  * @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)
  * @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 }) {
   const outputPath = resolve(process.cwd(), outputDir);
   const manifestPath = join(outputPath, 'despia', 'local.json');
   
@@ -71,11 +72,13 @@ 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();

package/src/next.js

@@ -1,16 +1,26 @@
 /**
  * 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
  *   })({
+ *     output: 'export',
  *     // your next config
  *   });
  * 
- * Or use the webpack plugin approach:
+ * Usage for SSR (recommended: use post-build script):
+ *   // package.json
+ *   {
+ *     "scripts": {
+ *       "build": "next build",
+ *       "postbuild": "despia-local .next/static"
+ *     }
+ *   }
+ * 
+ * Or use the webpack plugin approach (works best for static export):
  *   const DespiaLocalPlugin = require('@despia/local/webpack');
  *   module.exports = {
  *     webpack: (config) => {
@@ -31,18 +41,33 @@ export function withDespiaLocal(pluginOptions = {}) {
   };
 
   return (nextConfig = {}) => {
+    // Detect if this is static export or SSR
+    const isStaticExport = nextConfig.output === 'export';
     const existingWebpack = nextConfig.webpack;
 
     return {
       ...nextConfig,
       webpack: (config, options) => {
-        // Add Despia Local plugin
-        config.plugins.push(
-          new DespiaLocalPlugin({
-            outDir: localConfig.outDir,
-            entryHtml: localConfig.entryHtml
-          })
-        );
+        // Only add webpack plugin for client builds (not server builds)
+        // For SSR, the webpack plugin will target .next/static during client build
+        // For static export, it works normally
+        if (!options.isServer) {
+          // Determine the correct output directory
+          let targetOutDir = localConfig.outDir;
+          
+          // For SSR apps, target .next/static where client assets are stored
+          if (!isStaticExport && targetOutDir === '.next') {
+            targetOutDir = '.next/static';
+          }
+          
+          config.plugins.push(
+            new DespiaLocalPlugin({
+              outDir: targetOutDir,
+              entryHtml: localConfig.entryHtml,
+              skipEntryHtml: !isStaticExport // Skip entryHtml for SSR
+            })
+          );
+        }
 
         // Call existing webpack config if present
         if (typeof existingWebpack === 'function') {

package/src/webpack.js

@@ -9,6 +9,7 @@ class DespiaLocalPlugin {
     this.options = {
       outDir: options.outDir || 'dist',
       entryHtml: options.entryHtml || 'index.html',
+      skipEntryHtml: options.skipEntryHtml || false,
       ...options
     };
   }
@@ -17,6 +18,19 @@ class DespiaLocalPlugin {
     const pluginName = 'DespiaLocalPlugin';
     
     compiler.hooks.afterEmit.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';
+      
+      // Skip manifest generation for server builds (SSR apps don't need server-side assets)
+      if (isNextJsServerBuild) {
+        callback();
+        return;
+      }
+      
       // Get output path from webpack compiler
       const outputPath = compilation.compiler.outputPath || this.options.outDir;
       const additionalPaths = [];
@@ -41,7 +55,8 @@ class DespiaLocalPlugin {
         const paths = generateManifest({
           outputDir: outputPath,
           entryHtml: this.options.entryHtml,
-          additionalPaths
+          additionalPaths,
+          skipEntryHtml: this.options.skipEntryHtml
         });
         console.log(`✓ Generated despia/local.json with ${paths.length} assets`);
       } catch (error) {