source-map-loader
Extracts source maps from existing source files (from their sourceMappingURL ).
Getting Started
To begin, you’ll need to install source-map-loader :
Then add the plugin to your webpack config. For example:
file.js
webpack.config.js
The source-map-loader extracts existing source maps from all JavaScript entries. This includes both inline source maps as well as those linked via URL. All source map data is passed to webpack for processing as per a chosen source map style specified by the devtool option in webpack.config.js. This loader is especially useful when using 3rd-party libraries having their own source maps. If not extracted and processed into the source map of the webpack bundle, browsers may misinterpret source map data. source-map-loader allows webpack to maintain source map data continuity across libraries so ease of debugging is preserved. The source-map-loader will extract from any JavaScript file, including those in the node_modules directory. Be mindful in setting include and exclude rule conditions to maximize bundling performance.
And run webpack via your preferred method.
Options
| Name | Type | Default | Description |
|---|---|---|---|
| filterSourceMappingUrl | undefined | Allows to control SourceMappingURL behaviour |
filterSourceMappingUrl
Type: Function Default: undefined
Allows you to specify the behavior of the loader for SourceMappingURL comment.
The function must return one of the values:
webpack.config.js
Examples
Ignoring Warnings
To ignore warnings, you can use the following configuration:
webpack.config.js
More information about the ignoreWarnings option can be found here
Contributing
Please take a moment to read our contributing guidelines if you haven’t yet done so.
Source Maps: быстро и понятно
Механизм Source Maps используется для отображения исходных текстов программы на сгенерированные на их основе скрипты. Несмотря на то, что тема не нова и по ней уже написан ряд статей (например эта, эта и эта) некоторые аспекты все же нуждаются в прояснении. Представляемая статья представляет собой попытку упорядочить и систематизировать все, что известно по данной теме в краткой и доступной форме.
В статье Source Maps рассматриваются применительно к клиентской разработке в среде популярных браузеров (на примере, DevTools Google Chrome), хотя область их применения не привязана к какому-либо конкретному языку или среде. Главным источникам по Source Maps является, конечно, стандарт, хотя он до сих пор не принят (статус — proposal), но, тем не менее, широко поддерживается браузерами.
Работа над Source Maps была начата в конце нулевых, первая версия была создана для плагина Firebug Closure Inspector. Вторая версия вышла в 2010 и содержала изменения в части сокращения размера map-файла. Третья версия разработана в рамках сотрудничества Google и Mozilla и предложена в 2011 (последняя редакция в 2013).
В настоящее время в среде клиентской разработки сложилась ситуация, когда исходный код почти никогда не интегрируется на веб-страницу непосредственно, но проходит перед этим различные стадии обработки: минификацию, оптимизацию, конкатенацию, более того, сам исходный код может быть написан на языках требующих транспиляции. В таком случае, для целей отладки необходим механизм позволяющий наблюдать в дебаггере именно исходный, человекочитаемый код.
Для работы Source Maps необходимы следующие файлы:
Map-файл
Вся работа Source Maps основана на map-файле, который может выглядеть, например, так:
Обычно, имя map-файла складывается из имени скрипта, к которому он относится, с добавлением расширения «.map», bundle.js — bundle.js.map. Это обычный json-файл со следующими полями:
Загрузка Source Maps
Для того, чтобы браузер загрузил map-файл может быть использован один из следующих способов:
Таким образом, загрузив map-файл браузер подтянет и исходники из поля «sources» и с помощью данных в поле «mappings» отобразит их на сгенерированный скрипт. Во вкладке Sources DevTools можно будет найти оба варианта.
Для указания пути может использоваться пседопротокол file://. Также, в может быть включено все содержимое map-файла в кодировке Base64. В терминологии Webpack подобные Source Maps названы inline source maps.
Self-contained map-файлы
Код файлов-исходников можно включить непосредственно в map-файл в поле «sourcesContent», при наличии этого поля необходимость в их отдельной загрузке отпадает. В этом случае названия файлов в «sources» не отражают их реального адреса и могут быть совершенно произвольными. Именно поэтому, вы можете видеть во вкладке Sources DevTools такие странные «протоколы»: webpack://, ng:// и т.д
Mappings
Сущность механизма отображения состоит в том, что координаты (строка/столбец) имен переменных и функций в сгенерированном файле отображаются на координаты в соотвествующем файле исходного кода. Для работы механизма отображения необходима следующая информация:
(#1) номер строки в сгенерированном файле;
(#2) номер столбца в сгенерированном файле;
(#3) индекс исходника в «sources»;
(#4) номер строки исходника;
(#5) номер столбца исходника;
Все эти данные находятся в поле «mappings», значение которого — длинная строка с особой структурой и значениями закодированными в Base64 VLQ.
Строка разделена точками с запятой (;) на разделы, соответствующие строкам в сгенерированном файле (#1).
Каждый раздел разделен запятыми (,) на сегменты, каждый из которых может содержать 1,4 или 5 значений:
Каждое значение представляет собой число в формате Base64 VLQ. VLQ (Variable-length quantity) представляет собой принцип кодирования сколь угодно большого числа с помощью произвольного числа двоичных блоков фиксированной длины.
В Source Maps используются шестибитные блоки, которые следуют в порядке от младшей части числа к старшей. Старший 6-й бит каждого блока (continuation bit) зарезервирован, если он установлен, то за текущим следует следующий блок относящийся к этому же числу, если сброшен — последовательность завершена.
Поскольку в Source Maps значение должно иметь знак, для него также зарезервирован младший 1-бит (sign bit), но только в первом блоке последовательности. Как и ожидается, установленный sign бит означает отрицательное число.
Таким образом, если число можно закодировать единственным блоком, оно не может быть по модулю больше 15 (11112), так как в первом шестибитном блоке последовательности два бита зарезервированы: continuation бит всегда будет сброшен, sign бит будет установлен в зависимости от знака числа.
Шестибитные блоки VLQ отображаются на кодировку Base64, где каждой шестибитной последовательности соответствует определенный символ ASCII.
Декодируем число mE. Инверсируем порядок, младшая часть последняя — Em. Декодируем числа из Base64: E — 000100, m — 100110. В первом отбрасываем старший continuation бит и два лидирующих нуля — 100. Во втором отбрасываем старший continuation и младший sign биты (sign бит сброшен — число положительное) — 0011. В итоге получаем 100 00112, что соответствует десятичному 67.
Можно и в обратную сторону, закодируем 41. Его двоичный код 1010012, разбиваем на два блока: старшая часть — 10, младшая часть (всегда 4-битная) — 1001. К старшей части добавляем старший continuation бит (сброшен) и три лидирующих нуля — 000010. К младшей части добавляем старший continuation бит (установлен) и младший sign бит (сброшен — число положительное) — 110010. Кодируем числа в Base64: 000010 — C, 110010 — y. Инверсируем порядок и, в итоге, получаем yC.
Для работы с VLQ весьма полезна одноименная библиотека.
Пособие по webpack
Давайте сначала разберемся, зачем нужен вебпак (webpack), и какие проблемы он пытается решить, а потом научимся работать с ним. Webpack позволяет избавиться от bower и gulp/grunt в приложении, и заменить их одним инструментом. Вместо bower’а для установки и управления клиентскими зависимостями, можно использовать стандартный Node Package Manager (npm) для установки и управления всеми фронтэнд-зависимостями. Вебпак также может выполнять большинство задач grunt/gulp’а.
Bower это пакетный менеджер для клиентской части. Его можно использовать для поиска, установки, удаления компонентов на JavaScript, HTML и CSS. GruntJS это JavaScript-утилита командной строки, помогающая разработчикам автоматизировать повторяющиеся задачи. Можно считать его JavaScript-альтернативой Make или Ant. Он занимается задачами вроде минификации, компиляции, юнит-тестирования, линтинга и пр.
Допустим, мы пишем простую страницу профиля пользователя в веб-приложении. Там используется jQuery и библиотеки underscore. Один из способов — включить оба файла в HTML:
Это простой HTML с Бутстрапом. Мы подключили jQuery и underscore с помощью тега script.
Код будет исполнен при вызове скрипта. Если открыть страницу в браузере, то профиль будет выглядеть так.
У этого кода две задачи:
Известно, что смешивать понятия — плохая практика, так что нужно написать отдельные модули, отвечающие за определенные задачи. В файле profile.js мы использовали анонимное замыкание для хранения всего кода. В JavaScript есть способы делать модули получше. Два популярных способа это CommonJS и AMD.
Если хотите узнать о модулях в JavaScript больше, то советую прочитать статью JavaScript Modules: A Beginner’s Guide.
Если загрузить index.html в браузере, то отобразится пустая страница. В консоли (в developer tools) можно обнаружить ошибку:
Проблема в том, что браузеры не понимают модульную систему вроде CommonJS. Нужно предоставить браузеру формат, который он ожидает.
Бандлеры модулей идут на помощь
Что такое вебпак?
webpack берет модули с зависимостями и генерирует статические ресурсы, которые представляют эти модули
Это определение теперь имеет смысл, когда понятна решаемая проблема. Вебпак берет набор ресурсов и трансформирует их в наборы (бандлы).
Трансформацией ресурсов занимаются загрузчики, которые являются сердцем вебпака.
Вебпак в действии
Для установки вебпака нужен node. Можно скачать node с официального сайта.
Теперь можно установить вебпак глобально:
В дополнение, нужно установить вебпак как зависимость.
Давайте создадим бандл.
Теперь страница работает нормально.
Можно сделать так, чтобы вебпак следил за изменениями и генерировал бандл автоматически. Для этого нужно запустить его с таким флагом:
Теперь вебпак не будет завершаться сам. При изменении файлов будет генерироваться новый бандл. Нужно лишь перезагрузить страницу в браузере. Давайте изменим profile.js :
Вебпак сгенерирует source map для файла bundle.js. Source map связывает минимизированный и собранный в один файл код с исходным, несобранным кодом. Для тестирования можно добавить строчку debugger в profile.js
Перезагрузите страницу, и приложение остановится на этой строке.
Добавление CSS
вебпак перезагрузит изменения, и мы увидим сообщение об ошибке в консоли:
Проблема в том, что вебпак не понимает CSS по умолчанию. Нужно установить пару загрузчиков для этого. Вот команда для установки необходимых загрузчиков:
Вебпак использует загрузчики для трансформации текста в нужный формат. Теперь нужно обновить require :
Запустите вебпак снова.
Конфигурация
Чтобы не указывать все опции в командной строке, можно создать конфигурационный файл webpack.config.js в корне приложения:
После изменений конфигурации нужно перезапускать вебпак.
Горячая перезагрузка
На сегодня все. Узнать больше о вебпаке можно из документации.
Русские Блоги
Давайте посмотрим на объяснение этих 7 режимов в документации:
Webpack не только поддерживает эти 7 типов, но также может комбинировать перечисленные выше встроенные скрытые ключевые слова eval, как сказано в документации, вы можете установить опцию souremap на cheap-module-inline-source-map.
Если ваши модули уже содержат SourceMaps, вам нужно использоватьsource-map-loaderПриходите и объединяйтесь для создания новых SourceMaps.
Чем отличаются результаты
Ниже мы перечислим результаты этих 7 режимов после упаковки и компиляции и увидим их сходства и различия:
В режиме eval каждый модуль оборачивается в eval и переносится для выполнения, а в конце добавляются комментарии.
В то же время в выходном каталоге вы найдете дополнительный файл index.js.map.
Мы можем отформатировать этот index.js.map для облегчения нашего наблюдения и сравнения ниже:
Для подробного объяснения того, как информация о строках и столбцах sourceMap сопоставляется с исходным кодом, это не тема, на которой мы сосредоточимся, и она будет опущена.
Заинтересованные студенты могут обратиться к научно-популярной статье Руан Ифэн:Подробная исходная карта JavaScript
По сравнению с исходной картой меньше конечных комментариев,
Но в выходном каталоге не меньше index.js.map
Как вы можете видеть, комментарий в конце, sourceMap, внедряется в пакет в виде DataURL. Поскольку вся информация sourceMap добавляется в пакет, весь файл пакета становится очень большим.
Аналогично eval, но все исходные карты в комментариях преобразуются в DataURL.
Аналогично результатам, генерируемым картой источника. Содержимое index.js в выходном каталоге одинаково.
Но содержимое файла index.js.map, созданного с помощью cheap-source-map, намного меньше, чем index.js.map, сгенерированного source-map. Давайте сравним результаты index.js.map, сгенерированного source-map выше. Обнаружил, что в исходном атрибуте меньшеКолонка информации, Остался только один «webpack:///js/index.js» 。
В дешевом модуле-источнике-карте sourceMap имеет меньше контента,Информация столбца SourceMapСокращенный, вы можете увидеть, что SourceContent ушел.
Какой из них лучше для стольких режимов?
развитиеЭкологическая рекомендация:
cheap-module-eval-source-map
производитьЭкологическая рекомендация:
cheap-module-source-map
Использование дешевого режима может значительно повысить эффективность генерации souremap.В большинстве случаев нам не важна информация о столбце, и даже если исходная карта не имеет столбца, некоторые механизмы браузера (например, v8) также будут предоставлять информацию о столбце.
Использование eval может значительно повысить эффективность непрерывного строительства.Таблица сравнения скорости, приведенная в официальном документе, показывает, что скорость компиляции в режиме eval очень высокая.
Используйте модуль для поддержки предварительно скомпилированных инструментов, таких как babel(Используется как загрузчик в веб-пакете).
Использование режима eval-source-map может уменьшить количество сетевых запросов.В этом режиме DataUrl сам содержит полную информацию об исходной карте, он не должен быть похож на sourceURL. Браузеру необходимо отправить полный запрос для получения файла исходной карты, что немного повысит эффективность. В производственной среде не следует использовать eval, что сделает файл очень большим.
Сравнительная таблица эффективности режима SourceMap
Введение в Webpack
Что такое веб-пакет?
Учитывая большое количество файлов, он создает один файл (или несколько файлов), который запускает ваше приложение.
Он может выполнять множество операций:
Webpack не ограничивается использованием во внешнем интерфейсе, он также полезен при разработке серверной части Node.js.
К предшественникам webpack и до сих пор широко используемым инструментам относятся:
Есть много общего в том, что они могут делать и Webpack, но главное отличие в том, что они известны какисполнители задач, а webpack родился как сборщик модулей.
Это более сфокусированный инструмент: вы указываете точку входа в свое приложение (это может быть даже HTML-файл с тегами скрипта), а webpack анализирует файлы и объединяет все, что вам нужно для запуска приложения, в одном выходном файле JavaScript (или в другом). файлы, если вы используете разделение кода).
Установка webpack
Webpack можно установить глобально или локально для каждого проекта.
Глобальная установка
Вот как установить его глобально с помощьюПряжа:
Local install
Webpack can be installed locally as well. It’s the recommended setup, because webpack can be updated per-project, and you have less resistance to using the latest features just for a small project rather than updating all the projects you have that use webpack.
once this is done, you can run webpack by typing
in the project root.
Webpack configuration
By default, webpack (starting from version 4) does not require any config if you respect these conventions:
You can customize every little bit of webpack of course, when you need. The webpack configuration is stored in the webpack.config.js file, in the project root folder.
The entry point
The output
Loaders
Using webpack allows you to use import or require statements in your JavaScript code to not just include other JavaScript, but any kind of file, for example CSS.
Webpack aims to handle all our dependencies, not just JavaScript, and loaders are one way to do that.
For example, in your code you can use:
by using this loader configuration:
The regular expression targets any CSS file.
A loader can have options:
You can require multiple loaders for each rule:
In this example, css-loader interprets the import ‘style.css’ directive in the CSS. style-loader is then responsible for injecting that CSS in the DOM, using a tag.
The order matters, and it’s reversed (the last is executed first).
What kind of loaders are there? Many! You can find the full list here.
A commonly used loader is Babel, which is used to transpile modern JavaScript to ES5 code:
This example makes Babel preprocess all our React/JSX files:
Plugins
Plugins are like loaders, but on steroids. They can do things that loaders can’t do, and they are the main building block of webpack.
The HTMLWebpackPlugin plugin has the job of automatically creating an HTML file, adding the output JS bundle path, so the JavaScript is ready to be served.
The webpack mode
This mode (introduced in webpack 4) sets the environment on which webpack works. It can be set to development or production (defaults to production, so you only set it when moving to development)
Production mode is slower to build, since it needs to generate a more optimized bundle. The resulting JavaScript file is smaller in size, as it removes many things that are not needed in production.
I made a sample app that just prints a console.log statement.
Here’s the production bundle:
Here’s the development bundle:
Running webpack
For example this package.json scripts definition we used before:
allows us to run webpack by running
Watching changes
Webpack can automatically rebuild the bundle when a change in your app happens, and keep listening for the next change.
Just add this script:
One nice feature of the watch mode is that the bundle is only changed if the build has no errors. If there are errors, watch will keep listening for changes, and try to rebuild the bundle, but the current, working bundle is not affected by those problematic builds.
Handling images
Webpack allows us to use images in a very convenient way, using the file-loader loader.
This simple configuration:
Allows you to import images in your JavaScript:
( img is an HTMLImageElement. Check the Image docs)
file-loader can handle other asset types as well, like fonts, CSV files, xml, and more.
Another nice tool to work with images is the url-loader loader.
This example loads any PNG file smaller than 8KB as a data URL.
Process your SASS code and transform it to CSS
Generate Source Maps
Since webpack bundles the code, Source Maps are mandatory to get a reference to the original file that raised an error, for example.
You tell webpack to generate source maps using the devtool property of the configuration:
devtool has many possible values, the most used probably are: