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

$3

``bash
npm install @edgeone/nuxt-pages
`

$3

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

$3

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

$3

- 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

$3

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'
}
}
`

$3

- 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

$3

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

$3

`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

$3

- ✅ Nuxt 3+
- ✅ Server-Side Rendering (SSR)
- ✅ Static Site Generation (SSG)
- ✅ API Routes
- ✅ Middleware
- ✅ Plugins
- ✅ Monorepo structures

$3

- ❌ @nuxt/image module (under development)
- ⚠️ Nuxt versions below 3 (compatibility in progress)

🛠️ Troubleshooting

$3

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

$3

Enable detailed logging:

`bash
DEBUG=edgeone:* npm run build
`

📝 API Reference

$3

#### onPreBuild(options: BuildOptions)
Prepares the project for EdgeOne deployment.

#### onBuild(options: BuildOptions)
Executes the main build process.

#### onPostBuild(options: BuildOptions)
Cleanup and finalization.

$3

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

📄 License

ISC License - see LICENSE file for details.