esbuild-peggy

An esbuild plugin for bundling Peggy.js / PEG.js parsers directly into JavaScript and TypeScript source files.

Available as esbuild-peggy on npm.

Quick Start

1. Add esbuild-peggy as a dependency - typically a devDependency - within your package.json; e.g.:

   $ npm install --save-dev esbuild-peggy

   or

   // FILE: package.json
   {
     "devDependencies": {
       "esbuild-peggy": "latest"
     }
   }

2. Configure esbuild-peggy as a plugin within your esbuild build script. E.g.:

   // FILE: esbuild.js
   import { build } from "esbuild";
   import { peggyPlugin } from "esbuild-peggy";
   
   build({
     // ...
     plugins: [ peggyPlugin() ],
     loader: {
       ".pegjs": "js",
       ".peggy": "js"
     }
   });

   Note that you may optionally pass arbitrary Peggy.js ParserOptions (as a map) in the first parameter to the peggyPlugin() function.

   Note also that esbuild-peggy is fully compatible with esbuild's "watch mode", and will automatically rebuild the generated parser implementation (and subsequently any appropriately defined dependencies) whenever the underlying .pegjs/.peggy source is modified (in that context).

3. Create your grammar file with a .pegjs or .peggy extension; e.g.:

   // FILE: grammar.pegjs
   START = Number
   Number = "-"? [0-9]+ ("."[0-9]+)? { return parseFloat(text()); }

4. Import the grammar file directly in your JavaScript or TypeScript file; e.g.:

   // FILE: index.ts
   import parser from "./grammar.pegjs";
   console.log(parser.parse("-3.14"));

See the examples directory within this repository for a complete demonstration of using esbuild-peggy with the esbuild bundler in JavaScript and TypeScript.

Licensing

The esbuild-peggy library and related documentation are made available under an MIT License. For details, please see the LICENSE.txt file in the root directory of the repository.

Versioning

This module follows the semver version numbering strategy.

About

About esbuild

esbuild is a tightly-designed, blazingly-fast, extraordinarily-common but oddly under-appreciated (though this seems to be changing) build tool/bundler framework implemented in golang with JavaScript/TypeScript bindings.

In case the npm-compare.com link above happens to go bad in the future note that as of this writing (mid-May 2025) that chart currently shows:

• esbuild with ~60 million weekly downloads from npm
• rollup with ~40 million weekly downloads.
• webpack with ~32 million weekly downloads.
• vite with ~28 million weekly downloads.

but note that vite currently embeds both rollup and esbuild, so that alone probably accounts for roughly half of the 60 million esbuild installs and 3/4ths of the 40 million rollup installs.

About PEG.js/Peggy.js

Peggy is the spiritual successor to PEG.js, a robust but largely stagnant parser generator for the JavaScript stack, both server (node.js, etc) and client (browser).

(PEG.js has not been refreshed for nearly a decade - arguably it doesn't strictly need to be: AST-style grammars have been a mature, well-established technology for easily half a century. But PEG.js still accrues more than half a million installs off of npmjs.org per week.)

About esbuild-peggy

esbuild-peggy is a straightforward esbuild plugin, implemented in TypeScript, that enables the (ESM) import or (CJS) require of .pegjs or .peggy grammar files directly within JavaScript or TypeScript source files (when bundled with esbuild).

For a complete working example of using esbuild-peggy in JavaScript or TypeScript see examples directory within the main source repository.

Contributions Welcome

This plugin was initially developed to "scratch my own itch" (address a specific need I organically encountered), but (a) seems to be moderately robust already and (b) could be generalized to address additional needs and use-cases as they are identified.

Should you have any questions, encounter any issues, or have any feature requests/bug-fixes/enhancements you'd like to propose, please feel free submit them as issues or pull requests on the GitHub platform (or other channels as appropriate).

See HACKING.md for more information about building this module from source and other development related topics.