Keep Server Awake 🚀

A lightweight, zero-dependency ES Module designed to ping web services at set intervals.

This package is useful for preventing cold starts on servers, keeping background workers active, or setting up simple internal health checks without relying on heavy external cron daemons.

🚨 IMPORTANT DISCLAIMER 🚨

Please read before using this package on free-tier hosting platforms (e.g., Render, Heroku, Railway).

Many Platform-as-a-Service (PaaS) providers put free-tier instances to "sleep" after a period of inactivity to conserve compute resources. Using automated pinging tools to bypass these sleep restrictions is often a direct violation of their Terms of Service. If platform providers detect continuous, automated requests designed solely to keep free instances awake, they may suspend or terminate your account.

This tool is provided for educational purposes, legitimate uptime monitoring, and use on paid/private infrastructure where keep-alive pings are permitted. Use at your own risk.

Features

• 📦 Zero Dependencies: Uses native Node.js http/https modules.
• ⚡ Lightweight: Tiny footprint, runs entirely in memory.
• 🕒 Customizable: Set your own ping intervals.
• 🔧 Smart Boot: Pings immediately on initialization to prevent early sleep.

Installation

Install via npm:

npm install keep-server-awake

Note: This package is an ES Module. Ensure your project's package.json includes "type": "module".

Usage

Basic Usage

Import the package and pass the URL of the endpoint you want to ping, along with the interval in minutes.

import keepAwake from 'keep-server-awake';

// Ping your server every 14 minutes
keepAwake('[https://your-api.com/health](https://your-api.com/health)', 14);

Integration with Express.js

The best way to use this is to trigger it right after your server starts listening, hitting a dedicated health endpoint.

import express from 'express';
import keepAwake from 'keep-server-awake';

const app = express();
const PORT = process.env.PORT || 3000;

// 1. Create a lightweight endpoint for the ping to hit
app.get('/health', (req, res) => {
    res.status(200).send('Server is awake');
});

app.listen(PORT, () => {
    console.log(`Server running on port ${PORT}`);
    
    // 2. Determine the live URL (Useful for platforms like Render)
    const liveUrl = process.env.SERVER_EXTERNAL_URL || `http://localhost:${PORT}`;
    
    // 3. Start the keep-awake cycle (pinging every 14 minutes)
    keepAwake(`${liveUrl}/health`, 14); 
});

API Reference

keepAwake(url, intervalMinutes)

| Parameter | Type | Default | Description | | :--- | :--- | :--- | :--- | | url | string | Required | The full URL endpoint to ping (must include http:// or https://). | | intervalMinutes | number | 14 | How frequently the ping should occur, in minutes. |