Library / SDK
spencermountain/compromise avatar
spencermountain/compromise

Compromise tags English with a conjugated word list, not a model

modest natural-language processing

12,174 stars673 forksJavaScriptMIT

At a glance

What is it?
compromise is a JavaScript NLP library that turns English text into tagged data by conjugating a fixed lexicon of roughly 14,000 words. That choice buys a 250kb browser build and caps how far tagging can go on words the list never saw.
Who is it for?
Adopt compromise when the input is English, the job is rule shaped (find a phrase, conjugate a verb, add a number to a spelled out value) and the code has to run in a browser tab. Do not adopt it as a general NLP stack: the lexicon is about 14,000 conjugated English words, the language forks cover French, German, Italian and Spanish only, and no other language has an entry point in this repository.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 1 day ago.
What is it written in?
Mainly JavaScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • spencermountain/compromise12,174 ★ · +17
Star history
Repository2026-09-162026-11-15
spencermountain/compromise12.2k12.2k

17 Stars in the last 60 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Every form comes from one conjugated word list

compromise has no model file and no training step. The README says it works mainly by conjugating all forms of a basic word list, and that the final lexicon is around 14,000 words. That single decision explains both the speed and the ceiling: a lookup table generated at build time can answer questions about words the table contains, and can say nothing useful about words it does not.

The project is blunt about the limit. It calls itself modest natural language processing, says it makes limited and sensible decisions, and adds that it is not as smart as you'd think. The top-level entries of the repository are source directories (one/, two/, three/, tokenize/, src/) plus plugins/ and data/, and nothing in that list reads as stored weights.

For you the consequence is specific: match patterns address tags that come out of that list, so a word the lexicon never saw may be tagged less reliably. Product names, ticket IDs and in-house jargon are where rules quietly stop matching. Test your own vocabulary through doc.match() before building anything on top of it.

What the core cannot compute, a plugin can attach. compromise-speech is loaded with nlp.extend(), which adds a computation step rather than more vocabulary:

js
import plg from 'compromise-speech'
nlp.extend(plg)

let doc = nlp('Milwaukee has certainly had its share of visitors..')
doc.compute('syllables')
doc.places().json()

The json() call then returns terms with a normal form and a syllables array, which is the shape you use when you need data instead of a string.

The entry points decide which of the four layers you load

package.json publishes several subpaths, and the import condition never points at the same file as the require condition. The root import resolves to ./src/three.js while a CommonJS require of the root resolves to ./builds/three/compromise-three.cjs. The same pairing repeats for ./one, ./two, ./three and ./tokenize, each with a matching declaration file: ./types/three.d.ts for ESM and ./types/three.d.cts for require.

Two entries in that map are types only. The ./misc export lists a declaration and no runtime file, and the ./view/* export is laid out the same way, so those helpers are declarations in this package rather than a module you call at runtime.

The package also sets type to module.

The practical trap: importing compromise/two gives you the tagger and none of the sentence level methods, and it will still parse your string happily. Decide which of the four layers you need before you measure anything.

First run is npm install and one call that returns text

The whole setup is the command printed at the top of the README. There is no config file, no model download and no build step on the consumer side, because the runtime files ship inside the package.

bash
npm install compromise

Import the default export, hand it a string, and you get a doc object. Asking it a question returns text rather than a parse tree, and transforming it changes the string you get back.

js
import nlp from 'compromise'

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

Patterns are how you pull a slice out of a longer document. The tag prefixed with a hash is resolved by the tagging layer, so a pattern call already assumes that stage ran.

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

If all you need is to split text into words, sentences and punctuation, import compromise/one and stop there. The next layer up is the tagger:

js
import nlp from 'compromise/two'

let doc = nlp("Wayne's World, party time")
let str = doc.match('#Possessive #Noun').text()
// "Wayne's World"

The shortest useful filter is a has() call with a tag in it, which is how the README suggests gating logic:

js
if (doc.has('simon says #Verb')) {
  return true
}

Arithmetic happens in words, and has() matches more than the text says

Numbers are handled as spelled out words, not as parsed values. Adding 20 to a phrase written out in full crosses a tens boundary, and the output word changes shape to match.

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

The transformation is bounded by how far the lexicon carries number words. The visible examples only cover whole numbers written out in words, so a rule that assumes a numeric range has to be checked against your own values.

The second surprise is that has() is a semantic match rather than a string search. Both of these return true for the same sentence, even though only one of the words is actually present:

js
let doc = nlp("we're not gonna take it..")

doc.has('gonna') // true
doc.has('going to') // true (implicit)

// transform
doc.contractions().expand()
doc.text()
// 'we are not going to take it..'

So a has() filter will report matches that do not appear in the source string. If you are counting occurrences for a report or a metric, counting with has() gives a different number than counting the literal words yourself.

Script tag users pay for the full 250kb build

The browser path needs no bundler and no import statement. Two script tags are enough, and the same arithmetic from the numbers layer runs against the live document.

html
<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>

Read the output closely. The input was two bottles, the number went down by one, and the noun came back singular. The transform is a text rewrite that re-inflects, not an edit to a number field, so anything you do downstream that expects independent parts has to re-parse the result.

The cost of that convenience is stated on the same page: compromise is about 250kb minified. Since the script tag loads the whole build, a page that only needs string splitting downloads the tagger and the sentence layer as well.

If you control the build, a named subpath import is the cheaper route. If you do not, decide whether 250kb is acceptable on your slowest connection before you commit to it.

The tagger is not 100%, and the lexicon stops at four other languages

The README says compromise tries its best to turn text into data and is not as smart as you'd think. Read that as a design position, not a defect to be filed: rules built on a tag will be wrong on some fraction of any corpus, and your job is to find which fraction with your own words.

If tagging quality is what you are buying, your own evaluation set is the only one that will settle it.

Language coverage is the harder boundary. The English build is the only one in this repository. Four sibling projects exist for French, German, Italian and Spanish, and they live in separate nlp-compromise repositories, so upgrading the core does not upgrade the one you depend on for another language. No other languages are listed.

The consequence for a reader is blunt: a corpus in Portuguese, Japanese or Turkish has no entry point here, and rules written against English tags do not transfer to a language with different morphology. Pick a different toolkit for those, and keep this one for English.

The speed figures belong to the tokenizer, not the tagger

The performance numbers attached to this project describe compromise/one, the tokenizer layer. The most precise claims on the page: most sentences take a tenth of a millisecond, it handles about 1mb of text a second, roughly ten Wikipedia pages, and Infinite jest takes 3 seconds. There is also an unnumbered claim that it can run on keypress.

Importing the layer below the tagger looks like this, and the output is where the cost of normalisation becomes visible:

js
import nlp from 'compromise/one'

let doc = nlp("Wayne's World, party time")
let data = doc.json()
/* [{
  normal:"wayne's world party time",
    terms:[{ text: "Wayne's", normal: "wayne" },
      ...
      ]
  }]
*/

Note what normal does there. The source token is Wayne's and the normalised form is wayne, so the possessive suffix is dropped during normalisation. If you need the surface text, read terms[].text; normal is a lookup key, not the original.

None of those timings cover compromise/two. Once tagging is switched on, the tenth of a millisecond figure does not describe your run. The plugin directory holds compromise-speed for parallelizing or streaming text to the tokenizer, which is the documented way to push more through it.

Measure the layer you will actually ship. The gap between the tokenizer and the tagger is where an onkeypress handler stops being cheap.

MIT licence, three releases since May, and generated builds

The licence is MIT, and the top-level entries of the repository contain no licence agreement file beyond the standard LICENSE. No CLA file sits alongside it, so there is no extra sign-off step to budget for when you vendor the code.

Release cadence is steady. Recent releases are 14.17.0 on 2026-09-10, 14.18.0 on 2026-10-05 and 14.19.0 on 2026-10-18, and the last push to master landed on 2026-10-30. That is a minor release every two to four weeks, which is frequent enough that a tag your rules depend on can move under you between two installs.

The published artefacts are generated in the repository. pnpm-workspace.yaml and pnpm-lock.yaml describe the workspace, rollup.config.js builds the bundles, and builds/ holds the output, including the three .cjs files that the require condition points at. The ESM condition serves ./src/three.js directly from source instead. Comparing bundle sizes between the two conditions is therefore not a like-for-like measurement.

changelog.md is the place to check what moved between the version you pinned and the one you are considering, and the tests/ directory holds the project's tests. Pin 14.19.0 in your lockfile and read the changelog before taking the next minor.

Editorial conclusion

Adopt compromise when the input is English, the job is rule shaped (find a phrase, conjugate a verb, add a number to a spelled out value) and the code has to run in a browser tab. Do not adopt it as a general NLP stack: the lexicon is about 14,000 conjugated English words, the language forks cover French, German, Italian and Spanish only, and no other language has an entry point in this repository. Before committing, push your own vocabulary through compromise/two and confirm the words your rules depend on get the tags you assumed, because a lexicon tagger fails quietly on words it never saw. Version 14.19.0 shipped on 2026-10-18 and the last push landed on 2026-10-30, so pin that version instead of tracking master.

Frequently asked questions

How does compromise work?

It conjugates all forms of a basic word list into a final lexicon of about 14,000 words, then tags and transforms text against that list. There is no model and no training step, which is why the project describes itself as modest natural language processing.

How do you use compromise in JavaScript?

Run npm install compromise, then import the default export and pass it a string. The doc object it returns exposes verbs(), nouns(), match(), numbers(), has() and text(), and text() gives the string back after any transform.

What is compromise the library?

An MIT licensed JavaScript natural language processing package published on npm as compromise. It ships in layers: compromise/one tokenizes words, sentences and punctuation, compromise/two adds part-of-speech tagging, and the root entry gives the full build.

Official sources

  1. License: MIT
  2. Project website
  3. README
  4. Releases
  5. spencermountain/compromise on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/spencermountain-compromise.svg)](https://hysenlabs.com/projects/spencermountain-compromise)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/spencermountain-compromise.svg)](https://hysenlabs.com/projects/spencermountain-compromise)

Was this useful?