🚀 Ping-Me

Keep your free tier backends alive, responsive, and observable!

Ping-Me is a full-stack open-source infrastructure utility that prevents automatic sleep cycles on free hosting platforms like Render, Railway, Cyclic, Glitch, and Vercel Functions.

🔥 The Problem

Free-tier backend hosts are amazing — until they're not:

• 🔌 Your server goes to sleep after minutes of inactivity
• 🐢 First requests are cold, taking seconds to start
• 😬 It times out if you don't keep it warm
• 🧪 When demoing or testing, your APIs break unpredictably

✅ The Solution

Ping-Me makes sure your backend never sleeps, and if it tries, you know about it:

• 🔁 Keep-alive Pinging: Automatically pings your endpoint on intervals
• ⚙️ Framework Adapters: Plug into Express, Fastify, Koa, Next.js, Hono
• 🧪 Dashboard UI: View uptime %, ping latency, error codes, logs
• 🔑 API Key Access: Each user gets a unique key to isolate metrics
• 🛡️ Abuse Protection: Rate limiting, IP filtering, data-size capping
• 🧩 CLI Tool: Bootstrap your server with pings instantly

📦 Installation

# Install the core library
npm install @ping-me/core

# Or use the framework-specific adapter
npm install @ping-me/express
# npm install @ping-me/next
# npm install @ping-me/fastify
# npm install @ping-me/koa
# npm install @ping-me/hono

Or use the CLI to set up:

npx ping-me init
npx ping-me add express

🧰 Usage

Express

const express = require('express');
const { withPingMe } = require('@ping-me/express');

const app = express();

// Add ping-me to your app
withPingMe(app, {
  route: '/ping-me',          // Custom route (default: /ping-me)
  interval: 300000,           // 5 minutes
  baseUrl: 'https://my-api.com', // Optional: specify exact URL
  apiKey: 'your-api-key'      // Optional: for dashboard metrics
});

app.listen(3000);

Next.js

// pages/api/ping-me.js
import { createPingMeHandler } from '@ping-me/next';

export default createPingMeHandler();

// In your _app.js or a component
import { usePingMe } from '@ping-me/next';

function MyApp({ Component, pageProps }) {
  // This will auto-ping your endpoint
  const status = usePingMe({
    interval: 300000, // 5 minutes
    apiKey: process.env.PING_ME_API_KEY // Optional
  });
  
  return <Component {...pageProps} />;
}

Core Usage

import { pingMe } from '@ping-me/core';

// Start pinging
const stopPinging = pingMe({
  url: 'https://my-api.com/ping',
  interval: 300000, // 5 minutes
  apiKey: 'your-api-key', // Optional
  log: console.log     // Optional custom logger
});

// Stop pinging later if needed
stopPinging();

📊 Dashboard

A beautiful Next.js dashboard is available to monitor your backend services:

• 📈 Uptime Charts: See your uptime over time
• ⏱️ Response Times: Track latency trends
• 💬 Status Logs: View ping history and errors
• 🔔 Alert Settings: Configure notification preferences

Try the Dashboard →

🧑‍💻 API

Track your metrics with the Ping-Me API:

# Ping Logging Endpoint
POST https://ping-me-api.vercel.app/api/log
Authorization: Bearer your-api-key
{
  "endpoint": "https://my-api.com",
  "status": 200,
  "responseTime": 123
}

# Get Metrics
GET https://ping-me-api.vercel.app/api/metrics
Authorization: Bearer your-api-key

🛠️ Project Structure

This is a monorepo built with Turborepo and PNPM:

ping-me/
├── apps/
│   ├── dashboard/     ← Next.js 14 + Tailwind CSS dashboard
│   ├── examples/      ← Example usage of ping-me
│   └── api/           ← Serverless API routes
├── packages/
│   ├── core/          ← Framework-agnostic ping logic
│   ├── cli/           ← CLI: npx ping-me init
│   ├── express/       ← Express adapter
│   ├── fastify/       ← Fastify adapter
│   ├── next/          ← Next.js adapter
│   ├── koa/           ← Koa adapter
│   ├── hono/          ← Hono adapter
│   └── metrics-server/ ← Metrics Server

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for details.

1. Fork the repository
2. Create your feature branch: git checkout -b feature/amazing-feature
3. Install dependencies: pnpm install
4. Make your changes
5. Run tests: pnpm test
6. Commit your changes: git commit -m 'Add some amazing feature'
7. Push to the branch: git push origin feature/amazing-feature
8. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

💖 Sponsorship

If you find Ping-Me useful, please consider sponsoring the project:

---

Made with ❤️ by @mreshank