1. What It Is and Why It's Needed

UUID (Universally Unique Identifier) is an identification standard used in software development to create unique keys without the need for centralized management. The uuid library for JavaScript (Node.js) provides a simple and reliable way to generate UUID versions 1, 3, 4, 5, and 7 (in recent versions). It is one of the most popular and downloaded libraries in the Node.js ecosystem, with over 50 million weekly downloads.

Why is this needed? In modern development, almost every application needs unique identifiers: for database records, user identification, sessions, orders, files, and much more. Using UUID avoids collisions (identifier matches) even in distributed systems where multiple servers generate identifiers simultaneously. For example, if you have a microservice architecture where each service creates records independently, UUID ensures that two services will never create a record with the same ID.

The uuid library supports several versions of the standard: v1 (based on time and MAC address), v4 (random generation), v7 (timestamp + random data — a new standard optimized for databases). Version 4 is the most common due to its simplicity and high degree of uniqueness. Version 7 is recommended for new projects as it provides natural time-based sorting, which improves database index performance.

2. Installation

Installing the uuid library in a Node.js project is done via npm (Node Package Manager). Open a terminal in your project's root folder and run the command:

npm install uuid

If you use yarn:

yarn add uuid

After installation, the library will be available for import in your code. Types are also available for TypeScript projects (installed automatically with the package).

3. Quick Start — Minimal Working Example

Create a file example.js and add the following code:

import { v4 as uuidv4 } from 'uuid';\n\n// Generate a single UUID v4\nconst myUUID = uuidv4();\nconsole.log('Generated UUID:', myUUID);\n// Example output: '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'

Run the file with the command node example.js. You will see the generated UUID in the console. This is a minimal example demonstrating the core functionality of the library — generating a single identifier.

4. Main Methods/Functions

The uuid library provides several functions for generating UUIDs of different versions. Let's look at each one in detail.

4.1. v1() — UUID version 1 (time-based)

Signature: v1(options?, buffer?, offset?)

Description: Generates a UUID version 1, which includes a timestamp (100-nanosecond intervals since October 15, 1582) and the device's MAC address. This guarantees uniqueness in time and space. However, using the MAC address can be a privacy concern.

import { v1 as uuidv1 } from 'uuid';\n\nconst uuid1 = uuidv1();\nconsole.log('UUID v1:', uuid1);\n// Example: 'c9b1deb4-3b7d-11ec-8d3d-0242ac130003'\n\n// With options: disable MAC address (use random node)\nconst uuid1NoMac = uuidv1({ node: [0x01, 0x23, 0x45, 0x67, 0x89, 0xab] });\nconsole.log('UUID v1 with custom node:', uuid1NoMac);