🌐 IP Address Getter

A lightweight, type-safe TypeScript package to easily detect and fetch the user's public IP address in browser and Node.js environments with minimal overhead.

Documentation • Installation • Usage • API

✨ Features

• 🚀 Lightweight - Minimal dependencies, optimized for performance
• 📦 Type-Safe - Full TypeScript support with proper type definitions
• 🌍 Browser & Node.js - Works seamlessly in both browser and server environments
• 🔧 Flexible - Supports custom API endpoints and User-Agent headers
• 🛡️ Error Handling - Graceful error handling for network failures
• 📱 ESM Ready - Modern JavaScript module support
• 🎯 Simple API - Clean, intuitive interface to get user's IP in seconds

Installation

npm install @iaceene/ip-address-getter

Or with yarn:

yarn add @iaceene/ip-address-getter

Quick Start

import IP from '@iaceene/ip-address-getter';

// Create and fetch your IP address
const ip = await IP.New();
console.log(ip.GetIP()); // Output: XXX.XXX.XXX.XXX

Documentation

Usage

Basic Usage

import IP from '@iaceene/ip-address-getter';

// Create a new IP instance with default settings
const ip = await IP.New();

// Get the user's public IP address
const ipAddress = ip.GetIP();
console.log(ipAddress); // '203.0.113.42'

Custom Configuration

import IP from '@iaceene/ip-address-getter';

// Detect user's IP with custom API endpoint and User-Agent
const ip = await IP.New({
    URL: 'https://api.ipify.org?format=text',
    UserAgent: 'Mozilla/5.0'
});

console.log(ip.GetIP()); // Get the user's detected IP

API

IP.New(args?: options): Promise<IP>

Factory method to create and initialize an IP instance asynchronously.

Parameters:

• args (optional) - Configuration options

Returns: Promise<IP> - An initialized IP instance

Example:

const ip = await IP.New();

GetIP(): string

Retrieves the user's detected public IP address.

Returns: string - The user's public IP address

Example:

const addr = ip.GetIP();
console.log(addr); // User's IP: '203.0.113.42'

Options

The options object accepts the following properties:

| Property | Type | Default | Description | |----------|------|---------|-------------| | URL | string | 'http://ifconfig.me' | API endpoint to detect and fetch the user's IP address from | | UserAgent | string | 'curl/8.4.0' | Custom User-Agent header for the request |

Example:

const options = {
    URL: 'http://ifconfig.me',
    UserAgent: 'curl/8.4.0'
};

const ip = await IP.New(options);

Error Handling

The package includes built-in error handling that gracefully manages network failures when detecting user IP:

import IP from '@iaceene/ip-address-getter';

try {
    const ip = await IP.New();
    console.log(`User IP: ${ip.GetIP()}`);
} catch (error) {
    console.error('Failed to fetch user IP address:', error);
}

Popular IP Detection APIs

You can use any of these public IP APIs to detect user's IP with this package:

• ifconfig.me - Simple and fast (default)
• ipify.org - Returns IP in multiple formats
• ip.42.pl - Fast and reliable
• icanhazip.com - Returns just the IP address
• ident.me - Simple IP detection

Examples

Get User's IP using a specific service

import IP from '@iaceene/ip-address-getter';

// Detect user's IP using ipify.org
const ip = await IP.New({
    URL: 'https://api.ipify.org?format=text'
});

console.log(`User's IP: ${ip.GetIP()}`);

Custom User-Agent for IP Detection

import IP from '@iaceene/ip-address-getter';

const ip = await IP.New({
    UserAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36'
});

console.log(`User IP: ${ip.GetIP()}`);

Requirements

• Node.js 18.0.0 or higher
• TypeScript 5.0 or higher (for development)

Contributing

Contributions are welcome! Please read our CONTRIBUTORS.md guide for details on our code of conduct and the process for submitting pull requests.

License

ISC © 2026 - iaceene