JS::SourceMap - Parse and use JS source maps in Perl


  use JS::SourceMap qw/load loads discover/;

  # parse a file into a sourcemap
  $map = load($filename);

  # parse a string into a sourcemap
  $map = loads($string);

  # find the URL for a sourcemap from some JS code:
  $url = discover($web_goo);


Current web development techniques like minification can make debugging deployed JS code a pain. Source maps are a compact representation of the data necessary to turn a filename/line/column in a JS runtime error thrown e.g. in your browser into the real filename/line/column in the source code where the error occurred.

This is a set of Perl modules that allow you to decode and use JS source maps. A typical use case for this module is a server-side component in Perl that receives JS runtime error information somehow from a web application's JS front end. You usually have the source map available on the server already but there is a `discover` function in `JS::SourceMap` that will search JS code for a pointer to its source map as per convention. You'll have to fetch the URL that `discover` finds yourself, though.

We have adapted much of this Perl implementation from the Python implementation at, which is BSD-licensed. Our API is very similar to that Python module's.

  • load $stream_or_filename [, @options ]

    Our first argument can either be a filename or an open file handle of some kind; in the former case the file is opened, read and closed by us, in latter it is only read. The contents are passed to loads, along with any options.

  • loads $string [, @options ]

    Decodes a sourcemap passed as a string. Returns a JS::SourceMap::Index instance or throws an error.

    If any @options are given they are passed to the JS::SourceMap::Decoder constructor.

  • discover $string

    Examine the contents of a file of JS code for the marker that points to its source map. If found we return the URL to the source map. If not we return undef. We search the five first and five last lines in the source code we're given, since the token we're looking for is supposed to be in there somewhere.




attila <>

The most recent sourcecode can be found at the github repository:


ISC/BSD c.f. LICENSE in the source distribution.