This guide explains how to run Node.js packages in an edge runtime, such as Vercel Edge Functions, Cloudflare Workers, or Deno Deploy. You’ll learn what makes a package edge-compatible, how to adapt or replace incompatible ones, and how to deploy a working edge function. Before starting, you should have a basic understanding of JavaScript/TypeScript and a Node.js project set up locally.
What You’ll Need
- Node.js 18+ installed locally
- A code editor (VS Code recommended)
- An account with an edge runtime provider (Vercel, Cloudflare, or Deno)
- Your existing Node.js project or a new empty directory
Step-by-Step
- Identify the runtime you’re targeting. Each edge runtime has its own API and deployment process. For this guide, we’ll use Vercel Edge Functions as the primary example, but the principles apply to Cloudflare Workers and Deno Deploy as well.
- Create a new edge function file. In your project, create a file like
api/edge.js(for Vercel) orfunctions/edge.js(for Cloudflare). The exact location depends on your framework. - Export a default handler. Edge runtimes expect a default export that takes a
Requestobject and returns aResponse. For example:export default async function handler(request) { return new Response('Hello from edge!'); } - Install the package you want to use. Use npm or yarn to install it as you normally would:
npm install some-package. Edge runtimes can bundle most npm packages, but some rely on Node.js built-in modules that aren’t available. - Import the package in your edge function. At the top of your file, add the import statement. For example:
import { someFunction } from 'some-package'; - Use the package inside your handler. Call the package’s functions within the handler. Avoid using it at the top level for initialization that depends on request-specific data.
- Check for Node.js built-in module usage. If the package uses
fs,path,http, or other Node.js core modules, it won’t work directly. Look for alternatives or polyfills (see Common Mistakes). - Deploy your edge function. For Vercel, run
vercel deploy. For Cloudflare, usewrangler deploy. For Deno, usedeployctl deploy. Follow your provider’s CLI prompts. - Test your deployed function. Visit the provided URL to verify it returns the expected response. If you see an error, check the logs in your provider’s dashboard.
Common Mistakes
- Using Node.js built-in modules. Packages that rely on
fs,path,crypto(the Node.js version), orstreamwill fail. Edge runtimes provide a limited set of Web APIs instead. - Assuming all npm packages work. Many packages are pure JavaScript and work fine, but those with native bindings (e.g.,
bcrypt) or that depend on Node.js-specific APIs won’t. - Forgetting to use the Web standard Request/Response. Edge runtimes use the Fetch API, not Express-style
req/resobjects. - Top-level await for non-request data. Some runtimes limit top-level await. Keep initialization inside the handler.
- Not checking the package’s browser field. Some packages have a
browserfield in theirpackage.jsonthat points to a lighter version. Edge bundlers may use it automatically, but sometimes you need to configure aliases.
Tips
- Prefer packages that are explicitly marked as “edge-compatible” or “works with Workers”.
- Use a bundler like esbuild or Vite to see which modules are being pulled in and whether they reference Node.js globals.
- For cryptography, use the Web Crypto API (
crypto.subtle) instead of Node’scryptomodule. - Keep your edge function small and focused. Edge runtimes have size limits (e.g., 1 MB on Vercel).
- Test locally with the same runtime if possible. Vercel has
vercel dev, Cloudflare haswrangler dev, and Deno hasdeno runwith the appropriate flags.
Troubleshooting
If your edge function fails to deploy or returns an error, follow these steps:
- Read the error message. It often points to the exact module or line that’s incompatible. For example, “Module not found: ‘fs'” means the package uses Node’s file system.
- Check the package’s documentation. Many popular packages have edge-specific instructions or a separate build for edge runtimes.
- Search for the package name + “edge” or “workers”. There may be a community solution or a fork.
- Try a polyfill. For some Node.js APIs, you can install a polyfill like
node-fetch(though fetch is already global) orbuffer(for Buffer). However, polyfills can be tricky; prefer replacing the package. - Use a different package. If the package is fundamentally incompatible, look for an alternative that provides similar functionality without Node.js dependencies.
- Check your bundler configuration. If you’re using a custom build, ensure you’re not including Node.js polyfills that conflict with the edge runtime.
Frequently Asked Questions
Can I use Express or other Node.js frameworks in edge runtimes?
No, Express relies on Node.js HTTP server internals. Instead, use framework-agnostic handlers or edge-specific frameworks like Hono or Itty Router.
Do all npm packages work on edge runtimes?
No. Only packages that use standard JavaScript APIs and Web APIs work. Packages that use Node.js built-in modules or native bindings will not work without modification.
How do I handle environment variables in edge runtimes?
Use the runtime’s environment variable system. On Vercel, use process.env (works in edge functions). On Cloudflare, use env parameter in the handler. On Deno, use Deno.env.get().
Can I use TypeScript with edge runtimes?
Yes, all major edge runtimes support TypeScript out of the box. Just write your handler in a .ts file and import types as needed.
What is the size limit for edge functions?
Limits vary by provider. Vercel has a 1 MB compressed size limit for the entire function bundle. Cloudflare Workers have a 1 MB script size limit (gzipped). Deno Deploy allows up to 10 MB. Keep your bundle small.
How do I debug edge functions locally?
Use the provider’s local development server. Vercel: vercel dev. Cloudflare: wrangler dev. Deno: deno run --allow-net your-file.ts (with appropriate flags). These tools simulate the edge runtime closely.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.
More cards in this drawer
- Car Trends Making Cars Worse: 7 Downsides
- Nostalgic Classic Games Revamped on G2A?
- Nvidia RTX 4000 Super GPUs: Full Specs & Buying Guide
- Photoshop vs Lightroom AI Features Compared
- DNF vs DNF5: Which Package Manager?
- Stop iTunes Web Links From Opening iTunes