@edgeone/nuxt-pages 1.0.0-beta.1

package/README.md

@@ -0,0 +1,255 @@
+# EdgeOne Nuxt Deploy
+
+A professional deployment package that seamlessly deploys your Nuxt 3/4 applications to Tencent Cloud EdgeOne platform with optimized performance and intelligent caching.
+
+## ✨ Features
+
+- 🚀 **One-Click Deployment** - Automated build and deployment process for EdgeOne
+- 🏗️ **Nitro Integration** - Full compatibility with Nuxt 3's Nitro engine
+- 📦 **Monorepo Support** - Optimized templates for complex project structures
+- 🎯 **Smart Caching** - Multi-layer caching with memory, regional blobs, and tag invalidation
+- ⚡ **Performance Optimized** - Static asset handling, lazy loading, and OpenTelemetry tracing
+- 🔧 **Auto Configuration** - Intelligent Nuxt config detection and modification
+- 🌐 **SSR Ready** - Full server-side rendering support on EdgeOne
+
+## 📋 Requirements
+
+- **Nuxt**: 3+
+- **Node.js**: 18.x or higher
+- **EdgeOne**: Tencent Cloud EdgeOne account
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+npm install @edgeone/nuxt-pages
+```
+
+### Basic Usage
+
+1. **Add to your build process:**
+
+```javascript
+// In your build script or CI/CD pipeline
+import { onPreBuild, onBuild, onPostBuild } from '@edgeone/nuxt-pages'
+
+const buildOptions = {
+  cwd: process.cwd(),
+  env: process.env,
+  meta: {},
+  functions: {},
+  constants: {
+    PUBLISH_DIR: 'dist'
+  }
+}
+
+// Execute build phases
+await onPreBuild(buildOptions)
+await onBuild(buildOptions)
+await onPostBuild(buildOptions)
+```
+
+2. **Your Nuxt project will be automatically configured:**
+
+The package will create or modify your `nuxt.config.ts`:
+
+```typescript
+export default defineNuxtConfig({
+  srcDir: 'app',
+  nitro: {
+    preset: 'node-server',
+    output: {
+      dir: '.edgeone',
+      publicDir: '.edgeone/assets',
+      serverDir: '.edgeone/server-handler',
+    },
+  },
+  devtools: { enabled: true },
+})
+```
+
+## 🏗️ Architecture
+
+### Build Process
+
+The deployment follows a three-phase approach:
+
+1. **PreBuild Phase** (`onPreBuild`)
+   - Validates Nuxt version compatibility
+   - Configures Nitro build output
+   - Sets up EdgeOne-specific configurations
+
+2. **Build Phase** (`onBuild`)
+   - Creates server handlers
+   - Generates route metadata for pages and API routes
+   - Patches Nitro handlers for EdgeOne compatibility
+
+3. **PostBuild Phase** (`onPostBuild`)
+   - Restores original configurations
+   - Cleanup and optimization
+
+### Caching Strategy
+
+- **Memory Cache**: LRU cache for frequently accessed data
+- **Regional Blobs**: Distributed storage for static assets
+- **Tag Invalidation**: Smart cache invalidation based on content tags
+- **Stale-While-Revalidate**: Background revalidation for optimal performance
+
+## 📁 Project Structure
+
+After deployment, your project will have:
+
+```
+your-project/
+├── .edgeone/
+│   ├── assets/           # Static assets
+│   ├── server-handler/   # Server-side code
+│   │   ├── chunks/       # Nitro chunks
+│   │   ├── handler.js    # EdgeOne handler
+│   │   └── index.mjs     # Server entry point
+│   └── dist/             # Runtime modules
+├── app/                  # Your Nuxt app (if using srcDir)
+├── nuxt.config.ts        # Auto-generated/modified config
+└── package.json
+```
+
+## ⚙️ Configuration
+
+### Advanced Options
+
+You can customize the deployment behavior:
+
+```typescript
+// Custom build options
+const buildOptions = {
+  cwd: process.cwd(),
+  env: {
+    ...process.env,
+    USE_REGIONAL_BLOBS: 'true',
+    NITRO_PORT: '9000'
+  },
+  meta: {
+    // Custom metadata
+  },
+  functions: {
+    // Function-specific settings
+  },
+  constants: {
+    PUBLISH_DIR: 'dist'
+  }
+}
+```
+
+### Environment Variables
+
+- `USE_REGIONAL_BLOBS`: Enable regional blob storage (default: true)
+- `NITRO_PORT`: Development server port (default: 9000)
+- `NITRO_PUBLIC_DIR`: Static assets directory
+
+## 🎯 Monorepo Support
+
+For monorepo projects, the package automatically detects the structure and uses optimized templates:
+
+```javascript
+// Automatic detection of monorepo structure
+// Uses nuxt-handler-monorepo.tmpl.js for complex setups
+// Handles working directory changes and path resolution
+```
+
+## 🔧 Development
+
+### Local Testing
+
+The package includes a development server for local testing:
+
+```bash
+# Start development server
+npm run start
+```
+
+Your Nuxt app will be available at `http://localhost:9000`
+
+### Build Scripts
+
+```json
+{
+  "scripts": {
+    "build": "node ./tools/build.js",
+    "build:watch": "node ./tools/build.js --watch",
+    "start": "node dist/index.js",
+    "test": "ts-node src/test.ts"
+  }
+}
+```
+
+## 📊 Performance Features
+
+- **Static Asset Optimization**: 1-year cache headers for static files
+- **Lazy Loading**: Nitro app initialization on first request
+- **OpenTelemetry Tracing**: Built-in performance monitoring
+- **Error Handling**: Graceful fallbacks and error recovery
+- **Memory Management**: Efficient memory usage with LRU caching
+
+## 🚨 Compatibility
+
+### Supported Features
+- ✅ Nuxt 3+
+- ✅ Server-Side Rendering (SSR)
+- ✅ Static Site Generation (SSG)
+- ✅ API Routes
+- ✅ Middleware
+- ✅ Plugins
+- ✅ Monorepo structures
+
+### Known Limitations
+- ❌ `@nuxt/image` module (under development)
+- ⚠️ Nuxt versions below 3 (compatibility in progress)
+
+## 🛠️ Troubleshooting
+
+### Common Issues
+
+1. **Build Fails**: Ensure Nuxt version is 3+
+2. **Module Conflicts**: Check for unsupported modules like `@nuxt/image`
+3. **Path Issues**: Verify your project structure matches expected layout
+
+### Debug Mode
+
+Enable detailed logging:
+
+```bash
+DEBUG=edgeone:* npm run build
+```
+
+## 📝 API Reference
+
+### Core Functions
+
+#### `onPreBuild(options: BuildOptions)`
+Prepares the project for EdgeOne deployment.
+
+#### `onBuild(options: BuildOptions)`
+Executes the main build process.
+
+#### `onPostBuild(options: BuildOptions)`
+Cleanup and finalization.
+
+### Types
+
+```typescript
+interface BuildOptions {
+  cwd: string
+  env: any
+  meta: any
+  functions: any
+  constants: {
+    PUBLISH_DIR: string
+  }
+}
+```
+
+## 📄 License
+
+ISC License - see [LICENSE](LICENSE) file for details.
+

package/dist/build/content/server.js

@@ -0,0 +1,18 @@
+
+      var require = await (async () => {
+        var { createRequire } = await import("node:module");
+        return createRequire(import.meta.url);
+      })();
+    
+import {
+  RUN_CONFIG_FILE,
+  copyNuxtServerCode,
+  verifyNuxtHandlerDirStructure
+} from "../../esm-chunks/chunk-TP3RAVPL.js";
+import "../../esm-chunks/chunk-V2LFVP3C.js";
+import "../../esm-chunks/chunk-6BT4RYQJ.js";
+export {
+  RUN_CONFIG_FILE,
+  copyNuxtServerCode,
+  verifyNuxtHandlerDirStructure
+};

package/dist/build/content/static.js

@@ -0,0 +1,17 @@
+
+      var require = await (async () => {
+        var { createRequire } = await import("node:module");
+        return createRequire(import.meta.url);
+      })();
+    
+import {
+  addNitroBuildOutputConfig,
+  resetNitroConfig
+} from "../../esm-chunks/chunk-7RNB5RB6.js";
+import "../../esm-chunks/chunk-5JK44IEA.js";
+import "../../esm-chunks/chunk-V2LFVP3C.js";
+import "../../esm-chunks/chunk-6BT4RYQJ.js";
+export {
+  addNitroBuildOutputConfig,
+  resetNitroConfig
+};

package/dist/build/functions/server.js

@@ -0,0 +1,17 @@
+
+      var require = await (async () => {
+        var { createRequire } = await import("node:module");
+        return createRequire(import.meta.url);
+      })();
+    
+import {
+  createServerHandler,
+  patchNitroHandler
+} from "../../esm-chunks/chunk-L23O2KDO.js";
+import "../../esm-chunks/chunk-TP3RAVPL.js";
+import "../../esm-chunks/chunk-V2LFVP3C.js";
+import "../../esm-chunks/chunk-6BT4RYQJ.js";
+export {
+  createServerHandler,
+  patchNitroHandler
+};

package/dist/build/plugin-context.js

@@ -0,0 +1,16 @@
+
+      var require = await (async () => {
+        var { createRequire } = await import("node:module");
+        return createRequire(import.meta.url);
+      })();
+    
+import {
+  PluginContext,
+  SERVER_HANDLER_NAME
+} from "../esm-chunks/chunk-Y3YAV6NZ.js";
+import "../esm-chunks/chunk-5JK44IEA.js";
+import "../esm-chunks/chunk-6BT4RYQJ.js";
+export {
+  PluginContext,
+  SERVER_HANDLER_NAME
+};

package/dist/build/routes.js

@@ -0,0 +1,18 @@
+
+      var require = await (async () => {
+        var { createRequire } = await import("node:module");
+        return createRequire(import.meta.url);
+      })();
+    
+import {
+  createNuxtApiRoutesMeta,
+  createNuxtPagesRouteMeta,
+  createNuxtRoutesMeta
+} from "../esm-chunks/chunk-UFRAZNP3.js";
+import "../esm-chunks/chunk-5JK44IEA.js";
+import "../esm-chunks/chunk-6BT4RYQJ.js";
+export {
+  createNuxtApiRoutesMeta,
+  createNuxtPagesRouteMeta,
+  createNuxtRoutesMeta
+};

package/dist/build/templates/nuxt-handler-monorepo.tmpl.js

@@ -0,0 +1,260 @@
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { readFileSync, existsSync, statSync } from 'fs';
+import { extname } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Static assets directory
+const ASSET_DIR = resolve(__dirname, '../assets');
+
+// MIME type mapping
+const MIME_TYPES = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'application/javascript',
+  '.css': 'text/css',
+  '.json': 'application/json',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.txt': 'text/plain',
+  '.xml': 'application/xml'
+};
+
+/**
+ * Get the MIME type of a file
+ */
+function getMimeType(filePath) {
+  const ext = extname(filePath).toLowerCase();
+  return MIME_TYPES[ext] || 'application/octet-stream';
+}
+
+/**
+ * Handle static file requests
+ */
+function handleStaticFile(url) {
+  try {
+    // Remove query parameters
+    let cleanUrl = url.split('?')[0];
+    
+    // Handle IPX image processing paths from @nuxt/image
+    // Convert /_ipx/s_800x600/hero.png to /hero.png
+    // Also handles nested paths: /_ipx/s_800x600/images/hero.png -> /images/hero.png
+    if (cleanUrl.startsWith('/_ipx/')) {
+      let newUrl = '';
+
+      // Remove /_ipx/ prefix
+      const ipxPath = cleanUrl.slice(6); // Remove '/_ipx/'
+      
+      // IPX format: /_ipx/[params]/[original_path]
+      // Parameters are typically the first segment(s) and contain underscores/commas
+      // The original file path starts after the params
+      const pathSegments = ipxPath.split('/').filter(s => s); // Remove empty segments
+      
+      if (pathSegments.length === 0) {
+        // Empty path after /_ipx/, skip
+        return null;
+      }
+      
+      // Check each segment for file extension
+      for (let i = 0; i < pathSegments.length; i++) {
+        const segment = pathSegments[i];
+        if(segment.startsWith('s_') || segment.startsWith('w_') || segment.startsWith('h_') || segment.startsWith('q_') || segment.startsWith('f_') || segment.startsWith('c_') || segment.startsWith('bg_') || segment.startsWith('blur_') || segment.startsWith('_')) {
+          continue;
+        }
+        // Check if segment ends with a known image extension
+        newUrl += '/' + segment;
+      }
+
+      if(newUrl.startsWith('/http')) newUrl = newUrl.slice(1);
+      
+      if(newUrl.includes('http:/') && !newUrl.includes('http://')) {
+        newUrl = newUrl.replace('http:/', 'http://');
+      } else if(newUrl.includes('https:/') && !newUrl.includes('https://')) {
+        newUrl = newUrl.replace('https:/', 'https://');
+      }
+
+      return {
+        statusCode: 302,
+        headers: {
+          'from-server': 'true',
+          location: newUrl
+        }
+      }
+    }
+    
+    // 本地调试寻找文件路径
+    const possiblePaths = [];
+    
+    // Direct file path
+    const directPath = resolve(ASSET_DIR, cleanUrl.startsWith('/') ? cleanUrl.slice(1) : cleanUrl);
+    possiblePaths.push(directPath);
+    
+    // Try each possible path
+    for (const filePath of possiblePaths) {
+      // Security check: ensure file is within asset directory
+      if (!filePath.startsWith(ASSET_DIR)) {
+        continue;
+      }
+      
+      if (existsSync(filePath) && statSync(filePath).isFile()) {
+        const content = readFileSync(filePath);
+        const mimeType = getMimeType(filePath);
+        
+        return {
+          statusCode: 200,
+          headers: {
+            'Content-Type': mimeType,
+            'Content-Length': content.length.toString(),
+            'Cache-Control': 'public, max-age=31536000' // 1 year cache
+          },
+          body: content
+        };
+      }
+    }
+  } catch (error) {
+    console.error('Static file error:', error);
+  }
+  
+  return null;
+}
+
+/**
+ * Lazy load Nitro application
+ */
+let nitroApp = null;
+async function getNitroApp() {
+  if (!nitroApp) {
+    // Set environment variables to prevent automatic server startup
+    process.env.NITRO_PORT = '';
+    process.env.PORT = '';
+    
+    // Set correct static assets path
+    process.env.NITRO_PUBLIC_DIR = ASSET_DIR;
+    
+    const nitroModule = await (async () => {
+      try {
+        return await import('./chunks/nitro/nitro.mjs')
+      } catch {
+        return await import('./chunks/_/nitro.mjs')
+      }
+    })()
+
+    const { {{USE_NITRO_APP_SYMBOL}}: useNitroApp } = nitroModule
+    nitroApp = useNitroApp();
+  }
+  return nitroApp;
+}
+
+async function getBody(req) {
+  if (req.method !== 'GET' && req.method !== 'HEAD') {
+    const chunks = [];
+    for await (const chunk of req) {
+      chunks.push(chunk);
+    }
+    const body = Buffer.concat(chunks).toString();
+    return body;
+  }
+  return '';
+}
+
+/**
+ * EdgeOne function handler
+ */
+export default async function handler(req, res, context) {
+  try {
+    const url = req.url || '/';
+    const method = req.method || 'GET';
+    const headers = req.headers || new Headers();
+    const body = await getBody(req);
+
+    // First try to handle static assets
+    if (method === 'GET') {
+      const staticResponse = handleStaticFile(url);
+      if (staticResponse) {
+        return new Response(staticResponse.body, {
+          status: staticResponse.statusCode,
+          headers: staticResponse.headers
+        });
+      }
+    }
+
+    // Handle dynamic requests
+    const app = await getNitroApp();
+    
+    try {
+      const response = await app.localCall({
+        url,
+        method,
+        headers,
+        body
+      });
+
+      // 正确处理 headers，特别是多个 set-cookie 的情况
+      const responseHeaders = new Headers();
+        
+      // 如果 response.headers 是 Headers 对象，直接复制
+      if (response.headers instanceof Headers) {
+        response.headers.forEach((value, key) => {
+          responseHeaders.append(key, value);
+        });
+      } else {
+        // 如果是普通对象，需要特殊处理 set-cookie 数组
+        for (const [key, value] of Object.entries(response.headers)) {
+          const lowerKey = key.toLowerCase();
+          
+          // set-cookie 是特殊 header，可以有多个值
+          if (lowerKey === 'set-cookie' && Array.isArray(value)) {
+            // 为每个 cookie 单独添加
+            value.forEach(cookie => {
+              responseHeaders.append('Set-Cookie', cookie);
+            });
+          } else {
+            // 其他 header 直接设置
+            responseHeaders.set(key, Array.isArray(value) ? value.join(', ') : value);
+          }
+        }
+      }
+    
+      // console.log('responseHeaders.getSetCookie() --->', responseHeaders.getSetCookie());
+      return new Response(response.body, {
+        status: response.status || response.statusCode,
+        headers: responseHeaders
+      });
+    } catch (nitroError) {
+      // Handle Nitro static file read errors (prerender files not found)
+      // Check error and its cause property (H3Error may wrap actual error in cause)
+      const actualError = nitroError?.cause || nitroError;
+      const errorPath = actualError?.path || nitroError?.path;
+      const errorCode = actualError?.code || nitroError?.code;
+      
+      // If error is due to prerender static file not found, try dynamic rendering
+      if (errorCode === 'ENOENT' && 
+          errorPath && 
+          (errorPath.includes('/assets/') || errorPath.includes('assets/')) &&
+          (errorPath.includes('/index.html') || errorPath.includes('index.html'))) {
+        console.warn(`Prerender file not found: ${errorPath}, falling back to dynamic rendering for ${url}`);
+        
+        // If static file handling has been tried but file not found, should perform dynamic rendering
+        // Nitro should be able to handle dynamic routes, but if it still tries to read static files,
+        // it may be due to configuration issues. We throw an error directly to let user know to build or check configuration
+        throw new Error(`Prerender route ${url} not found. Make sure to run build first or configure routeRules correctly. Original error: ${actualError?.message || nitroError?.message}`);
+      }
+      
+      // Other errors are thrown directly
+      throw nitroError;
+    }
+  } catch (error) {
+    return new Response(`Server Error: ${error.message}`, {
+      status: 500,
+      headers: {
+        'Content-Type': 'text/plain'
+      }
+    });
+  }
+}
+