@despia/local 1.0.2 → 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,7 +432,20 @@ export default {
 
 ### Next.js
 
-**For static export (recommended for static sites):**
+**Recommended: Client-Side Apps for Local/Offline Apps**
+
+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:
+
+- 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
@@ -433,82 +460,15 @@ module.exports = withDespiaLocal({
 });
 ```
 
-**For static export (alternative):**
+**For SSR Apps with Separate Static Build:**
 
-```javascript
-// next.config.js
-const withDespiaLocal = require('@despia/local/next');
+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 = withDespiaLocal({
-  outDir: 'out', // Next.js static export directory
-  entryHtml: 'index.html'
-})({
-  output: 'export',
-  // ... rest of 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
 
-**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: '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.
+**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
 
@@ -782,29 +742,36 @@ 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
+### 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
 
-**Manifest not generated for SSR app:**
+**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)
 
-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
+**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
 
-**Missing assets in SSR manifest:**
+**SSR Apps (Not Officially Supported):**
 
-- 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/`
+**Important**: This plugin does **not** officially support Next.js SSR apps. SSR requires custom tooling specific to your hosting provider.
 
-**Wrong directory for SSR:**
+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
 
-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)
+For production SSR apps, implement provider-specific solutions rather than relying on this plugin.
 
 ## Contributing
 

package/generate-offline-manifest.js

@@ -5,21 +5,64 @@
  * 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, 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');
@@ -68,16 +111,25 @@ try {
   const paths = generateManifest({ 
     outputDir, 
     entryHtml,
-    skipEntryHtml 
+    skipEntryHtml,
+    manifestOutputPath
   });
   
-  console.log(`✓ Generated despia/local.json`);
+  const manifestLocation = manifestOutputPath || join(outputDir, 'despia', 'local.json');
+  console.log(`✓ Generated ${manifestLocation}`);
   console.log(`✓ Included ${paths.length} assets`);
   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.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@despia/local",
-  "version": "1.0.2",
+  "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,15 +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 = [], skipEntryHtml = false }) {
+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)) {
@@ -83,10 +88,12 @@ export function generateManifest({ outputDir, entryHtml = 'index.html', addition
   // 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

@@ -8,19 +8,19 @@
  *     outDir: 'out' // Next.js static export directory
  *   })({
  *     output: 'export',
- *     // your next config
+ *     // your Next.js config
  *   });
  * 
- * Usage for SSR (recommended: use post-build script):
+ * For SSR apps, use the post-build script approach:
  *   // package.json
  *   {
  *     "scripts": {
  *       "build": "next build",
- *       "postbuild": "despia-local .next/static"
+ *       "postbuild": "despia-local .next/static --output public/despia/local.json"
  *     }
  *   }
  * 
- * Or use the webpack plugin approach (works best for static export):
+ * Or use the webpack plugin approach:
  *   const DespiaLocalPlugin = require('@despia/local/webpack');
  *   module.exports = {
  *     webpack: (config) => {
@@ -41,33 +41,18 @@ 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) => {
-        // 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
-            })
-          );
-        }
+        // Add Despia Local plugin
+        config.plugins.push(
+          new DespiaLocalPlugin({
+            outDir: localConfig.outDir,
+            entryHtml: localConfig.entryHtml
+          })
+        );
 
         // Call existing webpack config if present
         if (typeof existingWebpack === 'function') {

package/src/webpack.js

@@ -3,6 +3,8 @@
  */
 
 import { generateManifest } from './core.js';
+import { readdirSync } from 'fs';
+import { join, relative, extname } from 'path';
 
 class DespiaLocalPlugin {
   constructor(options = {}) {
@@ -10,20 +12,57 @@ class DespiaLocalPlugin {
       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;
+    
+    // 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;
     
-    compiler.hooks.afterEmit.tapAsync(pluginName, (compilation, callback) => {
+    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') || 
+      const isNextJsServerBuild = (compilerName.includes('server') || 
                                    compilerName.includes('Server') ||
-                                   compilation.compiler.options?.target === 'node';
+                                   compilation.compiler.options?.target === 'node') &&
+                                   isNextJs;
       
       // Skip manifest generation for server builds (SSR apps don't need server-side assets)
       if (isNextJsServerBuild) {
@@ -31,36 +70,80 @@ class DespiaLocalPlugin {
         return;
       }
       
-      // Get output path from webpack compiler
-      const outputPath = compilation.compiler.outputPath || this.options.outDir;
-      const additionalPaths = [];
+      const assets = new Set();
       
-      // Collect all emitted assets
-      for (const [filename, asset] of Object.entries(compilation.assets)) {
-        if (asset) {
-          const rootRelativePath = '/' + filename.replace(/\\/g, '/');
-          additionalPaths.push(rootRelativePath);
+      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}`);
+          }
         }
-      }
-      
-      // 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);
+        
+        // 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);
         }
-      }
-      
-      try {
-        const paths = generateManifest({
-          outputDir: outputPath,
-          entryHtml: this.options.entryHtml,
-          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();