@edgeone/nuxt-pages 1.0.0

package/README.md

@@ -0,0 +1,275 @@
+# EdgeOne Nuxt Deploy
+
+A professional deployment package that seamlessly deploys your Nuxt 3 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.8.0 or higher
+- **Node.js**: 18.x or higher
+- **EdgeOne**: Tencent Cloud EdgeOne account
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+npm install @tencent/nuxt-pages
+```
+
+### Basic Usage
+
+1. **Add to your build process:**
+
+```javascript
+// In your build script or CI/CD pipeline
+import { onPreBuild, onBuild, onPostBuild } from '@tencent/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.8.0+
+- ✅ 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.8.0 (compatibility in progress)
+
+## 🛠️ Troubleshooting
+
+### Common Issues
+
+1. **Build Fails**: Ensure Nuxt version is 3.8.0 or higher
+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
+  }
+}
+```
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+## 📄 License
+
+ISC License - see [LICENSE](LICENSE) file for details.
+
+## 🔗 Links
+
+- [GitHub Repository](https://github.com/q153877011/edgeone-nuxt-deploy)
+- [Issues](https://github.com/q153877011/edgeone-nuxt-deploy/issues)
+- [Tencent Cloud EdgeOne](https://cloud.tencent.com/product/eo)
+- [Nuxt 3 Documentation](https://nuxt.com)
+
+## 📞 Support
+
+- 📧 Create an issue on GitHub
+- 💬 Community discussions
+- 📖 Check the documentation
+
+---
+
+Made with ❤️ by [Venzil](https://github.com/q153877011) for the Nuxt community.

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-NJ4SUJNF.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-MMMRMLH2.js";
+import "../../esm-chunks/chunk-V2LFVP3C.js";
+import "../../esm-chunks/chunk-GX4Z7KQX.js";
+import "../../esm-chunks/chunk-6BT4RYQJ.js";
+export {
+  addNitroBuildOutputConfig,
+  resetNitroConfig
+};

package/dist/build/functions/server.js

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

package/dist/build/plugin-context.js

@@ -0,0 +1,18 @@
+
+      var require = await (async () => {
+        var { createRequire } = await import("node:module");
+        return createRequire(import.meta.url);
+      })();
+    
+import {
+  EDGE_HANDLER_NAME,
+  PluginContext,
+  SERVER_HANDLER_NAME
+} from "../esm-chunks/chunk-RPSYO4VM.js";
+import "../esm-chunks/chunk-GX4Z7KQX.js";
+import "../esm-chunks/chunk-6BT4RYQJ.js";
+export {
+  EDGE_HANDLER_NAME,
+  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 {
+  convertNuxtRoutePattern,
+  createNuxtApiRoutesMeta,
+  createNuxtPagesRouteMeta
+} from "../esm-chunks/chunk-6YERJDAJ.js";
+import "../esm-chunks/chunk-GX4Z7KQX.js";
+import "../esm-chunks/chunk-6BT4RYQJ.js";
+export {
+  convertNuxtRoutePattern,
+  createNuxtApiRoutesMeta,
+  createNuxtPagesRouteMeta
+};

package/dist/build/templates/nuxt-handler-backup.js

@@ -0,0 +1,305 @@
+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 HTTP response
+ */
+async function handleResponse(response, req, res, context) {
+  if (!response) {
+    res.statusCode = 500;
+    res.setHeader('Content-Type', 'text/plain');
+    res.end('Server Error');
+    return;
+  }
+
+  // Ensure response.headers is a Headers object
+  if (!(response.headers instanceof Headers)) {
+    response.headers = new Headers(response.headers || {});
+  }
+  
+  // Correctly iterate over Headers object (using entries() method)
+  for (const [key, value] of response.headers.entries()) {
+    res.setHeader(key, value);
+  }
+
+  // Check if Content-Type already exists (case-insensitive)
+  const hasContentType = response.headers.has('content-type');
+  
+  // Only set default value if Content-Type is missing
+  if (!hasContentType) {
+    res.setHeader('Content-Type', 'text/html; charset=utf-8');
+  }
+  // try {
+  //   res.setHeader('functions-request-id', context.headers['x-scf-request-id']);
+  // } catch (error) {
+  //   console.error('Handle response error:', error);
+  // }
+
+  res.setHeader('from-server', 'true');
+
+  // Handle set-cookie header (special handling, as there may be multiple values)
+  if (response.headers.has('set-cookie')) {
+    const cookieArr = response.headers.getSetCookie();
+    res.setHeader('set-cookie', Array.isArray(cookieArr) ? cookieArr : [cookieArr]);
+    // headers['set-cookie'] = Array.isArray(cookieArr) ? cookieArr : [cookieArr];
+  }
+
+  res.statusCode = response.status || response.statusCode || 200;
+  if(Buffer.isBuffer(response.body)) {
+    res.end(response.body);
+  } else if(response.body && typeof response.body === 'object' && typeof response.body.getReader === 'function') {
+    const reader = response.body.getReader();
+    const chunks = [];
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(Buffer.from(value));
+    }
+    res.end(Buffer.concat(chunks));
+  } else {
+    res.end(response.body || response._data || '');
+  }
+}
+
+/**
+ * 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 { {{USE_NITRO_APP_SYMBOL}}: useNitroApp } = await import('./chunks/nitro/nitro.mjs');
+    nitroApp = useNitroApp();
+  }
+  return nitroApp;
+}
+
+/**
+ * Handle HTTP response
+ */
+function handleResponse(response, event) {
+  if (!response) {
+    return {
+      statusCode: 500,
+      headers: { 'Content-Type': 'text/plain' },
+      body: 'Internal Server Error'
+    };
+  }
+
+  const headers = {};
+  
+  // Ensure response.headers is a Headers object
+  if (!(response.headers instanceof Headers)) {
+    response.headers = new Headers(response.headers || {});
+  }
+  
+  // Correctly iterate over Headers object (using entries() method)
+  for (const [key, value] of response.headers.entries()) {
+    headers[key] = value;
+  }
+
+  // Check if Content-Type already exists (case-insensitive)
+  const hasContentType = response.headers.has('content-type');
+  
+  // Only set default value if Content-Type is missing
+  if (!hasContentType) {
+    headers['Content-Type'] = 'text/html; charset=utf-8';
+  }
+
+  headers['from-server'] = 'true';
+  headers['functions-request-id'] = event.headers['x-scf-request-id'];
+
+  // Handle set-cookie header (special handling, as there may be multiple values)
+  if (response.headers.has('set-cookie')) {
+    const cookieArr = response.headers.getSetCookie();
+    headers['set-cookie'] = Array.isArray(cookieArr) ? cookieArr : [cookieArr];
+  }
+
+  return {
+    statusCode: response.status || response.statusCode || 200,
+    headers,
+    body: response.body || response._data || ''
+  };
+}
+
+/**
+ * EdgeOne function handler
+ */
+export async function handler(event) {
+  try {
+    const url = event.path || '/';
+    const method = event.httpMethod || event.method || 'GET';
+    const headers = event.headers || {};
+    const body = event.body || '';
+
+    // First try to handle static assets
+    if (method === 'GET') {
+      const staticResponse = handleStaticFile(url);
+      if (staticResponse) {
+        return staticResponse;
+      }
+    }
+
+    // Handle dynamic requests
+    const app = await getNitroApp();
+    
+    try {
+      const response = await app.localCall({
+        url,
+        method,
+        headers,
+        body
+      });
+
+      return handleResponse(response, event);
+    } 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) {
+    console.error('EdgeOne handler error:', error);
+    return {
+      statusCode: 500,
+      headers: { 'Content-Type': 'text/plain' },
+      body: `Internal Server Error: ${error.message}`
+    };
+  }
+}
+
+import('http').then(async (http) => {
+  const { createServer } = http;
+  // Dynamically import stream module to handle ReadableStream
+  await import('stream').then(({ Readable, pipeline }) => {
+    const server = createServer(async (req, res) => {
+      try {
+        const event = {
+          path: req.url,
+          httpMethod: req.method,
+          headers: req.headers,
+          body: ''
+        };
+
+        if (req.method !== 'GET' && req.method !== 'HEAD') {
+          const chunks = [];
+          for await (const chunk of req) {
+            chunks.push(chunk);
+          }
+          event.body = Buffer.concat(chunks).toString();
+        }
+
+        const result = await handler(event);
+
+        res.statusCode = result.statusCode;
+        // Object.entries(result.headers).forEach(([key, value]) => {
+        //   if(key === 'set-cookie') {
+            res.setHeader('set-cookie', Array.isArray(value) ? value[0].split(',') : value);
+        //   } else {
+        //     res.setHeader(key, value);
+        //   }
+        // });
+        // debug message
+        // res.setHeader('functions-request-id', req.headers['x-scf-request-id']);
+
+
+        // Handle response body: support Buffer, string, and ReadableStream
+        if (Buffer.isBuffer(result.body)) {
+          res.end(result.body);
+        } else if (result.body && typeof result.body === 'object' && typeof result.body.getReader === 'function') {
+          // Detect ReadableStream (Web Streams API)
+          try {
+            const nodeStream = Readable.fromWeb(result.body);
+            nodeStream.pipe(res);
+          } catch (streamError) {
+            console.error('Stream conversion error:', streamError);
+            // If conversion fails, try to read the entire stream
+            const reader = result.body.getReader();
+            const chunks = [];
+            try {
+              while (true) {
+                const { done, value } = await reader.read();
+                if (done) break;
+                chunks.push(Buffer.from(value));
+              }
+              res.end(Buffer.concat(chunks));
+            } catch (readError) {
+              console.error('Stream read error:', readError);
+              res.end();
+            }
+          }
+        } else {
+          // Handle string or other types
+          res.end(result.body || '');
+        }
+      } catch (error) {
+        console.error('Local server error:', error);
+        res.statusCode = 500;
+        res.setHeader('Content-Type', 'text/plain');
+        res.end(`Server Error: ${error.message}`);
+      }
+    });
+
+    const port = process.env.DEV_PORT || 9000;
+    server.listen(port, () => {
+      console.log(`EdgeOne development server running at http://localhost:${port}`);
+      console.log(`Static assets served from: ${ASSET_DIR}`);
+    });
+  });
+});
+