DevTools/Features/SourceMap

Please use "Edit with form" above to edit this page.

Status

SourceMap
Stage	Planning
Status	In progress
Release target	`
Health	OK
Status note	`

{{#set:Feature name=SourceMap

|Feature stage=Planning |Feature status=In progress |Feature version=` |Feature health=OK |Feature status note=` }}

Team

Product manager	Kevin Dangoor
Directly Responsible Individual	Kevin Dangoor
Lead engineer	Nick Fitzgerald
Security lead	`
Privacy lead	`
Localization lead	`
Accessibility lead	`
QA lead	`
UX lead	`
Product marketing lead	`
Operations lead	`
Additional members	`

{{#set:Feature product manager=Kevin Dangoor

|Feature feature manager=Kevin Dangoor |Feature lead engineer=Nick Fitzgerald |Feature security lead=` |Feature privacy lead=` |Feature localization lead=` |Feature accessibility lead=` |Feature qa lead=` |Feature ux lead=` |Feature product marketing lead=` |Feature operations lead=` |Feature additional members=` }}

Open issues/risks

A security review should be conducted before we have too much technical debt.

Now that there is an evolving spec for the source map file format, the first step is to write the core libraries to generate and consume/query source maps. These core libraries should be very general and reusable, so the plan right is to use the Common JS AMD format.

Next, a patch should be written for the web console to support mapping logged messages and uncaught errors back to their original source. It is still undecided, from an API/architecure point of view, who will check whether a given script has an associated source map, and how they will notify the potential consumer of the source map that it exists or mark the script as having an associated source map. This issue will rise to the surface at this stage.

As time progresses, and dependencies are met (or not), the order of the following still needs to be decided:

• Integration with the debugger.

• Integration with UglifyJS.

• Integration with CoffeeScript.

Stage 1: Definition

1. Feature overview

Nearly every web developer starts with JavaScript in one form during development and then produces JavaScript in another form for production use. Most often, this is a case of joining files together and minifying the output to reduce the number of requests the browser needs to make and how much data the browser needs to transfer. Another example of JavaScript starting in one form and ending up in the final form used by the browser is in PHP scripts which will sometimes generate bits of JavaScript as they generate their pages.

When JavaScript gets an error, being able to help the web developer out by showing them where the error occurred in the original source file (PHP script or unminified, still-separate JavaScript for example) would save the developer time every single time they hit an error. The Web Console log messages also include links to the line that generated the log message, so these messages could link back to the original source lines as well.

For a long time, there have been languages that have compiled to JavaScript, and recently there has been a surge in support for these languages led by CoffeeScript. CoffeeScript may seem like a fringe language today, but it will soon be shipping with Ruby on Rails 3.1, giving thousands of programmers a reason for developing with something other than JS.

When developing an application in CoffeeScript, any time an error is hit the browser tells the user the location of the problem in the JavaScript file, not the source file that the user is working with. One new language even went so far as to ensure that the lines numbers in the generated JS match up with the lines numbers in the original source file, which is an unfortunate thing to optimize for.

The solution to this problem is a mapping from the generated JS to the original source files.

2. Users & use cases

Moderately sophisticated JavaScript developers.

3. Dependencies

`

4. Requirements

• SpiderMonkey needs to output column in addition to source/line.
• When a sourcemap is available, error messages in console will link to the original source, not the generated JS
• Likewise, console log output will link back to the original source
• Patches for CoffeeScript and UglifyJS will be used to produce examples
• A specification for generated scripts to refer to their mappings and a mapping format

Link title

Non-goals

• Ideally, the source mapping file will also work for mapping LESS and similar to CSS. However, implementing the user interface for style source mapping is out of scope for this particular feature.

Stage 2: Design

5. Functional specification

`

6. User experience design

`

Stage 3: Planning

7. Implementation plan

`

8. Reviews

Security review

`

Privacy review

`

Localization review

`

Accessibility

`

Quality Assurance review

`

Operations review

`

Stage 4: Development

9. Implementation

TBD (status page link)

• bug 669999 - Add a library for parsing and consuming source map files to Firefox

• bug 670002 - Use source maps in the web console

• Bug 568142: Expand source notes to carry column information - Bug to add line/col information to be available to debuggers.

• Bug 618650: map JS source coordinates to source language that was translated to JS

• Bug 626932: Shrink JSParseNode - Would add character-offset to SpiderMonkey (as opposed to line/col).
  • Has an incomplete patch by njn. Doesn't compile.

• David Flanagan has been working on adding "//@line ###" style comment support to SpiderMonkey which is being tracked by this bug.

The source map file format spec originally proposed by Google. I (fitzgen) have edit permissions and am working with them on making something we can all agree upon.

This feature is related to the Script Origin Tracking proposal, because the mapping should be able to accommodate the many ways in which JavaScript can come into existence on a page.

• Brendan and Jim Blandy have suggested that using a separate mapping file will work better than including the mapping in the generated source.

• A bug with a patch was opened for WebKit but closed INVALID.
  • Webkit has another bug open for this feature.
  • A new bug with a patch was opened.

Stage 5: Release

10. Landing criteria

` {{#set:Feature open issues and risks=A security review should be conducted before we have too much technical debt.

Now that there is an evolving spec for the source map file format, the first step is to write the core libraries to generate and consume/query source maps. These core libraries should be very general and reusable, so the plan right is to use the Common JS AMD format.

Next, a patch should be written for the web console to support mapping logged messages and uncaught errors back to their original source. It is still undecided, from an API/architecure point of view, who will check whether a given script has an associated source map, and how they will notify the potential consumer of the source map that it exists or mark the script as having an associated source map. This issue will rise to the surface at this stage.

As time progresses, and dependencies are met (or not), the order of the following still needs to be decided:

• Integration with the debugger.

• Integration with UglifyJS.

• Integration with CoffeeScript.

|Feature overview=Nearly every web developer starts with JavaScript in one form during development and then produces JavaScript in another form for production use. Most often, this is a case of joining files together and minifying the output to reduce the number of requests the browser needs to make and how much data the browser needs to transfer. Another example of JavaScript starting in one form and ending up in the final form used by the browser is in PHP scripts which will sometimes generate bits of JavaScript as they generate their pages.

When JavaScript gets an error, being able to help the web developer out by showing them where the error occurred in the original source file (PHP script or unminified, still-separate JavaScript for example) would save the developer time every single time they hit an error. The Web Console log messages also include links to the line that generated the log message, so these messages could link back to the original source lines as well.

For a long time, there have been languages that have compiled to JavaScript, and recently there has been a surge in support for these languages led by CoffeeScript. CoffeeScript may seem like a fringe language today, but it will soon be shipping with Ruby on Rails 3.1, giving thousands of programmers a reason for developing with something other than JS.

When developing an application in CoffeeScript, any time an error is hit the browser tells the user the location of the problem in the JavaScript file, not the source file that the user is working with. One new language even went so far as to ensure that the lines numbers in the generated JS match up with the lines numbers in the original source file, which is an unfortunate thing to optimize for.

The solution to this problem is a mapping from the generated JS to the original source files. |Feature users and use cases=Moderately sophisticated JavaScript developers. |Feature dependencies=` |Feature requirements=* SpiderMonkey needs to output column in addition to source/line.

• When a sourcemap is available, error messages in console will link to the original source, not the generated JS
• Likewise, console log output will link back to the original source
• Patches for CoffeeScript and UglifyJS will be used to produce examples
• A specification for generated scripts to refer to their mappings and a mapping format

Link title |Feature non-goals=* Ideally, the source mapping file will also work for mapping LESS and similar to CSS. However, implementing the user interface for style source mapping is out of scope for this particular feature. |Feature functional spec=` |Feature ux design=` |Feature implementation plan=` |Feature security review=` |Feature privacy review=` |Feature localization review=` |Feature accessibility review=` |Feature qa review=` |Feature operations review=` |Feature implementation notes=TBD (status page link)

• bug 669999 - Add a library for parsing and consuming source map files to Firefox

• bug 670002 - Use source maps in the web console

• Bug 568142: Expand source notes to carry column information - Bug to add line/col information to be available to debuggers.

• Bug 618650: map JS source coordinates to source language that was translated to JS

• Bug 626932: Shrink JSParseNode - Would add character-offset to SpiderMonkey (as opposed to line/col).
  • Has an incomplete patch by njn. Doesn't compile.

• David Flanagan has been working on adding "//@line ###" style comment support to SpiderMonkey which is being tracked by this bug.

The source map file format spec originally proposed by Google. I (fitzgen) have edit permissions and am working with them on making something we can all agree upon.

This feature is related to the Script Origin Tracking proposal, because the mapping should be able to accommodate the many ways in which JavaScript can come into existence on a page.

• Brendan and Jim Blandy have suggested that using a separate mapping file will work better than including the mapping in the generated source.

• A bug with a patch was opened for WebKit but closed INVALID.
  • Webkit has another bug open for this feature.
  • A new bug with a patch was opened.

|Feature landing criteria=` }}

Feature details

Priority	P2
Rank	999
Theme / Goal	`
Roadmap	Developer Tools
Secondary roadmap	`
Feature list	Desktop
Project	`
Engineering team	DevTools

{{#set:Feature priority=P2

|Feature rank=999 |Feature theme=` |Feature roadmap=Developer Tools |Feature secondary roadmap=` |Feature list=Desktop |Feature project=` |Feature engineering team=DevTools }}

Team status notes

	status	notes
Products	`	`
Engineering	`	`
Security	sec-review-needed	`
Privacy	`	`
Localization	`	`
Accessibility	`	`
Quality assurance	`	`
User experience	`	`
Product marketing	`	`
Operations	`	`

{{#set:Feature products status=`

|Feature products notes=` |Feature engineering status=` |Feature engineering notes=` |Feature security status=sec-review-needed |Feature security health=` |Feature security notes=` |Feature privacy status=` |Feature privacy notes=` |Feature localization status=` |Feature localization notes=` |Feature accessibility status=` |Feature accessibility notes=` |Feature qa status=` |Feature qa notes=` |Feature ux status=` |Feature ux notes=` |Feature product marketing status=` |Feature product marketing notes=` |Feature operations status=` |Feature operations notes=` }}