PrismJS: what the syntax highlighter does before you reach for it

The problem Prism solves, and the shape of the project

A page that shows code needs the code to be tokenised before it can be coloured. Prism takes text, splits it into tokens according to a grammar for a named language, and wraps those tokens in elements a stylesheet can target. The README describes it as a lightweight, robust, and elegant syntax highlighting library, and notes it is a spin-off from Dabblet.

The audience is narrow and specific. If you are building documentation sites, blog engines, notebook viewers or any interface that renders source code, Prism is meant to sit between the raw text and the rendered page. It is not a code editor, it does not provide completion or diagnostics, and it does not parse a language for semantic meaning beyond what the highlighting grammar needs.

The repository layout reflects that split. There is a src/ directory, a tests/ directory, a benchmark/ directory, and a scripts/ directory that runs the build. The README explicitly warns contributors not to edit prism.js, because that file is the version of Prism used by the Prism website and is generated automatically. Changes belong in the unminified files under components/.

How Prism tokenises code: grammars, tokens and the build

Each supported language is described by a grammar. The README points contributors to the extending documentation for creating a new language definition, and requires that a new language or plugin be added to components.json and that Prism be rebuilt with npm run build so the language becomes available on the download build page.

That components.json file is not incidental. It is the manifest the build system reads, and it is also exported from the package: the exports map in package.json exposes "./components.json" pointing at "./dist/components.json". So the set of languages and plugins you can pull in is decided at build time, not discovered at runtime.

The package is published as an ES module first. package.json sets "type": "module", with "main" at ./dist/cjs/index.js and "module" at ./dist/index.js, so both a require path and an import path exist. Language and plugin files are exposed through wildcard subpaths: "./languages/*.js" resolves to ./dist/languages/*.js for imports and ./dist/cjs/languages/*.js for requires, and "./plugins/*.js" follows the same pattern. Themes and plugin stylesheets are plain CSS exports, "./themes/*.css" and "./plugins/*.css".

The consequence is that a Prism install is not one artefact. It is a core plus the subset of language and plugin files you actually import, which is why the library can stay small in a page that only highlights two languages.

Installing prismjs and building it from source

The package name is prismjs. The README's contributing notes describe the project's own dependency install, and they are explicit that npm ci is the intended command rather than npm install, because npm install causes non-deterministic builds.

npm ci

With all of Prism's dependencies installed, the README says you run the build command. This minifies the files and builds prism.js, and it is also the step required after adding a language or plugin to components.json so the addition becomes available on the download build page.

npm run build

The README also lists the software requirements for contributing: Node.js >= 10.x and npm >= 6.x. On the default branch, package.json sets the engines field to node >=18, so the published v2 line asks for a newer runtime than the v1 contributing notes describe.

The README points to the prism-themes repository for additional themes, and says that a new theme belongs there rather than in this repository. The package exposes its stylesheet directly: package.json sets "style" to dist/themes/prism.css, and the themes subpath maps to CSS files.

What v1's freeze means for anyone starting today

The README carries an important notice near the top: the project is working on Prism v2 and will only accept security-relevant PRs for the time being. It says PRs will be accepted again once work on v2 is sufficiently advanced, and that this will be announced on the Discussion page and in the roadmap discussion.

That is a maintenance posture, not an abandonment, and the distinction matters when you are choosing a dependency. The last push to the repository was on 2026-09-17, so the repository is being touched. But the default branch is v2, and package.json on that branch reports version 2.0.0-alpha.1. The last stable release listed is v1.30.0 from 2025-03-10, after a much longer gap since v1.29.0 in 2022.

Read together, these facts describe a project in transition. If you install the published stable line you are installing something that receives security fixes and little else. If you install from the default branch you are installing an alpha whose API is still moving. Neither is wrong, but they are different bets, and the README does not document a rollback path for a v2 upgrade.

Where Prism is the wrong tool

Prism highlights text. It does not build a syntax tree you can query, and the language definitions exist to drive tokenisation, not to validate or analyse code. If you need to detect errors, resolve symbols, or transform source, a parser is the right dependency and Prism is not a substitute for one.

The build-time manifest is a second boundary. Because languages and plugins are registered through components.json and shipped as separate files, a language that is not in that manifest is not available from the package. The README tells contributors they are responsible for handling bug reports about a language definition they add, which is a fair signal about how much central review a given grammar has received.

There is also a maintenance boundary worth stating plainly. A grammar bug in a language that only accepts security-relevant PRs is unlikely to be fixed quickly, and the README's note about limited review time for large PRs predates the freeze but still describes the project's habits. If your product depends on correct highlighting for an uncommon language, treat the grammar as something you may end up owning.

Prism against highlight.js and Shiki

The obvious comparison is highlight.js. Both are JavaScript syntax highlighters that tokenise text and emit marked-up output, and both ship per-language definitions. The practical difference is in packaging and configuration: Prism exposes a components.json manifest and subpath exports so you compose exactly the languages and plugins you import, while the choice of what to bundle is a build decision you make up front.

Shiki takes a different route entirely. It uses TextMate grammars, the same grammar format editors use, which means its output tends to match what you see in an editor and it can reuse existing grammar files. That approach pulls in more machinery than Prism's own grammars. Prism's README does not compare itself to either project, so the trade-off is yours to weigh: Prism is the smaller surface, Shiki is the closer match to editor rendering.

If your requirement is simply that code looks coloured and the language list is short, the size difference is the deciding factor. If your requirement is that the highlighting matches a specific editor theme, Prism's grammars are not the same artefact.

Licence, contribution rules and upgrade cost

Prism is MIT licensed, and the repository carries a LICENSE file at the top level alongside MAINTAINERS.md and SECURITY.md. The SECURITY.md file is the place to look for how vulnerabilities should be reported, and the README's freeze on non-security PRs makes that channel more relevant than usual.

The contribution rules are unusually concrete and worth reading even if you never send a patch, because they tell you how the codebase is maintained. Contributors are asked to use npm ci rather than npm install to avoid non-deterministic builds, to run npm run build after adding a language or plugin, to add tests and an example under examples/ for new languages, and to prefer several smaller PRs over one large one. The README also states a code convention of tabs for indentation and spaces for alignment.

For upgrade cost, the honest answer is that v1 to v2 is not documented as a migration. The repository is on v2, package.json reports 2.0.0-alpha.1, and the README points to a roadmap discussion rather than a migration guide. If you depend on Prism today, pinning the version and reading CHANGELOG.md before moving is the only concrete step the repository supports.

Editorial conclusion

Adopt Prism if you need syntax highlighting in a browser or Node.js and you want the language set to be a build-time choice rather than a runtime one. Do not adopt it expecting active feature development on v1: the README states that only security-relevant PRs are being accepted while v2 is in progress, and the default branch is v2. Before committing, verify that the languages and plugins you need exist in components.json, and pin the version you install, because the repository is already publishing 2.0.0-alpha.1 while v1.30.0 remains the last stable release.

Frequently asked questions

Official sources

1. License: MIT
2. PrismJS/prism on GitHub
3. Project website
4. README
5. Releases