issue-parser review
issue-parser 7.0.2 extracts forge references from plain text. A configured parser separates ordinary issue or pull request references, action phrases such as `Fix #42`, and user mentions. Presets cover GitHub, GitLab, and Bitbucket; custom hosts, prefixes, URL segments, delimiters, and action vocabularies cover self-hosted or internal conventions. The 7.0.2 fix stops references inside HTML comments from being reported. It remains a synchronous regex parser: it does not call a forge, validate a repository, resolve a bare `#42`, or parse Markdown into a syntax tree.
issue-parser 7.0.2 installed 6 packages in 1.2 seconds and bundled to 7.5 KB gzipped in our sandbox, with no audit findings but no TypeScript declarations. Use it for configurable forge-reference extraction; do not use its regex matches as proof that an issue exists or that Markdown was parsed exactly.
We installed it
| Install | ✓ · 1.2s | 6 packages on disk · 1 MB |
| Import | ✓ | ESM import works · require() works · CommonJS package |
| Browser | 7.5 KB | gzipped (20.5 KB minified), bundled with esbuild |
| Types | — | no TypeScript types found |
| Known vulns | 0 | 0 critical · 0 high · 0 moderate · 0 low (npm audit) |
Answers from our run
Does issue-parser install cleanly?
Yes. In a fresh container with an empty cache, npm install issue-parser finished in 1 seconds, leaving 6 packages and 1 MB on disk. npm audit reported no known vulnerabilities.
How much does issue-parser add to a browser bundle?
7.5 KB gzipped (20.5 KB minified) when the whole package is bundled for the browser with esbuild. Importing only part of it is usually smaller.
Does issue-parser work with both ESM and CommonJS?
Yes. Both import 'issue-parser' and require('issue-parser') worked in Node 22 in our run. The package is published as CommonJS.
Does issue-parser include TypeScript types?
No type declarations were found in our install, so TypeScript users need their own declarations.
issue-parser or issue-regex: which should you use?
issue-regex: Choose it when a single GitHub-style reference regex is enough and you do not need actions or mentions. issue-parser 7.0.2 installed 6 packages in 1.2 seconds and bundled to 7.5 KB gzipped in our sandbox, with no audit findings but no TypeScript declarations.
When should you not use issue-parser?
You need proof that a user, repository, issue, or pull request exists. issue-parser performs no network lookup and returns text matches only.
Use it if
- Release notes, commit messages, or bot commands need issue actions and mentions split into structured records.
- One parser must recognize GitHub, GitLab, or Bitbucket conventions without calling their APIs.
- A self-hosted forge uses familiar numeric issue syntax with custom hosts, prefixes, or URL path segments.
- References inside common inline code, fenced code, HTML code tags, and HTML comments should be ignored.
- You need proof that a user, repository, issue, or pull request exists. issue-parser performs no network lookup and returns text matches only.
- Source offsets, line numbers, or exact Markdown semantics are required. The result has no positions, and excluded code or comment regions are handled with regular expressions.
- Your TypeScript project requires package-owned declarations. Our 7.0.2 inspection found no type files, so you must add a wrapper or local declaration.
- The application is moving immediately to native ESM. Version 7 is CommonJS, while the published 8.0.0 beta changes to ESM and raises the Node floor to 22.22.2 or 24.15.
- References use nonnumeric identifiers or context-dependent grammar. The configurable matcher still expects digits after known issue prefixes and cannot understand arbitrary prose.
Setup reality
We installed issue-parser 7.0.2 in a fresh Node 22 Bookworm sandbox. npm took 1.2 seconds and left 6 packages using 1 MB. The package was 44 KB unpacked, with 5 direct dependencies and no peers, and npm audit returned 0 known vulnerabilities. It is CommonJS without an exports map; both require() and ESM import worked. The package contains no TypeScript declarations.
There are no credentials, native addons, or config files. Call the exported factory with github, gitlab, bitbucket, or a custom option object, then reuse its synchronous parse function. The factory compiles the regular expressions. A bare #12 has no repository slug, so your application must attach the current repository before it can query an API or build an unambiguous link. Issue numbers remain strings.
Results separate refs, actions, and mentions. allRefs combines ordinary and action references, but it is a non-enumerable getter in version 7. Copy it into a normal property before JSON.stringify() or object spread. Overrides replace preset arrays for an existing option; include every host or keyword you still want. The parser removes common code spans, fences, HTML code tags, and comments before matching, but malformed Markdown can defeat regex-based exclusion.
Our browser bundle succeeded at 20.5 KB minified and 7.5 KB gzipped. That is large for a few regular expressions because 5 lodash subpackages ship with the parser. The code is synchronous, so unusually large untrusted documents should be size-limited before parsing. Version 8.0.0 beta switches to ESM and much newer Node releases; pin major 7 if CommonJS compatibility is part of your runtime contract.
Patterns
Split GitHub actions and mentions parse-github-message
const issueParser = require('issue-parser');
const parse = issueParser('github');
const result = parse('Fix #12, see owner/docs#8, and ping @alex');
console.log(result.actions.close);
console.log(result.refs);
console.log(result.mentions);A bare `#12` has no slug. Attach the current repository in application code before turning it into a URL or API request.
Recognize GitLab issue and merge request forms parse-gitlab-message
const parse = require('issue-parser')('gitlab');
const result = parse('Implement group/project#31; review group/project!9; /cc @lee');
console.log(result.actions.close, result.refs);The GitLab preset uses `#` for issues and `!` for merge requests. Parsed identifiers are strings.
Extract Bitbucket references parse-bitbucket-message
const parse = require('issue-parser')('bitbucket');
const result = parse('Fixing team/repo#4 and notify @owner');Provider presets contain different action vocabularies. Do not assume GitHub duplicate phrases are active in the Bitbucket parser.
Copy allRefs before JSON serialization serialize-all-references
const parse = require('issue-parser')('github');
const result = parse('Fix #2 and compare #3');
const payload = {...result, allRefs: result.allRefs};
console.log(JSON.stringify(payload));In version 7, `allRefs` is a non-enumerable getter. Spread and JSON serialization omit it unless you copy the value explicitly.
Read full GitHub URLs parse-full-issue-urls
const parse = require('issue-parser')('github');
const result = parse([
'See https://github.com/acme/widget/pull/17',
'Fix https://github.com/acme/widget/issues/22',
].join('\n'));A full URL supplies the repository slug and number. The parser still makes no HTTP request and does not confirm the target.
Extend a preset with relationship actions add-action-groups
const issueParser = require('issue-parser');
const parse = issueParser('github', {
actions: {
parent: ['parent of'],
related: ['related to'],
},
});
const result = parse('Parent of #3; related to #9; fix #12');New action keys join the preset. Reusing `close` replaces that keyword array, so repeat any built-in words you want to retain.
Parse an internal issue marker define-custom-prefix
const parse = require('issue-parser')({
actions: {complete: ['complete'], blocked: ['blocked by']},
issuePrefixes: ['BUG-'],
mentionsPrefixes: ['@'],
});
const result = parse('Complete BUG-41, blocked by BUG-39');Custom issue identifiers still end in digits. The `issue` property is returned as a string, and the marker appears in `prefix`.
Add a private forge host support-self-hosted-forge
const issueParser = require('issue-parser');
const parse = issueParser('github', {
hosts: ['https://git.example.com'],
issueURLSegments: ['issues', 'pull'],
});
const result = parse('Fix https://git.example.com/acme/api/issues/7');A `hosts` override replaces the preset list. Include the public host too if input can contain both public and private URLs.
Accept punctuation after an action allow-action-delimiters
const issueParser = require('issue-parser');
const parse = issueParser('github', {delimiters: [':', '-']});
const result = parse('Fix: #1 and resolves - #2');Spaces and tabs are accepted automatically. Configured delimiter strings are escaped before the matcher is compiled.
Use a tilde mention marker replace-mention-prefix
const issueParser = require('issue-parser');
const parse = issueParser('github', {mentionsPrefixes: ['~']});
console.log(parse('Ask ~alex instead of @sam').mentions);The override replaces `@`; it does not append `~` to the preset. List both markers if both should match.
Skip common fenced and inline code ignore-markdown-code
const parse = require('issue-parser')('github');
const text = ['Fix #1', '`Fix #2`', '```js', '// Fix #3', '```'].join('\n');
console.log(parse(text).allRefs.map(ref => ref.issue));
// ['1']Exclusion is regex-based, not a Markdown syntax tree. Test unusual or malformed fences from your editor before treating the result as authoritative.
Parse a commit batch with one factory result reuse-parser
const parse = require('issue-parser')('github');
const parsed = commits.map(commit => ({
hash: commit.hash,
references: [...parse(commit.message).allRefs],
}));The factory compiles configuration-specific regular expressions. Reuse its function instead of rebuilding it for every message.
Alternatives
| Package | Registry | Pick it when |
|---|---|---|
| issue-regex | npm | Choose it when a single GitHub-style reference regex is enough and you do not need actions or mentions. |
| conventional-commits-parser | npm | Choose it when references belong inside a full Conventional Commits parse with headers, scopes, notes, and footers. |
| git-url-parse | npm | Choose it to extract host, owner, repository, and ref from Git remote URLs rather than prose. |
| @github/issue-parser | npm | Choose it to decode submitted GitHub issue-form Markdown into named field values. |
More utils guides
lru-cache · ajv · type-fest · p-limit · find-up · js-yaml · the whole shelf →
How this guide is made: grounded in the library's documentation, release notes, changelog, and issue history, on a fixed rubric — not a hands-on install of every release. The 50 most-downloaded entries are additionally install-verified in clean containers. Corrections: contact the desk.