Guide · Open source

How to use compromise: install and run English text analysis in JavaScript

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

compromise is an open-source JavaScript library for working with English text in code. You pass it a sentence or document, and it can find parts of speech, match patterns, pull out data such as numbers and places, and rewrite text. This guide shows how to install it, run the core examples from its README, and decide whether it suits your project.

compromisespencermountain/compromise · ★ 12.2k · MIT Install options & downloads

Quick start

1Check Node.js. Make sure Node.js is installed. The README does not state a required version.
2Install the package. Run npm install compromise in your project folder.
3Import nlp. Add import nlp from 'compromise' to your code.
4Create a document. Pass a sentence or text to nlp() to get a document object.
5Select and transform. Use methods like verbs() or nouns() followed by a transform such as toPastTense() or toPlural().
6Match or extract. Use has() or match() with patterns, then call text() or json() to read the results.

What compromise does and what it doesn't

compromise is a JavaScript library for English text. The README describes it as making limited, sensible decisions rather than being a deep AI model, and says it is meant to be small and fast.

The README also says it is 'not as smart as you'd think'. Expect rule-based analysis of English, not reasoning or state-of-the-art understanding.

Finds parts of speech such as verbs and nouns
Matches text patterns
Extracts data such as numbers and places
Rewrites text, for example converting verbs to past tense or expanding contractions

Install compromise with npm

compromise is installed through a package manager. The README gives one install command. It lists Node.js as the prerequisite but does not state a minimum version.

Import the library in your code with the import line shown in the README examples.

npm install compromise

Find parts of speech and transform text

Create a document with nlp(), then select parts of speech with methods such as verbs() and nouns(). The README example changes a verb to past tense and returns the updated text with text().

import nlp from 'compromise'

let doc = nlp('she sells seashells by the seashore.')
doc.verbs().toPastTense()
doc.text()
// 'she sold seashells by the seashore.'

Match patterns in text

Use has() to test for a pattern, or match() to grab parts of the text. Patterns use tags such as #Verb and #Adjective, and plain words. The README shows matching 'the #Adjective of times' against a text.

The match docs linked from the README cover the full pattern syntax.

let doc = nlp(entireNovel)
doc.match('the #Adjective of times').text()
// "the blurst of times?"

Extract numbers, places and contractions

Numbers can be read and changed as values. Contractions can be expanded into full forms. Place and data extraction needs the separate compromise-speech plugin, which the README loads with nlp.extend().

The README shows that 'gonna' matches 'going to' and that contractions().expand() turns "we're" into "we are".

let doc = nlp('ninety five thousand and fifty two')
doc.numbers().add(20)
doc.text()
// 'ninety five thousand and seventy two'

Use compromise in the browser

The README shows a client-side option that loads the library from a script tag. This lets text processing run in the page without a server.

The README also shows TypeScript-style import usage.

<script src="https://unpkg.com/compromise"></script>
<script>
  var doc = nlp('two bottles of beer')
  doc.numbers().minus(1)
  document.body.innerHTML = doc.text()
  // 'one bottle of beer'
</script>

What people use it for

Changing verbs to past tense in sentences
Pluralizing nouns in short text templates
Matching simple patterns such as 'simon says #Verb' in input text
Expanding contractions before further processing
Running light text processing in a browser page

Frequently asked questions

Is compromise free to use?

compromise is released under the MIT licence, according to the repository details. Check the LICENSE file in the repository for the full terms before you use it in a project.

How do I install compromise?

Run npm install compromise in your project. You then import it with import nlp from 'compromise'. The README gives this as the install method.

What do I need to run compromise?

You need Node.js, or a browser that can load the script from unpkg. The README does not state a minimum Node.js version.

Does compromise support languages other than English?

The core library is English-focused. The README points to separate projects for French, German, Italian and Spanish.

How does compromise compare to natural, spaCy or NLTK?

compromise is a small JavaScript library for simple English analysis. The comparable projects listed are natural and wink-nlp for JavaScript, and spaCy and NLTK for Python. Compare them on the features you need, since this guide does not benchmark them.

Why does my pattern not match?

Patterns depend on how compromise tags words. Test a simple pattern first with has(), then add tags one at a time. The match docs linked from the README show the syntax.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

compromise suits JavaScript developers who need simple English text analysis, pattern matching or quick transforms in a web or Node app, including in the browser. Pick a different tool if you need accurate parsing across many languages, strong reasoning, or a ready-made app without coding.

Install options & downloads