{"id":13225,"library":"gerber-parser","title":"Streaming Gerber/Drill File Parser","description":"gerber-parser is a JavaScript/TypeScript library that provides a streaming parser for Gerber (RS-274X) and NC drill files, commonly used for Printed Circuit Board (PCB) manufacturing. It functions as a Node.js transform stream, taking a text stream of a Gerber file and emitting structured JavaScript objects representing the file's contents, which can then be consumed by PCB visualization or plotting tools. The library is part of the Tracespace collection of open-source PCB visualization tools. The current stable version is 4.2.7. While a precise release cadence isn't explicitly stated, the project maintains an active development cycle within the Tracespace ecosystem, with major versions introducing breaking changes to improve parsing accuracy and specification compliance. Its key differentiator is its streaming architecture, allowing efficient processing of large Gerber files without loading the entire content into memory, and its explicit focus on the Gerber X2 standard for enhanced data integrity.","status":"active","version":"4.2.7","language":"javascript","source_language":"en","source_url":"https://github.com/tracespace/tracespace","tags":["javascript","PCB","Gerber","drill","circuit","board","transform","stream","hardware","typescript"],"install":[{"cmd":"npm install gerber-parser","lang":"bash","label":"npm"},{"cmd":"yarn add gerber-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add gerber-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary parser function is a default export, instantiating the transform stream.","wrong":"import { gerberParser } from 'gerber-parser';\nconst gerberParser = require('gerber-parser').default;","symbol":"gerberParser","correct":"import gerberParser from 'gerber-parser';"},{"note":"For Node.js environments still using CommonJS, `require` is the correct method, as the package exports the function directly as the module.exports.","wrong":"import gerberParser from 'gerber-parser';","symbol":"gerberParser (CommonJS)","correct":"const gerberParser = require('gerber-parser');"},{"note":"When using TypeScript, import the `Parser` type for type-hinting the stream instance.","symbol":"Parser (Type)","correct":"import type { Parser } from 'gerber-parser';"}],"quickstart":{"code":"import fs from 'fs';\nimport gerberParser from 'gerber-parser';\nimport type { Parser } from 'gerber-parser';\n\n// Create a dummy Gerber file for demonstration\nconst dummyGerberContent = `\n%FSLAX26Y26*%\n%MOIN*%\n%LPD*%\nG01*%\nD10*X1000000Y1000000*D03*%\nM02*%\n`;\n\nconst dummyGerberPath = 'dummy_file.gbr';\nfs.writeFileSync(dummyGerberPath, dummyGerberContent);\n\nconst parser: Parser = gerberParser();\n\nparser.on('warning', (w) => {\n  console.warn(`Warning at line ${w.line}: ${w.message}`);\n});\n\nparser.on('data', (obj) => {\n  // Each 'data' event emits a parsed Gerber object\n  console.log(JSON.stringify(obj, null, 2));\n});\n\nparser.on('end', () => {\n  console.log('Gerber file parsing complete.');\n  fs.unlinkSync(dummyGerberPath); // Clean up dummy file\n});\n\nparser.on('error', (err) => {\n  console.error('Error during parsing:', err.message);\n  fs.unlinkSync(dummyGerberPath); // Clean up dummy file on error\n});\n\n// Pipe the stream into the parser\nfs.createReadStream(dummyGerberPath)\n  .pipe(parser);\n","lang":"typescript","description":"Demonstrates how to create a `gerber-parser` instance, pipe a Gerber file stream into it, and handle data, warnings, and completion events."},"warnings":[{"fix":"Ensure all Gerber files passed to the parser conform to the Gerber X2 standard. If processing older Gerber files is necessary, consult the API documentation for options to disable this strict validation, though it's not recommended for production.","message":"Version 4.0.0 of `gerber-parser` explicitly accepts only Gerber X2 (or drill) files by default. Passing a non-X2 Gerber file will now throw an error.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"For modern browser applications, bundle `gerber-parser` using a module bundler. For simple script tag inclusion, ensure you use the `dist/gerber-parser.min.js` file and access the global `gerberParser` variable.","message":"Browser usage requires bundling. If using in a browser environment without a build tool (like Webpack or Browserify), you must use the pre-built `gerber-parser.min.js` script and access the library via the global `gerberParser` variable.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always attach an `on('warning', handler)` listener to the parser stream to log or handle these warnings. This helps identify and address potential issues in the Gerber input files.","message":"The parser emits `warning` events for non-critical issues or deviations from best practices in the Gerber file. These are not errors but can indicate potential problems or non-standard syntax.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Convert the Gerber file to the X2 standard or ensure it is a valid X2 file. Alternatively, if explicitly needed and understood, consult the `gerber-parser` API documentation for options to relax X2 strictness (though generally not recommended).","cause":"Attempting to parse an older Gerber RS-274D file or a malformed Gerber file with `gerber-parser` v4+ without disabling strict X2 validation.","error":"Error: Not a Gerber X2 file"},{"fix":"For ES Modules, use `import gerberParser from 'gerber-parser';`. For CommonJS, use `const gerberParser = require('gerber-parser');`. The module exports a function that you call directly to get a stream instance (e.g., `const parser = gerberParser();`).","cause":"Incorrectly importing or requiring the `gerber-parser` module, attempting to `new` the result, or misusing CommonJS `require` with an ES module setup.","error":"TypeError: gerberParser is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}