Command-line interface for executing Edge Functions, starting development servers, and interactive REPL sessions. Provides comprehensive tooling for development, testing, and deployment of Edge Functions.
The edge-runtime command provides multiple execution modes for different development workflows.
# Execute a script file
edge-runtime <script-file>
# Run as HTTP server
edge-runtime --listen <script-file>
# Evaluate inline code
edge-runtime --eval <code>
# Start interactive REPL
edge-runtime
# Display help
edge-runtime --helpUsage Examples:
# Execute an edge function script
edge-runtime my-function.js
# Start development server on default port (3000)
edge-runtime --listen my-function.js
# Start server on specific port and host
edge-runtime --listen --port 8080 --host 0.0.0.0 my-function.js
# Test inline code
edge-runtime --eval "console.log('Hello from Edge Runtime')"
# Start interactive session
edge-runtimeComplete set of command-line options for configuring runtime behavior.
--eval, -e <code>
Evaluate an input script inline instead of reading from file
--help
Display help message with all available options
--listen, -l
Run the script as an HTTP server instead of one-time execution
--port, -p <number>
Specify the port for HTTP server (default: 3000)
Server will automatically try next port if specified port is in use
--host, -h <string>
Specify the host/interface for HTTP server (default: 127.0.0.1)
--repl
Start an interactive REPL session
Note: REPL starts automatically when no script is providedFlag Examples:
# Evaluate code directly
edge-runtime -e "addEventListener('fetch', e => e.respondWith(new Response('OK')))"
# Server with custom port
edge-runtime -l -p 8080 function.js
# Server on all interfaces
edge-runtime --listen --host 0.0.0.0 --port 3000 function.js
# Get help
edge-runtime --helpDefault mode for executing Edge Function scripts with one-time evaluation.
Usage Examples:
edge-runtime function.js// function.js
addEventListener('fetch', event => {
const response = new Response('Hello World', {
headers: { 'content-type': 'text/plain' }
});
event.respondWith(response);
});
console.log('Edge function loaded successfully');The script is executed once and the process exits. This mode is useful for:
HTTP server mode for development and testing with live request handling.
edge-runtime --listen [--port <port>] [--host <host>] <script-file>Usage Examples:
# Start server on default port (3000)
edge-runtime --listen api.js
# Custom port and host
edge-runtime --listen --port 8080 --host 0.0.0.0 api.js
# Server automatically finds available port if specified port is busy
edge-runtime --listen --port 3000 api.js # Will use 3001 if 3000 is busy// api.js
addEventListener('fetch', event => {
const url = new URL(event.request.url);
if (url.pathname === '/api/hello') {
event.respondWith(Response.json({ message: 'Hello World' }));
} else if (url.pathname === '/api/time') {
event.respondWith(Response.json({
timestamp: Date.now(),
iso: new Date().toISOString()
}));
} else {
event.respondWith(new Response('Not Found', { status: 404 }));
}
});Server mode features:
Execute Edge Function code directly from command line without creating files.
edge-runtime --eval <javascript-code>
edge-runtime -e <javascript-code>Usage Examples:
# Simple response
edge-runtime -e "console.log('Runtime version:', EdgeRuntime)"
# Fetch event handler
edge-runtime -e "
addEventListener('fetch', event => {
event.respondWith(new Response('Inline function working!'));
});
console.log('Inline function registered');
"
# JSON API response
edge-runtime -e "
addEventListener('fetch', event => {
const data = { status: 'ok', timestamp: Date.now() };
event.respondWith(Response.json(data));
});
"Inline evaluation is useful for:
Interactive Read-Eval-Print Loop for exploring Edge Runtime capabilities and testing code snippets.
edge-runtime
# or explicitly:
edge-runtime --replREPL Usage Examples:
// REPL starts with Edge Runtime context
ƒ => console.log('Hello from REPL')
Hello from REPL
// All Edge Runtime globals are available
ƒ => fetch
[Function: fetch]
ƒ => new Response('test').text()
Promise { <pending> }
// Define and test functions
ƒ => const myHandler = (event) => {
event.respondWith(new Response('REPL handler'));
}
ƒ => addEventListener('fetch', myHandler)
// Test Web APIs
ƒ => new URL('https://example.com/path').pathname
'/path'
ƒ => crypto.randomUUID()
'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
// Exit REPL
ƒ => .exitREPL features:
~/.edge_runtime_repl_history.exit, .help, etc.)Environment variables that affect CLI behavior.
EDGE_RUNTIME_LOGGING=<boolean>
Enable or disable CLI logging output
Default: true
Example: EDGE_RUNTIME_LOGGING=false edge-runtime --listen api.jsUsage Examples:
# Disable logging
EDGE_RUNTIME_LOGGING=false edge-runtime --listen function.js
# Enable logging (default)
EDGE_RUNTIME_LOGGING=true edge-runtime --listen function.jsThe CLI provides comprehensive error reporting and debugging information.
Error Types:
# Syntax errors in edge function code
edge-runtime invalid-syntax.js
# Output: SyntaxError with line numbers and context
# Runtime errors during execution
edge-runtime runtime-error.js
# Output: Runtime error with stack trace
# Server startup errors
edge-runtime --listen --port 80 function.js
# Output: Permission error for privileged port
# File not found errors
edge-runtime nonexistent.js
# Output: Clear file not found messageDebug Output Examples:
# Server mode includes request logging
edge-runtime --listen function.js
# Output:
# ƒ 127.0.0.1 GET / → 200 OK in 2ms
# ƒ 127.0.0.1 POST /api/data → 201 Created in 15msThe CLI handles process lifecycle and signal management properly.
Signal Handling:
SIGTERM/SIGINT: Graceful shutdown with pending request completionSIGUSR1: Debugging support (Node.js inspector)Usage Examples:
# Start server in background
edge-runtime --listen function.js &
SERVER_PID=$!
# Graceful shutdown
kill -TERM $SERVER_PID
# Force shutdown if needed
kill -KILL $SERVER_PID