lorem-ipsum/README.md

Generates lorem ipsum placeholder text for Node.js, Deno, browsers, and React Native. Developed with Bun.

# lorem-ipsum

Generate words, sentences, and paragraphs of lorem ipsum placeholder text.

Version 3 supports modern JavaScript runtimes, including Node.js, Bun, Deno,
modern browsers, and React Native. It has no runtime dependencies and ships ESM,
CommonJS, a browser build, CLI, and TypeScript declaration files.

## Version Notes

This README is for version 3.

Version 3 is tested with Node.js 22+, Bun 1.3+, and Deno 2+.

## What's New in Version 3

Version 3 keeps the public API compatible with version 2 while modernizing the
package around current JavaScript runtimes.

- No runtime or development package dependencies.
- Vanilla JavaScript source with hand-written TypeScript declarations.
- ESM and CommonJS builds for package consumers.
- Browser builds for UNPKG and jsDelivr.
- Bun-powered local development, testing, building, and publishing.

The new v3 package is small:

- ESM: 5.4 kB raw, 1.7 kB gzip
- CommonJS: 6.7 kB raw, 2.2 kB gzip
- Browser: 5.9 kB raw, 1.8 kB gzip
- Browser minified: 3.2 kB raw, 1.4 kB gzip
- npm package: about 8.6 kB packed

For older documentation:

- Version 2: see the `2-stable` branch
- Version 1: see the `1-stable` branch

If you need compatibility with older versions of Node.js, use `lorem-ipsum@2`,
which supports Node.js 8 and later.

For truly ancient runtimes, `lorem-ipsum@1.0.6` supports Node.js as far back as
0.4.

## Installation

```sh
npm i lorem-ipsum
bun add lorem-ipsum
deno install npm:lorem-ipsum
```

## Note for Deno Users

Deno users can import the package from npm with an `npm:` specifier.

```js
import { loremIpsum } from "npm:lorem-ipsum";

console.log(loremIpsum({ count: 2, units: "sentences" }));
```

The library API works in Deno. The CLI can also run under Deno, though commands
that read package metadata or copy to the clipboard may need Deno permissions.

## Note for Browser Users

Browsers can load the package directly from UNPKG.

```html
<script src="https://unpkg.com/lorem-ipsum@3"></script>
<script>
  console.log(LoremIpsum.loremIpsum({ count: 2, units: "sentences" }));
</script>
```

The default UNPKG entry is minified. You can also request the browser builds
explicitly:

```html
<script src="https://unpkg.com/lorem-ipsum@3/dist/index.browser.js"></script>
<script src="https://unpkg.com/lorem-ipsum@3/dist/index.browser.min.js"></script>
```

## Using the Class

The class is the recommended API when you want to reuse the same generation
options.

```js
import { LoremIpsum } from "lorem-ipsum";
// const { LoremIpsum } = require("lorem-ipsum");

const lorem = new LoremIpsum({
  sentencesPerParagraph: {
    max: 8,
    min: 4,
  },
  wordsPerSentence: {
    max: 16,
    min: 4,
  },
});

lorem.generateWords(1);
lorem.generateSentences(5);
lorem.generateParagraphs(7);
```

## Using the Function

`loremIpsum()` is a compatibility API for users who prefer the original
function-style interface.

```js
import { loremIpsum } from "lorem-ipsum";
// const { loremIpsum } = require("lorem-ipsum");

loremIpsum(); // Generates one sentence.
```

You can pass options to customize the output.

```js
import { loremIpsum } from "lorem-ipsum";

loremIpsum({
  count: 1,                // Number of words, sentences, or paragraphs.
  format: "plain",         // "plain" or "html".
  paragraphLowerBound: 3,  // Minimum sentences per paragraph.
  paragraphUpperBound: 7,  // Maximum sentences per paragraph.
  random: Math.random,     // PRNG function.
  sentenceLowerBound: 5,   // Minimum words per sentence.
  sentenceUpperBound: 15,  // Maximum words per sentence.
  suffix: "\n",            // Line ending for paragraphs.
  units: "sentences",      // "words", "sentences", or "paragraphs".
  words: ["ad", "..."],    // Word list to draw from.
});
```

## Using the CLI

Install globally with npm or Bun to use the `lorem-ipsum` command.

```sh
npm i -g lorem-ipsum
bun add --global lorem-ipsum
deno install --global --allow-read --allow-run -n lorem-ipsum npm:lorem-ipsum
```

If you install with Bun, make sure Bun's global bin directory is on your
`PATH`. You can find it with `bun pm bin -g`.

If you install with Deno, make sure Deno's global bin directory is on your
`PATH`. Deno installs global commands under `$HOME/.deno/bin` by default.
Use `--force` to replace an existing Deno install.

```sh
lorem-ipsum --version
lorem-ipsum --help

lorem-ipsum 1 word
lorem-ipsum 2 words
lorem-ipsum 1 sentence
lorem-ipsum 2 sentences
lorem-ipsum 1 paragraph
lorem-ipsum 2 paragraphs

lorem-ipsum 2 paragraphs --format html
lorem-ipsum 2 paragraphs --copy
lorem-ipsum 2 paragraphs --format html --copy
```

On Linux, the `--copy` option requires `xclip`.

## Development

This project uses Bun for local development, testing, building, and publishing.
Bun is not required to use the package at runtime.

```sh
bun test
bun run dev
bun run build
bun publish
```

## License

MIT License

Copyright (c) 2012-2026 Nickolas Kenyeres <dev@kenyeres.ca>

See [LICENSE](LICENSE).