{"id":11540,"library":"peggy","title":"Peggy Parser Generator","description":"Peggy is a robust, open-source parser generator for JavaScript that serves as the successor to the popular PEG.js project. It enables developers to define grammars using a simple and expressive syntax based on parsing expression grammar (PEG) formalism, which is more powerful than traditional LL(k) and LR(k) parsers. Peggy integrates both lexical and syntactical analysis and produces fast parsers with excellent error reporting capabilities. The current stable version is 5.1.0, with regular patch and minor releases, and major versions released less frequently. Key differentiators include its superior error reporting, integration of lexical and syntactical analysis, and being usable across various environments: browsers (via an online tool), command line, and as a JavaScript API. It also provides source map support and ships with TypeScript definitions, making it well-suited for modern JavaScript and TypeScript development workflows. It requires Node.js version 20 or higher.","status":"active","version":"5.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/peggyjs/peggy","tags":["javascript","grammar","parser generator","PEG","PEG.js","typescript"],"install":[{"cmd":"npm install peggy","lang":"bash","label":"npm"},{"cmd":"yarn add peggy","lang":"bash","label":"yarn"},{"cmd":"pnpm add peggy","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary function for compiling a PEG grammar string into a parser. CommonJS `require` is still supported but ESM `import` is preferred for modern Node.js environments.","wrong":"const generate = require('peggy').generate;","symbol":"generate","correct":"import { generate } from 'peggy';"},{"note":"The custom error class thrown by generated parsers when input does not match the grammar. While exported, it's typically caught from the parser's `parse` method.","wrong":"import { PeggySyntaxError } from 'peggy';","symbol":"SyntaxError","correct":"import { SyntaxError } from 'peggy';"},{"note":"For programmatic access to Peggy's command-line interface functionalities, useful for custom build tools. Most users will invoke `peggy` directly from the command line.","symbol":"cli","correct":"import { cli } from 'peggy';"}],"quickstart":{"code":"import { generate } from 'peggy';\n\nconst grammar = `\n  start = expression\n  expression = term (('+' / '-') term)*\n  term = factor (('*' / '/') factor)*\n  factor = number / '(' expression ')'\n  number 'number' = [0-9]+ { return parseInt(text()); }\n`;\n\ntry {\n  const parser = generate(grammar, { output: 'parser', format: 'es' });\n\n  const result = parser.parse('1 + 2 * (3 - 4)');\n  console.log('Parse successful:', result);\n\n  // Example of a syntax error\n  parser.parse('1 +');\n} catch (e: any) {\n  if (e.name === 'SyntaxError') {\n    console.error(`Syntax Error at line ${e.location.start.line}, column ${e.location.start.column}: ${e.message}`);\n  } else {\n    console.error('An unexpected error occurred:', e);\n  }\n}","lang":"typescript","description":"This quickstart demonstrates how to define a simple arithmetic grammar, generate a parser using `peggy.generate`, and then use the generated parser to process an input string. It also illustrates how to catch and handle `SyntaxError` instances thrown by the parser."},"warnings":[{"fix":"Transpile your generated parser code using Babel or a similar tool if targeting environments older than ES2020, or update your runtime to Node.js >=20.","message":"Peggy v5.0.0 and later no longer supports ES5 for generated parser code. Generated code now requires ES2020 features (e.g., `const`, `let`). If you need to support earlier runtimes, you must use a transpiler like Babel.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Replace all instances of `pegjs` with `peggy` in your code and build scripts.","message":"When migrating from PEG.js, all `require('pegjs')` or `import ... from 'pegjs'` statements must be updated to `require('peggy')` or `import ... from 'peggy'`. Similarly, any command-line usage of `pegjs` should be replaced with `peggy`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Review your build pipeline and any polyfill assumptions if you encounter unexpected runtime issues after upgrading to v5.0.6 or later, especially if you use Peggy programmatically.","message":"As of v5.0.6, Peggy switched from `tsc` and `rollup` to `tsup` for its own code generation. This change might be user-visible as `tsup` injects different polyfills, potentially affecting the runtime behavior of Peggy itself if you rely on specific polyfills in a custom build pipeline.","severity":"breaking","affected_versions":">=5.0.6"},{"fix":"Ensure your development and production environments are running Node.js version 20 or newer.","message":"Peggy requires Node.js version 20 or higher. Running Peggy with older Node.js versions will result in errors.","severity":"gotcha","affected_versions":"<5.1.0"},{"fix":"Upgrade to the latest `5.x.x` patch release to benefit from TypeScript definition fixes, such as `5.1.0` or newer.","message":"Previous versions (e.g., 5.0.1, 5.0.2) had TypeScript definition issues related to `SyntaxError` constructor and return types. While fixed in later patches, if you're stuck on an older 5.x patch, you might encounter type-checking problems.","severity":"gotcha","affected_versions":"5.0.0 - 5.0.2"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Globally replace `pegjs` with `peggy` in your project's source code and configuration files.","cause":"You have migrated from PEG.js but have not updated all `require` or `import` statements to reference `peggy` instead.","error":"Error: Cannot find module 'pegjs'"},{"fix":"For Peggy imports, use `import ... from 'peggy';`. For generated parsers in v5+, ensure your project is configured for ESM or transpile the output if targeting an older CJS environment or browser.","cause":"You are attempting to use CommonJS `require()` syntax for Peggy imports within an ES Module (ESM) context in Node.js, or your generated parser code (pre-v5) is being run in an ESM context without proper transpilation.","error":"ReferenceError: require is not defined"},{"fix":"Update Peggy to the latest `5.x.x` patch version (e.g., 5.1.0) to get the corrected TypeScript definitions.","cause":"This specific TypeScript error indicates an incompatibility with older `peggy.d.ts` definitions (e.g., from v5.0.1 or v5.0.2) when using TypeScript to compile code that imports `SyntaxError` from 'peggy'.","error":"SyntaxError: 'SyntaxError' constructor should not have a return type."},{"fix":"Ensure `text()` is called within a rule's action block and that the rule has successfully matched some input. Verify that the `text()` function is correctly defined and accessible in the context of your generated parser's actions.","cause":"This often occurs within semantic actions (`{ return text(); }`) in your grammar when `text()` is called outside a rule that has matched any input or if the `text()` function isn't available in the current scope for some reason.","error":"TypeError: Cannot read properties of undefined (reading 'text')"}],"ecosystem":"npm"}