Frequently Asked Questions

Find answers to common questions about EdgeMaster.

---

General Questions

What is EdgeMaster?

EdgeMaster is a lightweight, zero-dependency TypeScript microframework specifically designed for edge computing environments like Cloudflare Workers, AWS Lambda@Edge, and Azure Functions. It provides structured architecture with routing, middleware (interceptors), and production-ready features.

Why use EdgeMaster instead of Express.js?

Express.js is designed for Node.js servers, not edge environments. EdgeMaster is built specifically for edge computing with:

• Zero dependencies (~14 KB bundle size)
• No Node.js APIs (only Web APIs)
• Optimized for edge constraints (CPU time, memory)
• Fast cold starts (<1ms)
• Native TypeScript support

How does EdgeMaster compare to Hono?

Feature	EdgeMaster	Hono
Architecture	Task-based, structured	Simple, lightweight
Bundle Size	14 KB	~12 KB
Built-in Features	Auth, cache, rate limit	Basic routing
Best For	Production apps	Simple projects
Complexity	Scales to large apps	Best for simple apps

Recommendation: Use Hono for simple projects, EdgeMaster for production applications.

Is EdgeMaster production-ready?

Yes! EdgeMaster is production-ready with:

• 90%+ test coverage
• Built-in authentication (JWT, API keys)
• Rate limiting
• Caching support
• Error handling
• TypeScript strict mode
• Used in production environments

---

Installation & Setup

What are the minimum requirements?

• Node.js 16.0.0 or higher
• npm 7+ (or yarn/pnpm)
• TypeScript 5.0+ (recommended)
• Cloudflare Workers account (for Cloudflare deployment)

Can I use EdgeMaster with JavaScript?

Yes, but TypeScript is strongly recommended for the best experience. EdgeMaster is written in TypeScript and provides full type definitions.

// JavaScript works
const { EdgeController, RouteHandler, Task, json } = require('edge-master');

// But TypeScript is better
import { EdgeController, RouteHandler, Task, json } from 'edge-master';

How do I migrate from Express.js?

Key differences to consider:

// Express
app.use(middleware);
app.get('/users', (req, res) => {
  res.json({ users });
});

// EdgeMaster
app.addInterceptor(interceptor);
app.GET('/users', new RouteHandler(new Task({
  do: async () => json({ users })
})));

See our Migration Guide for detailed steps.

---

Platform-Specific

Which platforms does EdgeMaster support?

EdgeMaster works on any edge platform that supports Web APIs:

• ✅ Cloudflare Workers (recommended) - Full support
• ✅ AWS Lambda@Edge - Supported
• ✅ Azure Functions - Supported
• ✅ Vercel Edge Functions - Supported
• ✅ Node.js - Works (but not optimized for)
• ✅ Bun - Supported
• ✅ Deno - Supported

Why is Cloudflare Workers recommended?

Cloudflare Workers offers the best experience:

• Zero cold starts
• Global edge network (300+ data centers)
• Built-in services (KV, D1, R2, AI)
• Generous free tier
• EdgeMaster was designed specifically for Workers

Can I use EdgeMaster with AWS Lambda@Edge?

Yes! Here's a simple adapter:

import { EdgeController } from 'edge-master';

const app = new EdgeController();
// ... configure routes

export const handler = async (event: any) => {
  const request = new Request(event.Records[0].cf.request.uri, {
    method: event.Records[0].cf.request.method,
    headers: new Headers(event.Records[0].cf.request.headers)
  });

  return app.handleRequest({ req: request });
};

---

Features & Functionality

How do I add authentication?

Use the built-in JWT interceptor:

import { jwtInterceptor } from 'edge-master';

app.addInterceptor(jwtInterceptor({
  secret: env.JWT_SECRET,
  exclude: ['/api/login', '/api/public'],
}));

See Authentication Tutorial for details.

How do I implement rate limiting?

Use the rate limit interceptor:

import { rateLimitInterceptor } from 'edge-master';

app.addInterceptor(rateLimitInterceptor({
  limit: 100,           // 100 requests
  window: 60,           // per 60 seconds
  keyGenerator: (req) => req.headers.get('cf-connecting-ip')
}));

How do I add caching?

Use the cache interceptor:

import { cacheInterceptor } from 'edge-master';

const { check, store } = cacheInterceptor({
  ttl: 3600,            // 1 hour
  shouldCache: (req) => req.method === 'GET'
});

app.addInterceptor(check);   // Check cache
app.addInterceptor(store);   // Store in cache

Can I use EdgeMaster with databases?

Yes! EdgeMaster works with:

• Cloudflare D1 (SQL)
• Cloudflare KV (Key-Value)
• Cloudflare R2 (Object Storage)
• PostgreSQL (via HTTP)
• PlanetScale (MySQL)
• Upstash (Redis)
• Supabase

Example with D1:

app.GET('/users', new RouteHandler(new Task({
  do: async ({ env }) => {
    const { results } = await env.DB.prepare(
      'SELECT * FROM users'
    ).all();

    return json({ users: results });
  }
})));

How do I handle file uploads?

app.POST('/upload', new RouteHandler(new Task({
  do: async ({ req, env }) => {
    const formData = await req.formData();
    const file = formData.get('file');

    // Upload to R2
    await env.MY_BUCKET.put(`uploads/${Date.now()}.jpg`, file);

    return json({ success: true });
  }
})));

Can I use WebSockets?

WebSockets require Durable Objects, which EdgeMaster doesn't directly support yet. Use Cloudflare Durable Objects directly for WebSocket needs.

---

Development & Debugging

How do I debug my EdgeMaster application?

Local Development:

npx wrangler dev --local

Add Logging:

import { loggingInterceptor } from 'edge-master';

const { request, response } = loggingInterceptor({
  level: 'debug',
  logTiming: true
});

app.addInterceptor(request);
app.addInterceptor(response);

View Logs:

npx wrangler tail

How do I test my EdgeMaster application?

import { EdgeController, RouteHandler, Task, json } from 'edge-master';

describe('My API', () => {
  it('should return users', async () => {
    const app = new EdgeController();

    app.GET('/users', new RouteHandler(new Task({
      do: async () => json({ users: [] })
    })));

    const req = new Request('http://localhost/users');
    const res = await app.handleRequest({ req });
    const data = await res.json();

    expect(data).toEqual({ users: [] });
  });
});

Why is my route not matching?

Check these common issues:

1. Route priority - More specific routes need higher priority
2. HTTP method - Ensure you're using the right method (GET, POST, etc.)
3. Path format - Check for trailing slashes
4. Interceptor short-circuit - An interceptor might be returning early

// Debug route matching
app.addRoute(
  (req) => {
    console.log('Testing route:', req.url, req.method);
    return true; // This will match all routes
  },
  handler,
  -1 // Low priority to run last
);

---

Performance & Optimization

How can I improve performance?

1. Use caching aggressively
2. Minimize interceptors (each adds overhead)
3. Optimize database queries
4. Use CDN for static assets
5. Enable compression
6. Keep bundle size small

See Performance Optimization for details.

What's the bundle size impact?

• Core EdgeMaster: ~14 KB minified
• With all interceptors: ~20 KB minified
• Zero runtime dependencies: No external code

Compare to Express.js (200+ KB) or other frameworks.

How many routes can EdgeMaster handle?

EdgeMaster has been tested with 1000+ routes without performance issues. Route matching is O(n) with early exit for most cases.

What about cold starts?

EdgeMaster cold starts are <1ms on Cloudflare Workers because:

• Zero dependencies
• No heavy initialization
• Optimized for edge constraints

---

Errors & Troubleshooting

"Cannot find module 'edge-master'"

Solution:

npm install edge-master

Ensure edge-master is in your package.json dependencies.

"Type 'Request' is not assignable..."

Solution: Install Cloudflare Workers types:

npm install -D @cloudflare/workers-types

Add to tsconfig.json:

{
  "compilerOptions": {
    "types": ["@cloudflare/workers-types"]
  }
}

"Exceeded CPU time limit"

Solution: Optimize your code:

• Reduce synchronous computation
• Use async/await properly
• Cache expensive operations
• Minimize database queries

"KV binding not found"

Solution: Ensure KV namespace is configured in wrangler.toml:

[[kv_namespaces]]
binding = "MY_KV"
id = "your-namespace-id"

And deployed:

npx wrangler deploy

"Rate limit not working"

Solution: Rate limiting requires state storage. For multiple workers, use KV-backed storage:

import { rateLimitInterceptor, KVRateLimitStore } from 'edge-master';

app.addInterceptor(rateLimitInterceptor({
  limit: 100,
  window: 60,
  store: new KVRateLimitStore(env.MY_KV)
}));

---

Deployment

How do I deploy to production?

Cloudflare Workers:

npx wrangler deploy

With custom domain: Add to wrangler.toml:

routes = [
  { pattern = "api.example.com/*", zone_name = "example.com" }
]

How do I set environment variables?

Development: Create .dev.vars:

API_KEY=dev-key
JWT_SECRET=dev-secret

Production:

npx wrangler secret put API_KEY
npx wrangler secret put JWT_SECRET

Can I use a CI/CD pipeline?

Yes! Example GitHub Actions:

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm ci
      - run: npm test
      - run: npx wrangler deploy
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}

---

Licensing & Support

What is the license?

EdgeMaster is licensed under the MIT License - free for commercial and personal use.

Where can I get help?

• Documentation: https://em.asanflow.com
• GitHub Issues: Report bugs
• GitHub Discussions: Ask questions
• Email: sharif3271@gmail.com

How can I contribute?

See our Contribution Guide for details on:

• Reporting bugs
• Requesting features
• Contributing code
• Improving documentation

---

Roadmap & Future

What's on the roadmap?

Planned features:

• OpenAPI/Swagger spec generation
• GraphQL adapter
• WebSocket support via Durable Objects
• More platform adapters
• Enhanced D1 helpers
• CLI tool for scaffolding

Can I sponsor the project?

Yes! Sponsorship helps support development. Contact sharif3271@gmail.com for sponsorship options.

---

Still have questions?

• 📚 Read the docs
• 💬 Ask on GitHub Discussions
• 🐛 Report an issue
• 📧 Email us

---

Can't find your answer? Ask a question →