@maravilla-labs/functions

Maravilla Edge Functions bundler and development tools. This package provides esbuild-based bundling for edge functions, transforming multiple JavaScript function files into a single optimized bundle for WASM execution.

Installation

npm install --save-dev @maravilla-labs/functions

Usage

CLI Commands

# Build functions for production
npx maravilla-functions build

# Build with options
npx maravilla-functions build --output dist --minify --sourcemap

# Start development mode with file watching
npx maravilla-functions dev

# Development mode with custom output
npx maravilla-functions dev --output build

Package.json Scripts

Add to your functions/package.json:

{
  "scripts": {
    "build": "maravilla-functions build",
    "dev": "maravilla-functions dev",
    "build:prod": "maravilla-functions build --minify"
  },
  "devDependencies": {
  "@maravilla-labs/functions": "latest"
  }
}

Function Structure

Functions should be organized in a flat or nested structure:

functions/
├── package.json
├── hello.js
├── user-profile.js
└── auth/
    └── login.js

Each function file should export HTTP method handlers:

// hello.js
export const GET = (request, response) => {
  response.json({ message: 'Hello World!' });
};

export const POST = (request, response) => {
  const body = JSON.parse(request.body || '{}');
  response.json({ received: body });
};

Route Mapping

Functions are automatically mapped to API routes:

• hello.js → /api/hello
• user-profile.js → /api/user-profile
• auth/login.js → /api/auth/login

HTTP Methods

Supported export patterns:

// Named method exports
export const GET = (request, response) => { /* ... */ };
export const POST = (request, response) => { /* ... */ };
export const PUT = (request, response) => { /* ... */ };
export const DELETE = (request, response) => { /* ... */ };

// Default export handles all methods
export default (request, response) => {
  // Handle based on request.method
};

Request Object

{
  method: 'GET',           // HTTP method
  url: 'http://...',       // Full URL
  path: '/api/hello',      // Path part
  query: { id: '123' },    // Query parameters as object
  headers: { ... },        // Headers as object
  body: '...'              // Raw body string
}

Response Object

response.status(200)                    // Set status code
response.setHeader('key', 'value')      // Set header
response.json({ data: 'value' })        // JSON response
response.text('plain text')             // Text response
response.html('<h1>HTML</h1>')          // HTML response

Build Output

The bundler generates:

• dist/functions.js - Single bundled JavaScript file
• Source maps (if enabled)
• Minified output (if enabled)

The bundle includes:

• All function modules with proper ES6 imports
• Runtime helpers (Request/Response classes)
• Route registry for path matching
• Global handleRequest function for WASM integration

Integration with Maravilla CLI

The Maravilla CLI automatically detects and uses the bundled output:

1. Looks for functions/dist/functions.js
2. Compiles to QuickJS bytecode
3. Embeds in WASM runtime
4. Serves via HTTP with automatic routing

Development Workflow

1. Setup functions directory:

   mkdir functions
   cd functions
   npm init -y

npm install --save-dev @maravilla-labs/functions

2. **Add build scripts:**
```json
{
  "scripts": {
    "build": "maravilla-functions build",
    "dev": "maravilla-functions dev"
  }
}

3. Create function files:

   // hello.js
   export const GET = (request, response) => {
     response.json({ message: 'Hello from Maravilla!' });
   };

4. Build and serve:

   npm run build
   maravilla serve --dev --framework-port 5173

Features

• ✅ esbuild-powered - Fast, reliable bundling
• ✅ ES6 modules - Native import/export support
• ✅ File watching - Automatic rebuilds in dev mode
• ✅ Source maps - Debug support
• ✅ Minification - Production optimization
• ✅ Route mapping - Automatic API route generation
• ✅ Method detection - HTTP method analysis
• ✅ WASM integration - Seamless CLI integration

License

Proprietary. © 2025 SOLUTAS GmbH, Switzerland. All rights reserved. Use is governed by the root LICENSE file or a separate written agreement with SOLUTAS GmbH.