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

npm install @edgeone/nuxt-pages

Basic Usage

1. Add to your build process:

// 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:

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:

// 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:

// 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:

# Start development server
npm run start

Your Nuxt app will be available at http://localhost:9000

Build Scripts

{
  "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:

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

interface BuildOptions {
  cwd: string
  env: any
  meta: any
  functions: any
  constants: {
    PUBLISH_DIR: string
  }
}

📄 License

ISC License - see LICENSE file for details.