DEV Community

Cover image for Introducing node-ip-ts: A Modern Type-Safe IP Utility Library for Node.js
Deni Irawan Nugraha
Deni Irawan Nugraha

Posted on

Introducing node-ip-ts: A Modern Type-Safe IP Utility Library for Node.js

#javascript #typescript #webdev #node

Working with IP addresses in Node.js is a common task for backend developers.
Whether you're building authentication systems, rate limiters, firewall rules, analytics pipelines, or networking tools — sooner or later you'll need utilities for handling IP addresses.

For years, the popular ip package has been the go-to solution. It has millions of weekly downloads and provides a simple API for working with IPv4 and IPv6.

However, the ecosystem has evolved.

Today, most modern Node.js projects use:

  • TypeScript
  • ES Modules
  • strict type checking
  • modern bundlers

Unfortunately, the original ip package does not fully support these modern workflows.

That is exactly why node-ip-ts was created.

What is node-ip-ts?

node-ip-ts is a modern rewrite of the popular ip library with a focus on:

  • Full TypeScript support
  • ES Module compatibility
  • Strict typing
  • Zero dependencies
  • API compatibility with the original library

It allows developers to keep the familiar API while gaining the benefits of modern TypeScript development.

npm install node-ip-ts
Enter fullscreen mode Exit fullscreen mode

Why create another IP library?

The original ip package works well, but it has some limitations in modern TypeScript environments.

Feature ip node-ip-ts
TypeScript types ❌ ✅
ES Modules ❌ ✅
CommonJS ✅ ✅
Strict typing ❌ ✅
External dependencies 0 0
API compatibility — ✅

The goal of node-ip-ts is simple:

Provide a drop-in replacement for ip that works seamlessly with modern TypeScript projects.

This means you can migrate by changing just one line.

- const ip = require('ip')
+ const ip = require('node-ip-ts')
Enter fullscreen mode Exit fullscreen mode

Or in TypeScript:

import * as ip from "node-ip-ts"
Enter fullscreen mode Exit fullscreen mode

Example Usage

Here are some common operations you can perform with node-ip-ts.

Address Classification 

import * as ip from "node-ip-ts"

ip.isPrivate("192.168.1.1") // true
ip.isPublic("8.8.8.8") // true
ip.isLoopback("127.0.0.1") // true
Enter fullscreen mode Exit fullscreen mode

The library supports both IPv4 and IPv6.

ip.isPrivate("fd12:3456:789a:1::1") // true
Enter fullscreen mode Exit fullscreen mode

Working with CIDR and Subnets

Network calculations are one of the most common needs.

const subnet = ip.cidrSubnet("192.168.1.134/26")

subnet.networkAddress
// "192.168.1.128"

subnet.firstAddress
// "192.168.1.129"

subnet.lastAddress
// "192.168.1.190"

subnet.contains("192.168.1.150")
// true
Enter fullscreen mode Exit fullscreen mode

This is useful for things like:

  • firewall rules
  • IP allowlists / blocklists
  • internal network tools
  • infrastructure automation

Bitwise Operations on IP Addresses

The library also supports bitwise operations often required for networking logic.

ip.not("255.255.255.0")
// "0.0.0.255"

ip.or("0.0.0.255", "192.168.1.10")
// "192.168.1.255"
Enter fullscreen mode Exit fullscreen mode

These operations are helpful when computing:

  • wildcard masks
  • broadcast addresses
  • subnet boundaries

Converting IP Addresses

Sometimes IPs must be converted to integers for storage or comparison.

ip.toLong("127.0.0.1")
// 2130706433

ip.fromLong(2130706433)
// "127.0.0.1"
Enter fullscreen mode Exit fullscreen mode

The library also supports normalization of various IPv4 formats.

ip.normalizeToLong("0x7f.0.0.1")
// 2130706433
Enter fullscreen mode Exit fullscreen mode

Works in Node.js and the Browser

Most functions are environment agnostic, meaning they work in:

  • Node.js
  • Vite
  • webpack
  • esbuild
  • browser bundlers

The only exception is address() because it uses the Node.js os module.

Zero Dependencies

node-ip-ts intentionally has zero runtime dependencies.

This provides several benefits:

  • smaller install size
  • faster installs
  • lower supply-chain risk
  • easier auditing

Security tools like Snyk and Socket.dev can easily verify the package.

Designed for Modern TypeScript

The library is written entirely in TypeScript strict mode, providing:

  • accurate types
  • safer refactoring
  • better IDE autocomplete
  • fewer runtime errors

Example types:

type IPFamily = "ipv4" | "ipv6"

interface SubnetInfo {
  networkAddress: string
  firstAddress: string
  lastAddress: string
  broadcastAddress: string
  subnetMask: string
  subnetMaskLength: number
  numHosts: number
  length: number
  contains(other: string): boolean
}
Enter fullscreen mode Exit fullscreen mode

Who Should Use node-ip-ts?

This library is useful if you are building:

  • backend APIs
  • security tools
  • IP allowlist / denylist systems
  • networking utilities
  • infrastructure tools
  • analytics pipelines
  • rate limiters

Especially if your project uses TypeScript.

Contributing

The project is open source and contributions are welcome.

You can:

  • report bugs
  • suggest features
  • submit pull requests

GitHub repository:

https://github.com/denycode-dev/ip-ts

Docs:

node-ip-ts — Type-safe IP Address Utility Library for Node.js

A modern, zero-dependency TypeScript rewrite of the ip package. Full ESM + CJS support, strict types, and drop-in API compatibility.

node-ip-ts.vercel.app

Try it out

If you're working with IP addresses in Node.js and want a modern TypeScript-first alternative to the classic ip library, give node-ip-ts a try.

⭐ If you find it useful, consider starring the repository.

npm install node-ip-ts
Enter fullscreen mode Exit fullscreen mode

Top comments (0)