NTP Client for Node.js

0.5.3 verified Thu Apr 23 auth: no javascript abandoned

The `ntp-client` package provides a pure JavaScript implementation of the NTP (Network Time Protocol) client, allowing Node.js applications to retrieve the current network time from an NTP server. Its latest stable version, 0.5.3, was published over a decade ago in 2014, indicating that the project is largely abandoned. It differentiates itself by offering a minimal codebase with zero external dependencies, directly handling the NTP protocol for basic time retrieval. However, due to its lack of recent updates and maintenance, users might consider more actively maintained alternatives like `ntp-client-promise` or `ntp-time` for modern Node.js environments, especially those requiring ESM support or advanced features. An `@types/ntp-client` package exists, last updated in 2023, providing TypeScript definitions for version 0.5.0.

Common errors

error Error: bind EACCES 0.0.0.0:123 ↓

cause The application is attempting to bind to a privileged port (123, the default NTP port) without sufficient operating system permissions.

fix

Run the Node.js process with sudo or as an administrator (not recommended for production). Alternatively, configure your NTP server to listen on a non-privileged port (e.g., above 1024) and specify that port in getNetworkTime.

error Error: ETIMEOUT ↓

cause The NTP server did not respond within the default 10-second timeout. This could be due to network connectivity issues, an incorrect server address/port, or the NTP server being down or blocked by a firewall.

fix

Verify that pool.ntp.org (or your chosen server) is reachable and port 123 is open in your firewall. Check your internet connection. You can increase the timeout by passing an options object: ntpClient.getNetworkTime('pool.ntp.org', 123, { timeout: 20000 }, function(err, date) { ... }).

error TypeError: Cannot read properties of undefined (reading 'getNetworkTime') ↓

cause The `ntpClient` object was not correctly imported or is undefined, often due to incorrect CommonJS `require` syntax or a missing `npm install ntp-client`.

fix

Ensure the package is installed (npm install ntp-client) and imported correctly using const ntpClient = require('ntp-client');. Verify no destructuring is used: getNetworkTime is a method of the default export object, not a named export.

Warnings

breaking This package is a CommonJS module and does not natively support ES Modules (`import/export`) without a transpilation step or dynamic import. Attempting to `import` directly will result in errors in pure ESM environments. ↓

fix Use `const ntpClient = require('ntp-client');` for CommonJS environments. For ES Module projects, either configure a transpiler (e.g., Babel, TypeScript) or use dynamic `import('ntp-client')`. Consider alternatives like `ntp-client-promise` for native ESM support.

gotcha The `ntp-client` package has not been updated since 2014, making it effectively abandoned. It may contain unpatched bugs, security vulnerabilities related to the NTP protocol, or compatibility issues with newer Node.js versions. ↓

fix Assess the risk for your application. For critical or production applications, consider migrating to actively maintained NTP client libraries like `ntp-client-promise` or `ntp-time` that receive regular updates and support.

gotcha This client performs a single NTP query to retrieve the current time. It does not implement advanced NTP features like clock slewing (gradual adjustment) or a full NTP daemon, which are crucial for maintaining highly accurate and stable system time without sudden jumps that can disrupt applications. ↓

fix Understand that this library is for one-shot time retrieval. For robust, continuous system time synchronization, rely on operating system NTP services (e.g., `ntpd`, `systemd-timesyncd` on Linux, Windows Time service) or dedicated NTP daemon implementations.

gotcha Using the default NTP port (123) might require elevated privileges (root/administrator) on some operating systems to bind the UDP socket, potentially leading to 'EACCES' or similar permission errors. ↓

fix Ensure your Node.js process has necessary network binding permissions. For production, consider configuring your network or server to allow binding to port 123, or use a non-privileged port (e.g., 8123) if your NTP server explicitly supports it. Running with `sudo node app.js` can temporarily fix this for testing but is not recommended for production.

Install

npm install ntp-client

yarn add ntp-client

pnpm add ntp-client

Imports

ntpClient
wrong
```
import ntpClient from 'ntp-client';
```
correct
```
const ntpClient = require('ntp-client');
```
This package is a CommonJS module; direct ES Module `import` syntax is not supported without transpilation. Only the default export, an object with `getNetworkTime`, is provided.
getNetworkTime
wrong
```
const { getNetworkTime } = require('ntp-client');
```
correct
```
const ntpClient = require('ntp-client');
ntpClient.getNetworkTime('pool.ntp.org', 123, ...);
```
`getNetworkTime` is a method of the `ntpClient` object, not a named export. The package's module export is the `ntpClient` object itself.
Callback-based API
```
ntpClient.getNetworkTime(server, port, callback);
```
The primary API is callback-based. There are no Promise-based versions built into this package.

Quickstart

Demonstrates how to fetch the current network time from a specified NTP server using the `getNetworkTime` function and log the result.

const ntpClient = require('ntp-client');

const NTP_SERVER = process.env.NTP_SERVER ?? 'pool.ntp.org';
const NTP_PORT = parseInt(process.env.NTP_PORT ?? '123', 10);

ntpClient.getNetworkTime(NTP_SERVER, NTP_PORT, function(err, date) {
    if (err) {
        console.error('Failed to get network time:', err);
        return;
    }

    console.log(`Current network time from ${NTP_SERVER}:${NTP_PORT}:`);
    console.log(date.toISOString());
    console.log('Local system time for comparison:');
    console.log(new Date().toISOString());
});