mintly

Generate random adjective + noun combinations instantly for project names, IDs, slugs, and more.

A lightweight, zero-dependency npm package that provides human-readable random names through a simple API. Perfect for developers who need memorable identifiers without the hassle of manual naming or external API calls.

Features

• 🎯 Simple API — One-line function call to generate names
• 🎨 Multiple Formats — kebab-case, camelCase, PascalCase, snake_case, lowercase
• 🌐 Universal — Works in Node.js and browsers
• 📦 Lightweight — Lite build under 50KB (gzipped ~6KB)
• 🎭 Themed — Choose from tech, nature, or food word themes
• 🔒 Safe — Curated word lists with no inappropriate combinations
• 🎲 Unique — Guarantees unique results in a single call
• 🚀 Fast — Sub-millisecond generation time
• 🛠️ CLI Included — Use directly from terminal with npx mintly

Installation

npm

npm install mintly

pnpm

pnpm add mintly

yarn

yarn add mintly

Usage

Library API

Basic Usage

import { mintly } from 'mintly'

// Generate 3 random names (default)
const names = mintly()
// ['happy-world', 'cute-bird', 'angry-monkey']

With Options

// Specify count
mintly({ count: 5 })
// ['happy-world', 'cute-bird', 'angry-monkey', 'brave-lion', 'gentle-wave']

// With suffix
mintly({ count: 1, suffix: 'test' })
// ['cute-girl-test']

// With prefix
mintly({ count: 1, prefix: 'my' })
// ['my-happy-world']

// Custom separator
mintly({ count: 1, separator: '_' })
// ['happy_world']

// Format options
mintly({ count: 1, format: 'camelCase' })
// ['happyWorld']

mintly({ count: 1, format: 'PascalCase' })
// ['HappyWorld']

mintly({ count: 1, format: 'snake_case' })
// ['happy_world']

// Combine options
mintly({ count: 3, prefix: 'project', format: 'camelCase' })
// ['projectHappyWorld', 'projectCuteBird', 'projectAngryMonkey']

// Theme selection (available: tech, nature, food)
mintly({ count: 3, theme: 'tech' })
// ['async-server', 'binary-kernel', 'modular-proxy']

mintly({ count: 3, theme: 'nature' })
// ['alpine-meadow', 'coastal-reef', 'wild-falcon']

mintly({ count: 3, theme: 'food' })
// ['savory-risotto', 'fresh-mango', 'crispy-waffle']

// Theme with other options
mintly({ count: 2, theme: 'tech', format: 'camelCase', prefix: 'svc' })
// ['svcAsyncServer', 'svcBinaryKernel']

CLI

Basic Commands

# Generate 3 random names (default)
npx mintly

# Generate specific count
npx mintly -c 5
npx mintly --count 5

# With prefix and suffix
npx mintly -c 1 -p my -s test
# Output: my-cute-girl-test

# Format options
npx mintly --format camelCase
npx mintly --format PascalCase
npx mintly --format snake_case

# Custom separator
npx mintly --separator _
npx mintly --separator .

# Theme selection
npx mintly --theme tech
npx mintly --theme nature -c 5
npx mintly --theme food --format camelCase

# Show help
npx mintly --help

# Show version
npx mintly --version

CLI Options Reference

| Flag | Alias | Description | Default | |------|-------|-------------|---------| | --count | -c | Number of names to generate (1-10) | 3 | | --prefix | -p | Prefix to prepend to each name | - | | --suffix | -s | Suffix to append to each name | - | | --format | - | Output format (see formats below) | kebab | | --separator | - | Custom separator character | format default | | --theme | - | Word theme (tech, nature, food) | - | | --help | -h | Show help message | - | | --version | -v | Show version number | - |

Browser / Lite Build

For browser environments or when bundle size matters, use the lite build which includes a smaller curated word list (~100 adjectives + ~100 nouns):

import { mintly } from 'mintly/lite'

// Same API as the main build
const names = mintly({ count: 3 })
// Works identically, but with smaller bundle size

// All options work the same
mintly({
  count: 5,
  format: 'camelCase',
  prefix: 'app'
})

Bundle Size Comparison:

• Main build: ~69KB raw, ~20KB gzipped (includes 2,000+ adjectives and 2,000+ nouns with theme support)
• Lite build: ~57KB raw, ~17KB gzipped

The lite build uses a smaller word list but maintains the same API and guarantees unique combinations for up to 10 names.

Note: The theme option is not supported in the lite build. Using mintly({ theme: 'tech' }) with mintly/lite will throw a TypeError. Themes are only available in the main build.

API Reference

mintly(options?: MintlyOptions): string[]

Generates random adjective + noun combinations.

Parameters:

• options (optional): Configuration object

Returns: string[] — Array of generated names

Options (MintlyOptions):

| Property | Type | Default | Description | |----------|------|---------|-------------| | count | number | 3 | Number of names to generate (1-10). If count exceeds available unique combinations, returns maximum possible with a console warning. | | format | 'kebab' \| 'camelCase' \| 'PascalCase' \| 'snake_case' \| 'lowercase' | 'kebab' | Output format for generated names | | prefix | string | undefined | String to prepend to each name. Applied with same format rules. | | suffix | string | undefined | String to append to each name. Applied with same format rules. | | separator | string | format default | Custom separator character. Overrides format's default separator. | | theme | 'tech' \| 'nature' \| 'food' | undefined | Word theme for generation. Selects words from a theme-specific pool. Not available in lite build. |

Format Examples

| Format | Example Output | Separator | |--------|----------------|-----------| | kebab | happy-world | - | | camelCase | happyWorld | none | | PascalCase | HappyWorld | none | | snake_case | happy_world | _ | | lowercase | happyworld | none |

Behavior Notes

• Uniqueness: All returned names in a single call are guaranteed to be unique
• Count Limit: Maximum 10 names per call. Requesting more will return up to 10 with a console warning
• Error Handling: Invalid options (e.g., negative count, invalid format) throw TypeError
• Performance: Generation time is typically under 1ms

Use Cases

Project Names

import { mintly } from 'mintly'

// Generate project name candidates
const candidates = mintly({ count: 5, format: 'kebab' })
console.log(candidates)
// Choose your favorite from the list

Microservice Instances

// Generate service instance identifiers
const serviceIds = mintly({
  count: 10,
  suffix: 'svc',
  format: 'kebab'
})
// ['happy-world-svc', 'cute-bird-svc', ...]

Test Data

// Generate random usernames for testing
const usernames = mintly({
  count: 5,
  format: 'camelCase'
})
// ['happyWorld', 'cuteBird', 'angryMonkey', ...]

Default Nicknames

// In a browser app - generate default chat room name
import { mintly } from 'mintly/lite'

const defaultRoomName = mintly({
  count: 1,
  prefix: 'room',
  format: 'camelCase'
})[0]
// 'roomHappyWorld'

Git Branch Names

# Generate random branch name
git checkout -b $(npx mintly -c 1 -p feat --format kebab)
# Creates: feat-happy-world

Technical Details

Word Lists

• Main build: 2,000+ adjectives × 2,000+ nouns = 4,000,000+ combinations
• Lite build: ~100 adjectives × ~100 nouns = 10,000+ combinations
• Themes: tech (~150 × ~150), nature (~150 × ~150), food (~100 × ~100) — subsets of the main word pool
• Curation: All words are pre-curated to avoid inappropriate or offensive combinations

Module Format

• ESM only — This package uses modern ES modules (type: "module")
• Node.js: Requires Node.js 18+ (LTS)
• TypeScript: Full TypeScript support with type definitions included

Dependencies

Zero runtime dependencies. This package is completely self-contained.

Performance

• Generation time: Sub-millisecond (typically <1ms)
• Memory footprint: Minimal — word lists are static arrays
• Bundle size: Optimized with tree-shaking support

TypeScript

Full TypeScript support included:

import { mintly, type MintlyOptions, type ThemeName } from 'mintly'

const options: MintlyOptions = {
  count: 5,
  format: 'camelCase',
  prefix: 'test'
}

const names: string[] = mintly(options)

// With theme
const theme: ThemeName = 'tech'
const techNames = mintly({ count: 3, theme })

Type definitions are automatically available when using the package.

Contributing

Contributions are welcome! This project follows standard GitHub workflow:

1. Fork the repository
2. Create your feature branch (git checkout -b feat/amazing-feature)
3. Make your changes with tests
4. Run quality checks: pnpm check (lint + format + test)
5. Commit your changes
6. Push to the branch
7. Open a Pull Request

Development Setup

# Clone the repo
git clone https://github.com/kjunine/mintly.git
cd mintly

# Install dependencies
pnpm install

# Run tests
pnpm test

# Run linter
pnpm lint

# Check formatting
pnpm format:check

# Build
pnpm build

License

MIT © Daniel Kyojun Ku

Acknowledgments

• Word lists are curated from common English adjectives and nouns
• Inspired by the need for human-readable identifiers in modern development workflows