# short-uuid

> Create and translate standard UUIDs with shorter formats.

Latest version **6.0.3** (published 2025-12-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install short-uuid
pnpm add short-uuid
yarn add short-uuid
bun add short-uuid
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 6.0.3 |
| Published | 2025-12-01 |
| First published | 2016-06-05 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=14.17.0 |
| Dependencies | 1 |
| Unpacked size | 69.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 522 |
| Author | Samuel Rouse |
| Maintainers | oculus42 |
| Keywords | uuid, guid, uid, node |

## Links

- npm: https://www.npmjs.com/package/short-uuid
- Repository: https://github.com/oculus42/short-uuid
- Homepage: https://github.com/oculus42/short-uuid#readme
- Issues: https://github.com/oculus42/short-uuid/issues
- npm.io page: https://npm.io/package/short-uuid

## Dependencies (1)

- [any-base](https://npm.io/package/any-base.md) ^1.1.0

## Alternatives

- [@sindresorhus/slugify](https://npm.io/package/@sindresorhus/slugify.md) — 3.7M weekly downloads
- [solid-js](https://npm.io/package/solid-js.md) — 2.7M weekly downloads
- [expo-glass-effect](https://npm.io/package/expo-glass-effect.md) — 2.5M weekly downloads
- [nanoassert](https://npm.io/package/nanoassert.md) — 780.8K weekly downloads
- [@ffmpeg/ffmpeg](https://npm.io/package/@ffmpeg/ffmpeg.md) — 529.5K weekly downloads

## Recent versions

- 6.0.3 (latest) — 2025-12-01
- 6.0.0-beta.2 (prerelease) — 2025-03-18
- 6.0.2 — 2025-11-30
- 6.0.0 — 2025-11-30
- 6.0.0-beta.1 — 2025-03-18
- 6.0.0-beta.0 — 2025-03-12
- 5.2.0 — 2024-05-02
- 5.1.0 — 2024-05-01
- 5.0.1 — 2024-04-30
- 5.0.0 — 2024-04-29
- 4.2.2 — 2022-10-19
- 4.2.0 — 2021-05-13
- 4.1.0 — 2020-09-07
- 4.0.3 — 2020-09-07
- 4.0.2 — 2020-09-07
- … 18 more at https://npm.io/package/short-uuid/versions

## README

# short-uuid

[![npm](https://img.shields.io/npm/v/short-uuid.svg)](https://www.npmjs.com/package/short-uuid)
[![Code Climate](https://codeclimate.com/github/oculus42/short-uuid/badges/gpa.svg)](https://codeclimate.com/github/oculus42/short-uuid)
[![Test Coverage](https://codeclimate.com/github/oculus42/short-uuid/badges/coverage.svg)](https://codeclimate.com/github/oculus42/short-uuid/coverage)

Generate and translate standard UUIDs into shorter - or just *different* - formats and back.

### Quick Start

```javascript
import { generate, createTranslator } from 'short-uuid';

// Generate a short, Base58-encoded UUID immediately:
generate(); // fXqde8UM1CJcfYQVjSaS1E

const translator = createTranslator(); // Default is flickrBase58
translator.generate(); // s2J87kzwLTpm6sy7PjTceZ
```

```javascript
const short = require('short-uuid');

// Generate a short, Base58-encoded UUID immediately:
short.generate(); // 73WakrfVbNJBaAmhQtEeDv

// Or create a translator and generate using its method:
const translator = short.createTranslator(); // Default is flickrBase58
translator.generate(); // mhvXdrZT4jP5T8vBxuvm75
```


## v6.0.0
- Uses [`crypto.randomUUID`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/randomUUID) by default.
- Accepts alternative UUID generators such as [uuidv7](https://www.npmjs.com/package/uuidv7)
- Converted to TypeScript

## Major Changes in v6.0.0
- 🛑 Removes the uuid library as a dependency.
- 🛑 Removes the `new` method in favor of existing `generate`.
- 🛑 Removes the `uuid` method on the default export (previously imported from uuid/v4).
- 🛑 Removes `createTranslator` as default export.
- 🛑 The default `generate` method assumes crypto.randomUUID is available and may error prior to Node 18.
- ⚠️ Node 18 and lower may require passing a `uuid` generator to the translator.

### Usage Details

`short-uuid` starts with RFC4122 v4-compliant UUIDs and translates them
into other, usually shorter formats. It also provides translators
to convert back and forth from RFC-compliant UUIDs to the shorter formats,
and validate the IDs.

By default, shortened values are padded for consistent length. This can be disabled.

As of 6.0.0, short-uuid uses the native `crypto.randomUUID` method to generate UUIDs.
It can also accept alternative UUID generators, such as [uuidv7](https://www.npmjs.com/package/uuidv7).
Node 14.17.0 and later support `crypto.randomUUID`, but may require passing the UUID generator to the translator.

#### Creating Translators
```js
const short = require('short-uuid');
const { uuidv7 } = require('uuidv7');

// Use the default 'flickrBase58' alphabet
const defaultTranslator = short.createTranslator();

// Provide a custom alphabet (string with unique characters)
const decimalTranslator = short.createTranslator('0123456789');
decimalTranslator.generate(); // 340094463662231729161759792859809060270

// Use built-in constants for common alphabets
const cookieTranslator = short.createTranslator(short.constants.cookieBase90);
cookieTranslator.generate(); // 2TsOi>J4~x&|gunsEt/F

// Use an alternative UUID generator
const v7translator = short.createTranslator({ uuid: uuidv7 });
v7translator.generate(); // 1cuDCtXJn1XgatiyAGv63h

// Use a custom alphabet and options
const customV7translator = short.createTranslator(
  '0123456789abcdef',
  { uuid: uuidv7 }
);
customV7translator.generate(); // 019ad63fa3857c74b6db3fae12026b48
```

#### Encoding and Decoding
```js
// Create a translator
const translator = short.createTranslator();

// Generate a short-encoded UUID
const shortId = translator.generate(); // mhvXdrZT4jP5T8vBxuvm75

// Convert from short-encoded to standard UUID
const fullUUID = translator.toUUID(shortId); // a44521d0-0fb8-4ade-8002-3385545c3318

// Convert from standard UUID to short-encoded format
const shortAgain = translator.fromUUID(fullUUID); // mhvXdrZT4jP5T8vBxuvm75
```

#### Validation
```js
// Check if a string has the correct length and alphabet
translator.validate(shortId); // true or false

// Check if it also translates to a valid RFC4122 UUID
translator.validate(shortId, true);  // true if valid
translator.validate('0000000000000000000000', true); // false
```

#### Plain UUIDs
```js
// Each translator also exposes the uuid function it uses to generate UUIDs
const uuidFromTranslator = defaultTranslator.uuid();
```

### Options

The `createTranslator` method supports several arguments:

```javascript
short.createTranslator(alphabet);
short.createTranslator(alphabet, options);
short.createTranslator(options);
```

* `alphabet` - The alphabet to use for translation. Defaults to `short.constants.flickrBase58`.
* `consistentLength` - Controls padding on shortened values. Default is `true`.
* `uuid` - A function that generates a UUID. Defaults to `crypto.randomUUID`.

```javascript
// import does not expose a default export
import { constants, createTranslator } from 'short-uuid';

// By default shortened values are now padded for consistent length.
// If you want to produce variable lengths, like in 3.1.1
const translator = createTranslator(constants.flickrBase58, {
  consistentLength: false,
});

// Generate a shortened v4 UUID
translator.generate(); // mhvXdrZT4jP5T8vBxuvm75
```

## Support

short-uuid [6.x](https://github.com/oculus42/short-uuid/blob/v6.0.0/README.md)
and later is tested on Node 14.17.x and later.

## Notes
Documentation updates from [thadeucity](https://github.com/thadeucity)

Original TypeScript definitions by
[alexturek](https://github.com/alexturek).

Please see [Releases](https://github.com/oculus42/short-uuid/releases) for information on previous versions.

---
_Source: https://npm.io/package/short-uuid · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._