weweb-dynamic-metadata 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Melina Reisinger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,412 @@
+# weweb-dynamic-metadata
+⭐ Build-time SEO metadata generator for WeWeb static exports
+
+[![npm version](https://img.shields.io/npm/v/weweb-dynamic-metadata)](https://www.npmjs.com/package/weweb-dynamic-metadata)
+[![npm downloads](https://img.shields.io/npm/dm/weweb-dynamic-metadata)](https://www.npmjs.com/package/weweb-dynamic-metadata)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![GitHub stars](https://img.shields.io/github/stars/Mel000000/weweb-dynamic-metadata?style=social)](https://github.com/Mel000000/weweb-dynamic-metadata)
+
+A build-time tool that generates unique SEO metadata for each dynamic page in your WeWeb project. Zero runtime overhead, perfect SEO, and completely free.
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Why This Package Matters](#why-this-package-matters)
+- [Who This Is For](#who-this-is-for)
+- [Why This Project Exists](#why-this-project-exists)
+- [Usage Example](#usage-example)
+- [Architecture](#architecture)
+- [Features](#features)
+- [Quick Start](#quick-start)
+- [Prerequisites Checklist](#prerequisites-checklist)
+- [Setup](#setup)
+  - [1. Configure Supabase](#1-configure-supabase)
+  - [2. Create Config File](#2-create-config-file)
+  - [3. Run the Generator](#3-run-the-generator)
+- [How It Works](#how-it-works)
+  - [1. Reads Your Config](#1-reads-your-config)
+  - [2. Discovers Content IDs](#2-discovers-content-ids)
+  - [3. Fetches Metadata](#3-fetches-metadata)
+  - [4. Generates Central Metadata](#4-generates-central-metadata)
+  - [5. Injects Script into Template](#5-injects-script-into-template)
+  - [6. Creates Reference Files](#6-creates-reference-files)
+- [Project Folder Transformation](#project-folder-transformation)
+- [Output Summary](#output-summary)
+- [Programmatic Usage](#programmatic-usage)
+- [Why Not Cloudflare Workers?](#why-not-cloudflare-workers)
+- [Troubleshooting](#troubleshooting)
+- [License](#license)
+---
+
+## Overview
+
+WeWeb exports static HTML files where all dynamic routes (like `/article/1`, `/article/2`) share the **exact same HTML template** with identical metadata. This is terrible for SEO - every article page looks identical to search engines.
+
+This package solves that by generating a **central metadata file** and **tiny reference HTML files** that point to your main template. The result? Each article page gets its own unique metadata while maintaining a single source of truth.
+
+### Repository Structure
+- **📦 This Package**: The npm package that does the metadata generation
+- **📦 Your WeWeb Project**: Where you install and run it
+
+### Key challenges addressed:
+- Complete generation in ~1 second for 100 articles  
+- Zero runtime overhead - all metadata pre-generated
+- Tiny footprint - only ~500 bytes per article
+
+---
+
+## Why This Package Matters
+
+WeWeb currently has **no built-in solution** for dynamic SEO metadata. Every dynamic page shares the same HTML template, making SEO optimization impossible.
+
+This package provides a **production-tested solution** that:
+- Gives each page unique metadata
+- Requires no serverless functions
+- Works with any hosting platform
+- Preserves all WeWeb dynamic functionality
+
+---
+
+## Who This Is For
+
+This package is ideal for:
+
+- WeWeb users needing SEO for dynamic pages
+- Developers deploying WeWeb to any static host
+- Projects requiring unique metadata per page
+- Teams wanting zero-latency SEO solution
+
+This package may NOT be ideal if:
+
+- Your content changes every minute (use server-side instead)
+- You can't run build scripts in your deployment
+- You need real-time metadata updates
+
+---
+
+## Why This Project Exists
+
+WeWeb's dynamic pages share HTML templates, making unique metadata impossible. Official solutions require Cloudflare Workers (cost, complexity, latency).
+
+This project provides a **simpler, cheaper, faster alternative**:
+
+- **Zero runtime costs** - Everything runs at build time
+- **Perfect SEO** - Instant HTML for crawlers
+- **Dead simple** - Just a config file and one command
+- **Works everywhere** - Any static hosting works
+
+---
+
+## Usage Example
+
+1. Export your WeWeb project (creates `dist/` folder)
+2. Create `weweb.config.js` in your project root
+3. Run `npx weweb-dynamic-metadata`
+4. Deploy anywhere - each article now has unique metadata!
+
+```bash
+# One-time setup
+npm install --save-dev weweb-dynamic-metadata
+
+# Generate metadata (run after each WeWeb export)
+npx weweb-dynamic-metadata
+
+# That's it! Your articles now have unique SEO metadata
+```
+
+## Features
+
+- 🚀 **Zero Runtime Overhead**: All metadata pre-generated at build time
+- 📦 **Tiny Footprint**: Only ~500 bytes per article (reference files)
+- 🎯 **Perfect SEO**: Each page gets unique titles, descriptions, and Open Graph tags
+- 🔧 **Simple Setup**: Just add a config file and run
+- 💸 **Completely Free**: No Cloudflare Workers, no serverless costs
+- 🌍 **Works Everywhere**: Deploy to any static hosting (Netlify, Vercel, GitHub Pages, S3, etc.)
+- ⚡ **Fast**: Generates 1000 articles in ~3 seconds
+- 🔗 **Commit Traceability**: Optional git-info.js injection for deploy visibility
+
+## Quick Start
+```bash
+# 1. Install the package
+npm install --save-dev weweb-dynamic-metadata
+
+# 2. Create weweb.config.js in your project root
+# (see Setup section below)
+
+# 3. Run it!
+npx weweb-dynamic-metadata
+
+# Done! Your articles now have unique metadata
+```
+## Getting Started
+
+###  Prerequisites Checklist
+Before using this package, ensure you have:
+- A WeWeb project exported to static files (has ``article/_param/index.html``)
+- Node.js 18 or higher installed
+- A Supabase project with your content
+- Your Supabase URL and anon key ready
+- Your WeWeb build folder (usually ``dist/`` or project root)
+
+### Setup
+#### 1. Configure Supabase
+Create a view in your Supabase database for optimal performance:
+```sql
+-- Create a view for article metadata
+CREATE VIEW article_metadata AS
+SELECT 
+  id,
+  title,
+  LEFT(content, 160) AS excerpt,  -- First 160 chars for descriptions
+  image_url
+FROM articles;
+
+-- Enable public read access
+ALTER VIEW article_metadata ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY "Allow public read access" 
+ON article_metadata
+FOR SELECT 
+TO anon 
+USING (true);
+```
+#### 2. Create Config File
+Create ``weweb.config.js`` in your project root:
+```javascript
+export default {
+  // Your Supabase configuration
+  supabase: {
+    url: process.env.SUPABASE_URL,
+    anonKey: process.env.SUPABASE_ANON_KEY
+  },
+  
+  // Optional: Specify your build folder (defaults to ./dist)
+  outputDir: "./dist",
+  
+  // Define your dynamic routes
+  pages: [
+    {
+      route: "/article/:id",
+      table: "articles",              // Your Supabase table name
+      metadata: {
+        title: "title",                // Database field for title 
+        content: "excerpt",            // Database field for description
+        image: "featured_image"        // Database field for image
+      }
+    }
+  ]
+};
+```
+#### 3. Run the Generator
+```bash
+# One-time generation
+npx weweb-dynamic-metadata
+
+# Add to your package.json scripts
+{
+  "scripts": {
+    "build:metadata": "weweb-dynamic-metadata",
+    "build": "weweb export && weweb-dynamic-metadata"
+  }
+}
+```
+
+## How It Works
+
+### 1. Reads Your Config
+The package reads ``weweb.config.js`` from your project root to understand your Supabase connection and dynamic routes.
+
+### 2. Discovers Content IDs
+Fetches all IDs from your Supabase table to know which articles need metadata.
+
+### 3. Fetches Metadata
+For each ID, retrieves the metadata fields you specified (title, content, image, etc.).
+
+### 4. Generates Central Metadata
+Creates a central JavaScript file with all metadata:
+```javascript
+window.METADATA = {
+  "1": { title: "Article 1", content: "...", image: "..." },
+  "2": { title: "Article 2", content: "...", image: "..." },
+  // ... one entry per article
+};
+```
+
+### 5. Injects Script into Template
+Adds the metadata injector script to your ``your-page-name/_param/index.html`` template.
+
+### 6. Creates Reference Files
+Generates tiny HTML files for each article that load the template and pass the article ID:
+```html
+<!-- article/1/index.html - only ~500 bytes! -->
+<script>
+  window.CURRENT_ARTICLE_ID = "1";
+  window.location.replace('../_param/index.html#1');
+</script>
+```
+
+## Architecture
+
+```mermaid
+flowchart TD
+    %% Styles
+    classDef setup fill:#2da44e,stroke:#1a7f37,color:#ffffff
+    classDef core fill:#0969da,stroke:#0550ae,color:#ffffff
+    classDef output fill:#8250df,stroke:#6639ba,color:#ffffff
+    classDef runtime fill:#f66a0a,stroke:#bf4e00,color:#ffffff
+    classDef note fill:#fff,stroke:#6e7781,color:#24292f,stroke-width:1px,stroke-dasharray:3 3
+
+    subgraph Setup ["🟢 User Setup (One Time)"]
+        A["User exports WeWeb project<br/>creates static files"] --> B
+        B["User creates weweb.config.js<br/>in project root"] --> C
+        C["Configure:<br/>• Supabase URL & anonKey<br/>• Dynamic routes (/article/:id)<br/>• Table & metadata fields<br/>• Optional: outputDir"] --> D
+        D["Save config file"]
+    end
+    class A,B,C,D setup
+
+    subgraph Build ["🔵 Build Time - Metadata Generation"]
+        direction TB
+        E["Run: npx weweb-dynamic-metadata"] --> F
+        F["Read weweb.config.js"] --> G
+        G["Validate configuration"] --> I["For each dynamic route:<br/>e.g., /article/:id"]
+        
+        I --> J["Discover content IDs<br/>GET /rest/v1/table?select=id"]
+        J --> K["IDs: [1, 2, 3, ...]"]
+        
+        K --> L["Fetch metadata for each ID<br/>GET /rest/v1/table?id=eq.{id}"]
+        L --> M["Build central metadata object<br/>{1: {...}, 2: {...}, ...}"]
+        
+        M --> N["Generate article/metadata.js<br/>window.METADATA = {...}"]
+        
+        N --> O["Locate WeWeb template<br/>article/_param/index.html"]
+        O --> P["Inject metadata script into template"]
+        
+        P --> Q["For each ID, create reference file:<br/>article/1/index.html<br/>article/2/index.html<br/>..."]
+        
+        Q --> R["Copy metadata.js to _param/<br/>for backward compatibility"]
+    end
+    class E,F,G,I,J,K,L,M,N,O,P,Q,R core
+
+    subgraph Output ["🟣 Generated Output"]
+        S["📁 article/<br/>├── metadata.js<br/>├── _param/<br/>│   ├── index.html (modified)<br/>│   └── metadata.js<br/>├── 1/<br/>│   ├── index.html (reference)<br/>│   └── metadata.js<br/>├── 2/<br/>│   ├── index.html (reference)<br/>│   └── metadata.js<br/>└── ..."]
+    end
+    class S output
+
+    subgraph Runtime ["🟠 Runtime - Browser"]
+        T["User visits /article/2"] --> U
+        U["Browser loads article/2/index.html<br/>(tiny reference file)"] --> V
+        V["JavaScript sets window.CURRENT_ARTICLE_ID=2<br/>and loads _param/index.html"] --> W
+        W["Main template loads with ID=2"] --> X
+        X["Metadata injector reads window.METADATA[2]<br/>and updates page metadata"] --> Y
+        Y["Page displays with correct title,<br/>description, Open Graph tags"]
+    end
+    class T,U,V,W,X,Y runtime
+
+    %% Connections
+    D ==> E
+    R ==> S
+    S ==> T
+
+    %% Legend
+    L1["🟢 User Setup: One-time configuration"]:::note
+    L2["🔵 Build Time: Generates metadata + reference files"]:::note
+    L3["🟣 Output: Generated files ready for deployment"]:::note
+    L4["🟠 Runtime: Browser loads and applies metadata"]:::note
+    L5["⚙️ weweb.config.js: Central configuration file"]:::note
+    
+    L1 ~~~ L2 ~~~ L3 ~~~ L4 ~~~ L5
+```
+## Project Folder Transformation
+
+### Before: WeWeb Export (No Metadata)
+```text
+dist/ (or your build folder)
+├── your-page-name/
+│   └── _param/
+│       └── index.html              # Same for ALL articles!
+├── assets/
+├── index.html
+└── ...            # Sitemap
+```
+
+**The Problem**: Every article at `/your-page-name/1`, `/your-page-name/2`, etc. serves the EXACT same HTML file with identical metadata.
+
+---
+### After: Package Runs
+```
+dist/
+├── your-page-name/
+│   ├── metadata.js                    # Central metadata for all articles
+│   ├── _param/
+│   │   ├── index.html                  # Original template (script injected)
+│   │   └── metadata.js                  # Copy for compatibility
+│   ├── 1/
+│   │   ├── index.html                   # Tiny reference file (~500 bytes)
+│   │   └── metadata.js                   # Points to central metadata
+│   ├── 2/
+│   │   ├── index.html                   # Tiny reference file
+│   │   └── metadata.js                   # Points to central metadata
+│   └── ...
+├── assets/
+└── index.html
+
+```
+**The Solution**: Each article now has its own unique metadata while sharing the same template!
+
+## Output Summary
+
+After running, you'll get a JSON summary:
+```json
+{
+  "timestamp": "2024-03-14T20:49:28.825Z",
+  "pages": [
+    {
+      "route": "/article/:id",
+      "total": 150,
+      "succeeded": 150,
+      "failed": 0,
+      "metadataEntries": 150,
+      "referencesCreated": 150
+    }
+  ],
+  "totalMetadataEntries": 150,
+  "outputDirectories": ["dist/article"],
+  "duration": "2.34"
+}
+```
+## Programmatic Usage
+
+```javascript
+import { processFiles } from 'weweb-dynamic-metadata';
+
+const result = await processFiles();
+console.log(`Generated ${result.totalMetadataEntries} metadata entries`);
+console.log(`Took ${result.duration} seconds`);
+```
+## Why Not Cloudflare Workers?
+
+| Approach | This Package | Cloudflare Worker |
+|----------|--------------|-------------------|
+| **Runtime** | None (pre-generated) | Each request |
+| **Latency** | 0ms | +100-300ms |
+| **Cost** | Free | Pay per request |
+| **SEO** | Perfect - instant HTML | Crawlers might timeout |
+| **Complexity** | Simple config | Worker deployment |
+| **Scaling** | Infinite (static files) | Worker limits |
+| **Cold starts** | None | Possible |
+
+## Troubleshooting
+
+| Issue | Likely Cause | Solution |
+|-------|--------------|----------|
+| `getOutputDir: Could not find build folder` | No WeWeb export found | Run `weweb export` first or set `outputDir` in config |
+| `Config error: Invalid or unexpected token` | BOM characters in config | Recreate file without BOM (use VSCode "Save with Encoding → UTF-8") |
+| No metadata generated | Supabase connection issue | Check your Supabase URL and anon key |
+| `Failed to fetch ID` | Table or field names wrong | Verify table and field names in config |
+| Reference files not created | Permission issues | Check write permissions in build folder |
+
+## License
+
+This project is licensed under the MIT License. See the LICENSE file for details.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "weweb-dynamic-metadata",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Generate dynamic metadata for WeWeb static exports",
+  "main": "src/index.js",
+  "bin": {
+    "weweb-metadata": "src/index.js"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node test/run.js"
+  },
+  "dependencies": {
+    "fs-extra": "^11.3.4",
+    "dotenv": "^17.3.1"
+  },
+  "keywords": [
+    "weweb",
+    "metadata",
+    "seo",
+    "static-site"
+  ],
+  "author": "Melina Reisinger",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mel000000/weweb-dynamic-metadata.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Mel000000/weweb-dynamic-metadata/issues"
+  },
+  "homepage": "https://github.com/Mel000000/weweb-dynamic-metadata#readme"
+}

package/src/core/file-processor.js

@@ -0,0 +1,264 @@
+import { fileURLToPath } from 'url';
+import { getConfigPath, getOutputDir, getRoutePaths } from '../utils/paths.js';
+import path from 'path';
+import fs from 'fs-extra';
+import { injectScriptInTemplate } from "../utils/template-injector.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// ========== CONFIG LOADING ==========
+async function readConfig() {
+    try {
+        const configPath = getConfigPath();
+        const configUrl = new URL(`file://${configPath.replace(/\\/g, '/')}`);
+        const configModule = await import(configUrl.href);
+        const config = configModule.default || configModule;
+        
+        const { supabase, pages, outputDir } = config;
+        
+        return {
+            supabase,
+            outputDir, // Pass this through
+            pages: pages.map(page => ({
+                route: page.route,
+                table: page.table,
+                metadataEndpoint: `${supabase.url}/rest/v1/${page.table}?id=eq.{id}&select=${Object.values(page.metadata).join(',')}`,
+                headers: {
+                    'apikey': supabase.anonKey,
+                    'Authorization': `Bearer ${supabase.anonKey}`
+                },
+                metadataFields: Object.values(page.metadata)
+            }))
+        };
+    } catch (error) {
+        throw new Error(`Config error: ${error.message}`);
+    }
+}
+
+// ========== ID DISCOVERY ==========
+async function discoverIds(page) {
+    try {
+        const url = page.metadataEndpoint.split("?id")[0];
+        const res = await fetch(url, { headers: page.headers });
+        const data = await res.json();
+        return data.map(item => item.id).filter(Boolean);
+    } catch (error) {
+        throw new Error(`ID discovery failed: ${error.message}`);
+    }
+}
+
+// ========== METADATA FETCHING ==========
+async function fetchMetadata(page, id) {
+    try {
+        const url = page.metadataEndpoint.replace('{id}', id || "1");
+        const res = await fetch(url, { headers: page.headers });
+        const data = await res.json();
+        return Array.isArray(data) ? data[0] : data;
+    } catch (error) {
+        throw new Error(`Failed to fetch ID ${id}: ${error.message}`);
+    }
+}
+
+// ========== HELPER FUNCTIONS ==========
+function generateMetadataJs(metadataObject) {
+    return `// Metadata generated on ${new Date().toISOString()}
+window.METADATA = ${JSON.stringify(metadataObject, null, 2)};`;
+}
+
+async function updateTemplateScriptSrc(templatePath, newSrc) {
+    try {
+        let content = await fs.readFile(templatePath, 'utf-8');
+        content = content.replace(
+            /<script src="\/article\/metadata\.js"><\/script>/,
+            `<script src="${newSrc}"></script>`
+        );
+        await fs.writeFile(templatePath, content, 'utf-8');
+    } catch (error) {
+        // Silently fail - this is non-critical
+    }
+}
+
+async function ensureTemplateExists(templatePath) {
+    if (await fs.pathExists(templatePath)) return;
+    
+    const minimalTemplate = `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <base href="/">
+    <title></title>
+</head>
+<body>
+    <div id="app"></div>
+    <script type="module" src="/assets/main.js"></script>
+</body>
+</html>`;
+    await fs.writeFile(templatePath, minimalTemplate, 'utf-8');
+}
+
+// ========== FIXED: Original working reference HTML ==========
+function generateReferenceHtml(id, title, relativeTemplatePath) {
+    return `<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>${title || 'Loading...'}</title>
+    <!-- Load the template dynamically -->
+    <script>
+        (function() {
+            // Store the ID in a global variable for the template to use
+            window.CURRENT_ARTICLE_ID = ${JSON.stringify(String(id))};
+            
+            // Fetch the template and replace the current document
+            fetch('${relativeTemplatePath}')
+                .then(response => response.text())
+                .then(html => {
+                    // Write the template HTML
+                    document.open();
+                    document.write(html);
+                    document.close();
+                })
+                .catch(error => {
+                    console.error('Failed to load template:', error);
+                    document.body.innerHTML = '<h1>Error loading article</h1><p>Please refresh the page</p>';
+                });
+        })();
+    </script>
+    
+    <!-- Fallback for noscript -->
+    <noscript>
+        <meta http-equiv="refresh" content="0; url=${relativeTemplatePath}?id=${id}">
+    </noscript>
+</head>
+<body>
+    <p>Loading article ${id}... <a href="${relativeTemplatePath}?id=${id}">Click here if not redirected</a></p>
+</body>
+</html>`;
+}
+
+// ========== MAIN PROCESSOR ==========
+export async function processFiles() {
+    const startTime = Date.now();
+    
+    try {
+        const config = await readConfig();
+        const summary = {
+            timestamp: new Date().toISOString(),
+            pages: [],
+            totalMetadataEntries: 0,
+            outputDirectories: [],
+            duration: 0
+        };
+        
+        for (let i = 0; i < config.pages.length; i++) {
+            const page = config.pages[i];
+            
+            // Discover IDs
+            const ids = await discoverIds(page);
+            
+            // Setup paths
+            const routeName = page.route.split('/')[1];
+            const baseDir = config.outputDir || getOutputDir();
+            
+            const paramDir = path.join(baseDir, routeName, '_param');
+            const articleRootDir = path.join(baseDir, routeName);
+            const templatePath = path.join(paramDir, 'index.html');
+            
+            await fs.ensureDir(paramDir);
+            await fs.ensureDir(articleRootDir);
+            
+            // Ensure template exists and inject script
+            await ensureTemplateExists(templatePath);
+            await injectScriptInTemplate(templatePath);
+            
+            // Fetch all metadata
+            const metadataMap = new Map();
+            let successCount = 0;
+            let failCount = 0;
+            
+            for (const id of ids) {
+                try {
+                    const metadata = await fetchMetadata(page, id);
+                    metadataMap.set(String(id), metadata);
+                    successCount++;
+                } catch (error) {
+                    failCount++;
+                }
+            }
+            
+            // Write metadata.js
+            const metadataObj = Object.fromEntries(metadataMap);
+            const metadataJsPath = path.join(articleRootDir, 'metadata.js');
+            await fs.writeFile(metadataJsPath, generateMetadataJs(metadataObj));
+            
+            // Copy to _param for compatibility
+            await fs.copyFile(metadataJsPath, path.join(paramDir, 'metadata.js'));
+            
+            // Update template script src
+            await updateTemplateScriptSrc(templatePath, '/article/metadata.js');
+            
+            // Create reference files using the ORIGINAL working logic
+            const relativeTemplatePath = '../_param/index.html';
+            let referencesCreated = 0;
+            
+            for (const [id, metadata] of metadataMap.entries()) {
+                try {
+                    const articleDir = path.join(baseDir, routeName, id);
+                    await fs.ensureDir(articleDir);
+                    
+                    await fs.writeFile(
+                        path.join(articleDir, 'index.html'),
+                        generateReferenceHtml(id, metadata.title, relativeTemplatePath)
+                    );
+                    
+                    // Create a small metadata.js reference
+                    const articleMetadataJsPath = path.join(articleDir, 'metadata.js');
+                    const metadataReference = `// Reference to central metadata file
+// This file points to the main metadata.js
+// The actual metadata is loaded from /article/metadata.js`;
+                    
+                    await fs.writeFile(articleMetadataJsPath, metadataReference, 'utf-8');
+                    
+                    referencesCreated++;
+                } catch (error) {
+                    // Silently continue
+                }
+            }
+            
+            summary.pages.push({
+                route: page.route,
+                total: ids.length,
+                succeeded: successCount,
+                failed: failCount,
+                metadataEntries: metadataMap.size,
+                referencesCreated
+            });
+            
+            summary.totalMetadataEntries += metadataMap.size;
+            summary.outputDirectories.push(articleRootDir);
+        }
+        
+        summary.duration = ((Date.now() - startTime) / 1000).toFixed(2);
+        
+        return summary;
+        
+    } catch (error) {
+        throw error;
+    }
+}
+
+// Run if called directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+    processFiles()
+        .then(summary => {
+            console.log(JSON.stringify(summary, null, 2));
+            process.exit(0);
+        })
+        .catch(error => {
+            console.error(JSON.stringify({ error: error.message }));
+            process.exit(1);
+        });
+}

package/src/index.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import { processFiles } from "./core/file-processor.js";
+import dotenv from 'dotenv';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Load environment variables from project root
+dotenv.config({ path: path.join(__dirname, '..', '.env') });
+
+// Simple console colors
+const colors = {
+    reset: '\x1b[0m',
+    green: '\x1b[32m',
+    red: '\x1b[31m',
+    yellow: '\x1b[33m',
+    cyan: '\x1b[36m',
+    magenta: '\x1b[35m',
+    blue: '\x1b[34m'
+};
+
+// Helper to safely use colors
+function colorize(text, color) {
+    return colors[color] ? `${colors[color]}${text}${colors.reset}` : text;
+}
+
+console.log(`${colorize('🚀 WeWeb Dynamic Metadata Generator', 'cyan')}\n`);
+
+export { processFiles };
+// Handle the promise properly
+if (import.meta.url === `file://${process.argv[1]}`) {
+    processFiles()
+        .then(result => {
+            console.log(`\n${colorize('╔' + '═'.repeat(48) + '╗', 'magenta')}`);
+            console.log(`${colorize('║', 'magenta')}${colorize('🎉 GENERATION COMPLETE'.padEnd(48), 'green')}${colorize('║', 'magenta')}`);
+            console.log(`${colorize('╟' + '─'.repeat(48) + '╢', 'magenta')}`);
+            console.log(`${colorize('║', 'magenta')}   ⏱️  Duration: ${result.duration}s`.padEnd(50) + `${colorize('║', 'magenta')}`);
+            console.log(`${colorize('║', 'magenta')}   📊 Total entries: ${result.totalMetadataEntries}`.padEnd(50) + `${colorize('║', 'magenta')}`);
+            console.log(`${colorize('║', 'magenta')}   📁 Output: ${path.basename(result.outputDirectories[0])}`.padEnd(50) + `${colorize('║', 'magenta')}`);
+            console.log(`${colorize('╚' + '═'.repeat(48) + '╝', 'magenta')}\n`);
+            
+            process.exit(0);
+        })
+        .catch(error => {
+            console.error(`\n${colorize('❌ Generation failed:', 'red')}`, error.message);
+            console.error(error.stack);
+            process.exit(1);
+        });
+}

package/src/templates/metadata-injector.js

@@ -0,0 +1,191 @@
+// src/templates/metadata-injector.js
+export const METADATA_INJECTOR_SCRIPT = `
+<!-- METADATA INJECTOR -->
+<script src="/article/metadata.js"></script>
+
+<script>
+(function() {
+    'use strict';
+    
+    // Prevent duplicate execution
+    if (window.__METADATA_INJECTOR_LOADED) {
+        console.log('🔄 Metadata injector already loaded, skipping...');
+        return;
+    }
+    window.__METADATA_INJECTOR_LOADED = true;
+    
+    console.log('🚀 Metadata injector starting...');
+    
+    // Configuration
+    const CONFIG = {
+        DEBUG: true,
+        META_TIMEOUT: 2000
+    };
+    
+    // State
+    let currentMetadata = null;
+    let appliedId = null;
+    
+    // Debug logging
+    function debugLog(...args) {
+        if (CONFIG.DEBUG) console.log('[Metadata]', ...args);
+    }
+    
+    // Get ID from URL
+    function getArticleId() {
+        const path = window.location.pathname;
+        const parts = path.split('/').filter(p => p.length);
+        
+        // Case 1: /article/2
+        if (parts[0] === 'article' && parts[1] && parts[1] !== '_param') {
+            return parts[1];
+        }
+        
+        // Case 2: /article/_param/?id=2
+        if (parts[0] === 'article' && parts[1] === '_param') {
+            return new URLSearchParams(window.location.search).get('id');
+        }
+        
+        // Case 3: Reference mode (ID stored in global)
+        return window.__REFERENCE_ARTICLE_ID;
+    }
+    
+    // Update meta tags
+    function setMeta(attr, name, value) {
+        if (!value) return;
+        let el = document.querySelector(\`meta[\${attr}="\${name}"]\`);
+        if (!el) {
+            el = document.createElement('meta');
+            el.setAttribute(attr, name);
+            document.head.appendChild(el);
+        }
+        el.setAttribute('content', String(value).replace(/[<>]/g, ''));
+    }
+    
+    // Apply metadata
+    function applyMetadata() {
+        const id = getArticleId();
+        if (!id || !window.METADATA) return false;
+        
+        const meta = window.METADATA[id];
+        if (!meta) {
+            console.warn('⚠️ No metadata for ID:', id);
+            return false;
+        }
+        
+        // Don't reapply if same ID
+        if (id === appliedId) return true;
+        
+        debugLog('Applying metadata for ID:', id);
+        
+        // Set title - FIXED: Don't remove the title tag, just update it
+        if (meta.title) {
+            // Find existing title tag or create new one
+            let titleTag = document.querySelector('title');
+            if (!titleTag) {
+                titleTag = document.createElement('title');
+                document.head.appendChild(titleTag);
+            }
+            titleTag.textContent = meta.title;
+            // Also set document.title for good measure
+            document.title = meta.title;
+        }
+        
+        // Set description
+        const desc = meta.content || meta.description;
+        if (desc) setMeta('name', 'description', desc);
+        
+        // Open Graph
+        if (meta.title) setMeta('property', 'og:title', meta.title);
+        if (desc) setMeta('property', 'og:description', desc);
+        setMeta('property', 'og:url', window.location.href.split('?')[0]);
+        
+        // Image
+        const img = meta.image_url || meta.image;
+        if (img) {
+            setMeta('property', 'og:image', img);
+            setMeta('name', 'twitter:image', img);
+            setMeta('name', 'twitter:card', 'summary_large_image');
+        } else {
+            setMeta('name', 'twitter:card', 'summary');
+        }
+        
+        // Twitter
+        if (meta.title) setMeta('name', 'twitter:title', meta.title);
+        if (desc) setMeta('name', 'twitter:description', desc);
+        
+        // Canonical
+        let canonical = document.querySelector('link[rel="canonical"]');
+        if (!canonical) {
+            canonical = document.createElement('link');
+            canonical.setAttribute('rel', 'canonical');
+            document.head.appendChild(canonical);
+        }
+        canonical.setAttribute('href', window.location.href.split('?')[0]);
+        
+        // Structured data - FIXED: Don't remove if we don't have data
+        if (meta.title || desc || img) {
+            // Remove existing JSON-LD
+            document.querySelectorAll('script[type="application/ld+json"]').forEach(el => el.remove());
+            
+            const ldJson = {
+                '@context': 'https://schema.org',
+                '@type': 'Article',
+                headline: meta.title || '',
+                description: desc || '',
+                image: img || '',
+                url: window.location.href.split('?')[0]
+            };
+            const script = document.createElement('script');
+            script.type = 'application/ld+json';
+            script.textContent = JSON.stringify(ldJson);
+            document.head.appendChild(script);
+        }
+        
+        currentMetadata = meta;
+        appliedId = id;
+        
+        console.log('✅ Metadata applied for', id);
+        return true;
+    }
+    
+    // Initialize
+    function init() {
+        if (applyMetadata()) return;
+        
+        // Wait for metadata if not loaded
+        if (!window.METADATA) {
+            const timeout = setTimeout(() => {
+                console.log('⏰ Metadata timeout');
+                clearInterval(checkInterval);
+            }, CONFIG.META_TIMEOUT);
+            
+            const checkInterval = setInterval(() => {
+                if (window.METADATA && applyMetadata()) {
+                    clearInterval(checkInterval);
+                    clearTimeout(timeout);
+                }
+            }, 50);
+        }
+    }
+    
+    // Start immediately
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', init);
+    } else {
+        init();
+    }
+    
+    // Handle SPA navigation
+    let lastUrl = location.href;
+    setInterval(() => {
+        if (location.href !== lastUrl) {
+            lastUrl = location.href;
+            appliedId = null;
+            init();
+        }
+    }, 500);
+    
+})();
+</script>
+`;

package/src/utils/config.js

@@ -0,0 +1,65 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { logger } from './logger.js';
+
+const CONFIG_SCHEMA = {
+    supabase: { required: true, type: 'object' },
+    pages: { required: true, type: 'array', min: 1 }
+};
+
+export async function loadConfig() {
+    const configPath = path.join(process.cwd(), 'weweb.config.js');
+    
+    if (!await fs.pathExists(configPath)) {
+        throw new Error(`Config not found: ${configPath}`);
+    }
+    
+    try {
+        const config = (await import(`file://${configPath}`)).default;
+        return formatConfig(config);
+    } catch (error) {
+        throw new Error(`Invalid config: ${error.message}`);
+    }
+}
+
+export function validateConfig(config) {
+    const errors = [];
+    
+    for (const [key, rules] of Object.entries(CONFIG_SCHEMA)) {
+        if (rules.required && !config[key]) {
+            errors.push(`Missing required field: ${key}`);
+        }
+    }
+    
+    if (!Array.isArray(config.pages) || config.pages.length === 0) {
+        errors.push('At least one page required');
+    }
+    
+    config.pages.forEach((page, i) => {
+        if (!page.route) errors.push(`Page ${i}: missing route`);
+        if (!page.table) errors.push(`Page ${i}: missing table`);
+        if (!page.metadata) errors.push(`Page ${i}: missing metadata fields`);
+    });
+    
+    if (errors.length > 0) {
+        throw new Error(`Config validation failed:\n${errors.join('\n')}`);
+    }
+    
+    return true;
+}
+
+function formatConfig(config) {
+    return {
+        supabase: config.supabase,
+        pages: config.pages.map(page => ({
+            route: page.route,
+            table: page.table,
+            metadataEndpoint: `${config.supabase.url}/rest/v1/${page.table}?id=eq.{id}&select=${Object.values(page.metadata).join(',')}`,
+            headers: {
+                'apikey': config.supabase.anonKey,
+                'Authorization': `Bearer ${config.supabase.anonKey}`
+            },
+            metadataFields: Object.values(page.metadata)
+        }))
+    };
+}

package/src/utils/paths.js

@@ -0,0 +1,48 @@
+// src/utils/paths.js
+import path from 'path';
+import fs from 'fs-extra';
+
+export function getConfigPath() {
+    return path.join(process.cwd(), 'weweb.config.js');
+}
+
+export function getOutputDir() {
+    const projectRoot = process.cwd();
+    
+    // First, check if 'dist' exists (production build)
+    const distPath = path.join(projectRoot, 'dist');
+    if (fs.existsSync(distPath)) {
+        return distPath;
+    }
+    
+    // Check common WeWeb export locations
+    const possiblePaths = [
+        path.join(projectRoot, 'out'),           // WeWeb default export
+        path.join(projectRoot, 'build'),          // Common build folder
+        path.join(projectRoot, 'www'),            // Another common one
+        path.join(projectRoot, 'public'),         // Static folder
+    ];
+    
+    for (const testPath of possiblePaths) {
+        if (fs.existsSync(testPath)) {
+            return testPath;
+        }
+    }
+    
+    // If no existing build found, ask user to specify
+    throw new Error(
+        'Could not find your WeWeb build folder.\n' +
+        'Please ensure you have run "weweb export" first,\n' +
+        'or specify the path in weweb.config.js'
+    );
+}
+
+export function getRoutePaths(baseDir, route) {
+    const routeName = route.split('/')[1];
+    return {
+        paramDir: path.join(baseDir, routeName, '_param'),
+        articleRoot: path.join(baseDir, routeName),
+        templatePath: path.join(baseDir, routeName, '_param', 'index.html'),
+        metadataPath: path.join(baseDir, routeName, 'metadata.js')
+    };
+}

package/src/utils/template-injector.js

@@ -0,0 +1,82 @@
+// src/utils/template-injector.js
+import fs from 'fs-extra';
+import path from 'path';
+import { METADATA_INJECTOR_SCRIPT } from '../templates/metadata-injector.js';
+
+export async function injectScriptInTemplate(templatePath) {
+    try {
+        // Check if file exists
+        if (!await fs.pathExists(templatePath)) {
+            console.log(`⚠️ Template not found: ${templatePath}`);
+            return false;
+        }
+        
+        // Read template
+        let template = await fs.readFile(templatePath, 'utf-8');
+        
+        // Check if script is already injected using multiple markers
+        const hasInjector = 
+            template.includes('__METADATA_INJECTOR_LOADED') || 
+            template.includes('METADATA INJECTOR') ||
+            (template.includes('/article/metadata.js') && template.includes('applyMetadata'));
+        
+        if (hasInjector) {
+            console.log(`⏭️ Metadata injector already present in: ${templatePath}`);
+            
+            // Optional: Remove duplicates if they exist
+            const cleanedTemplate = removeDuplicateInjectors(template);
+            if (cleanedTemplate !== template) {
+                await fs.writeFile(templatePath, cleanedTemplate, 'utf-8');
+                console.log(`🧹 Cleaned up duplicate injectors in: ${templatePath}`);
+            }
+            
+            return true;
+        }
+        
+        // Insert script before </head>
+        template = template.replace('</head>', METADATA_INJECTOR_SCRIPT + '\n</head>');
+        
+        // Write back
+        await fs.writeFile(templatePath, template, 'utf-8');
+        console.log(`✅ Injected metadata script into: ${templatePath}`);
+        
+        return true;
+        
+    } catch (error) {
+        console.error(`❌ Failed to inject script:`, error.message);
+        return false;
+    }
+}
+
+// Helper function to remove duplicate injectors
+function removeDuplicateInjectors(html) {
+    // Count occurrences of the injector marker
+    const markerCount = (html.match(/__METADATA_INJECTOR_LOADED/g) || []).length;
+    
+    if (markerCount <= 1) return html;
+    
+    console.log(`🧹 Found ${markerCount} duplicate injectors, cleaning up...`);
+    
+    // Split by the injector and keep only the first one
+    const parts = html.split('<!-- METADATA INJECTOR -->');
+    
+    if (parts.length > 2) {
+        // Keep first injector, remove others
+        return parts[0] + '<!-- METADATA INJECTOR -->' + parts[1].split('</script>')[0] + '</script>\n' + parts.slice(2).join('').replace(/<script[\s\S]*?<\/script>/g, '');
+    }
+    
+    return html;
+}
+
+// Optional: Function to check if injector exists without modifying
+export async function hasMetadataInjector(templatePath) {
+    try {
+        if (!await fs.pathExists(templatePath)) return false;
+        
+        const template = await fs.readFile(templatePath, 'utf-8');
+        return template.includes('__METADATA_INJECTOR_LOADED') || 
+               template.includes('METADATA INJECTOR');
+    } catch {
+        return false;
+    }
+}