- Written in TypeScript
- Less than 5kB of code
- No runtime dependencies
- Supports ESM and CommonJS
- Comprehensive unit tests
- Node 16+
To query a Minecraft server using an IP/hostname and a port, use:
fetchServerInfo({
address: '1.2.3.4',
port: 25565,
timeout: 1000
});
To perform an SRV record lookup and query a Minecraft server using only a hostname, use:
fetchServerInfo({
hostname: 'example.com',
timeout: 1000
});
Regardless of which way it was invoked, fetchServerInfo
returns a promise which will resolve with an object containing the following properties:
Key | Type | Description |
---|---|---|
online | boolean |
Whether the server is online or not |
If the server is offline, the object will also contain the properties:
Key | Type | Description |
---|---|---|
error | Error |
A communications or validation error, if one occurred |
If the server is online, the object will also contain the following properties:
Key | Type | Description |
---|---|---|
version | string |
The server's version string |
motd | string |
The server's Message of the Day |
players | number |
The number of players on the server |
maxPlayers | number |
The maximum number of players the server supports |
fetchServerInfo
rejects if an error occurs during SRV record resolution.
import { fetchServerInfo } from 'minestat-es';
(async () => {
try {
// query by hostname (SRV lookup)
const { online, error, players } = await fetchServerInfo({
hostname: 'mc.example.com'
});
// OR
// query by address/port
const { online, error, players } = await fetchServerInfo({
address: 'example.com', // could also be an IP address
port: 25565
});
// interpret the results
console.log(`Server is ${online ? 'Online' : 'Offline'}`);
if (online) {
console.log(`There are ${players} player(s) online.`);
} else if (error) {
// either the SRV record failed to resolve, a socket error occurred,
// or the response from the server was invalid
console.error(error);
}
} catch (error) {
// an unexpected error occurred
console.error(error);
}
})();