Add source maps to compiled JavaScript and CSS

[colinrotherham]

This PR adds source maps to our compiled code

For example:

govuk-frontend-4.4.0.min.js

//# sourceMappingURL=govuk-frontend-4.4.0.min.js.map

govuk-frontend-4.4.0.min.css

/*# sourceMappingURL=govuk-frontend-4.4.0.min.css.map */

When browser developer tools are open the associated source map files are downloaded

JavaScript source maps

See log messages and stack traces mapped to the *.mjs source code (with line numbers)

Click through to the original source via the browser

CSS source maps

See styles mapped to the Sass *.scss source code (with line numbers)

[romaricpascal]

Sourcemaps are great and the PR looks technically neat for adding them in. Just looking into what will consume them so we're clear on who will benefit and who will not (depending on how code is loaded) and maybe check if some guidance will need updating. More news on this space in a bit 😄

[romaricpascal]

Who benefits from sourcemaps?

TL;DR:

• People using dist will benefit from a guidance update to copy the files alongside the .min.{js,css} files.
• Services statically serving node_modules/govuk-frontend[/govuk] will serve the sourcemaps automatically.
• Prototype Kit and services statically serving individual files (like all.js) will need to also statically serve the .map file.
• People using bundlers will need to add plugins/loaders to read the sourcemaps, unless they're using Babel or loading our ESM files (which they may well be doing if using Babel anyway).
• Scss builds from source so sourcemaps don't need reading.
• PostCSS will automatically consume sourcemaps.

People loading the files from dist on their page

Instead of looking at a cryptic file when an error occurs in the console, people using the release archive will get more readable code which may help us with support.

For that to work, though, we'll need to update the installation instructions to tell people to not only copy the .js and .css files, but also the sourcemaps.

People using the npm package

Serving files from node_modules with a static middleware

If they serve node_modules/govuk-frontend using something like Express's static, their server will make the sourcemaps available, so happy days.

If they point to individual files (eg. 'node_modules/govuk-frontend/govuk/all.js'), they'll need to also serve the .js.map file as well. For the prototype kit, for example, only the JS file will be served, so browsers won't be able to load the sourcemap.

Same situation would apply as well if people vendor their files in their framework of choice's public folder.

With bundlers

Bundlers outputing sourcemaps will be something developer of the actual project using govuk-frontend will need to enable (for ex. using the devtool option in Webpack or the sourcemap outputOption in Rollup). Up to them.

Outputing sourcemaps is only part of the job, though. By default bundlers don't consume sourcemaps from libraries, only create them from the modules they load. To consume them, people will need to add a plugin:

• source-map-loader for Webpack
• rollup-plugin-sourcemaps for Rollup

If Babel is involved for compiling the code during bundling, it is configured by default to consume sourcemaps

Note that if people load our ESM files, they'll technically be loading the sources, so won't need to consume sourcemaps.

If it's TypeScript consuming govuk-frontend, there's no support for input source maps yet. It follows Node's module resolution so I suspect it'll load ESM files directly.

With asset pipelines

For example Sprocket, used by Rails and Middleman (tech-docs-gem, for ex). Looks like support was added in v4, though unclear if it'd serve the sourcemaps alongside "bundling" the JS files.

Scss

Sass can output sourcemaps, and the projects would be building from our untouched Scss files so get pointed to the right place should they enable sourcemaps output. I think people could enable sourceMapIncludeSources if they were consuming our built all.css with Sass.

CSS

If people's project consume our CSS files, instead of SCSS files, through PostCSS for example. The later seems to automatically consume source maps

[colinrotherham]

@romaricpascal Rebased and ready for review again 👍

[romaricpascal]

Looking neat! 🙌🏻