elysia-ip

Get the client ip address in Elysia. It works with Bun, Cloudflare, Fastly and other runtimes.

Please consider starring the repository to show your ❤️ and support.

Installation

Requires Bun v1.0.4 or above. Requires Elysia v1.0.9 or above. For older elysia versions please install v0.0.7 of this package

bun a elysia-ip

Documentation

Introduction

This plugin adds a ip property to the context object. It contains the client ip address.

Usage

import { Elysia } from "elysia";
import { ip } from "elysia-ip";

new Elysia()
  .use(ip())
  .get("/", ({ ip }) => ip)
  .listen(3000);

How does it work?

For Bun runtime, We use server.requestIP introduced in Bun v1.0.4 to get the client ip address and early return it.

It relies on headers for runtimes other than Bun. Cloudflare and other providers send back specific headers, containing the IP address. For example CF-Connecting-IP for Cloudflare and Fastly-Client-IP for Fastly.

We also add support for X-Forwarded-For header (de-facto standard header) and other various headers.

Priority list:

User specified
X-Forwarded-For (de-facto standard header)
X-Real-IP (Apache)
X-Client-IP (Nginx)
CF-Connecting-IP (Cloudflare)
Fastly-Client-IP (Fastly)
X-Cluster-Client-IP (GCP)
X-Forwarded (RFC 7239)
Forwarded-For (RFC 7239)
Forwarded (RFC 7239)
appengine-user-ip (GCP)
true-client-ip (Akamai and Cloudflare)
cf-pseudo-ipv4 (Cloudflare)

You can even specify your own headers if you want to as following

import { Elysia } from "elysia";
import { ip } from "elysia-ip";

new Elysia()
  .use(ip({ checkHeaders: ["X-Forwarded-For", "X-Real-IP"] }))
  .get("/", ({ ip }) => ip)
  .listen(3000);

import { Elysia } from "elysia";
import { ip } from "elysia-ip";

new Elysia()
  .use(ip({ checkHeaders: "X-Forwarded-For" }))
  .get("/", ({ ip }) => ip)
  .listen(3000);

You can also switch to Headers only mode by setting headersOnly to true. This will only check headers and not the server.requestIP property.

import { Elysia } from "elysia";
import { ip } from "elysia-ip";

new Elysia()
  .use(ip({ headersOnly: true }))
  .get("/", ({ ip }) => ip)
  .listen(3000);

Debugging

Please use run the command setting environment variable NODE_DEBUG to either * or elysia-ip

License

MIT

gaurishhs/elysia-ip