@edgeone/nuxt-pages/README.md

A professional deployment package that seamlessly deploys your Nuxt 3/4 applications to Tencent Cloud EdgeOne platform with optimized performance and intelligent caching.

# 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.