262 lines
24 KiB
JavaScript
262 lines
24 KiB
JavaScript
import { resolve } from 'node:path';
|
||
import { fileURLToPath } from 'node:url';
|
||
|
||
function escapeHtml(value) {
|
||
return String(value)
|
||
.replaceAll('&', '&')
|
||
.replaceAll('<', '<')
|
||
.replaceAll('>', '>')
|
||
.replaceAll('"', '"')
|
||
.replaceAll("'", ''');
|
||
}
|
||
|
||
function paragraph(text) {
|
||
return '<p>' + text + '</p>';
|
||
}
|
||
|
||
function heading(text) {
|
||
return '<h2>' + text + '</h2>';
|
||
}
|
||
|
||
function codeBlock(code) {
|
||
return '<pre><code>' + escapeHtml(String(code).trim()) + '</code></pre>';
|
||
}
|
||
|
||
function figure(src, alt, caption) {
|
||
return '<figure><img src="' + src + '" alt="' + alt + '" loading="lazy" /><figcaption>' + caption + '</figcaption></figure>';
|
||
}
|
||
|
||
function orderedList(items) {
|
||
return '<ol>' + items.map((item) => '<li>' + item + '</li>').join('') + '</ol>';
|
||
}
|
||
|
||
function bulletList(items) {
|
||
return '<ul>' + items.map((item) => '<li>' + item + '</li>').join('') + '</ul>';
|
||
}
|
||
|
||
function dataTable(headers, rows) {
|
||
const head = '<thead><tr>' + headers.map((header) => '<th scope="col">' + header + '</th>').join('') + '</tr></thead>';
|
||
const body = '<tbody>' + rows.map((row) => '<tr>' + row.map((cell) => '<td>' + cell + '</td>').join('') + '</tr>').join('') + '</tbody>';
|
||
return '<div class="table-scroll"><table>' + head + body + '</table></div>';
|
||
}
|
||
|
||
function sourceList(items) {
|
||
return '<ul>' + items.map((item) => '<li><a href="' + item.url + '" target="_blank" rel="noopener noreferrer">' + item.title + '</a> — ' + item.note + '</li>').join('') + '</ul>';
|
||
}
|
||
|
||
function visibleText(html) {
|
||
return html
|
||
.replace(/<[^>]*>/g, ' ')
|
||
.replaceAll(' ', ' ')
|
||
.replaceAll('"', '"')
|
||
.replaceAll(''', "'")
|
||
.replaceAll('<', '<')
|
||
.replaceAll('>', '>')
|
||
.replaceAll('&', '&')
|
||
.replace(/\s+/g, ' ')
|
||
.trim();
|
||
}
|
||
|
||
function proseText(html) {
|
||
return visibleText(
|
||
html
|
||
.replace(/<pre><code>[\s\S]*?<\/code><\/pre>/g, '')
|
||
.replace(/<figure>[\s\S]*?<\/figure>/g, '')
|
||
.replace(/<div class="table-scroll">[\s\S]*?<\/div>/g, ''),
|
||
);
|
||
}
|
||
|
||
function createRevision(meta, bodyParts, sources) {
|
||
const bodyHtml = bodyParts.join('\n');
|
||
const proseLength = proseText(bodyHtml).length;
|
||
|
||
if (proseLength < 5000 || proseLength > 15000) {
|
||
throw new Error(meta.slug + ': prose length must be 5000–15000, got ' + proseLength);
|
||
}
|
||
|
||
if (sources.length < 2) {
|
||
throw new Error(meta.slug + ': at least two primary sources are required');
|
||
}
|
||
|
||
const contentHtml = [
|
||
bodyHtml,
|
||
heading('Проверяемые источники'),
|
||
sourceList(sources),
|
||
].join('\n');
|
||
|
||
return {
|
||
...meta,
|
||
contentHtml,
|
||
proseLength,
|
||
};
|
||
}
|
||
|
||
const webpackShimming = {
|
||
title: 'Webpack 4: Shimming',
|
||
url: 'https://v4.webpack.js.org/guides/shimming/',
|
||
note: 'назначение ProvidePlugin, legacy-модули с глобальными зависимостями и границы shim-подхода',
|
||
};
|
||
|
||
const webpackCodeSplitting = {
|
||
title: 'Webpack 4: Code Splitting',
|
||
url: 'https://v4.webpack.js.org/guides/code-splitting/',
|
||
note: 'entry, динамические импорты и дублирование модуля между несколькими entry',
|
||
};
|
||
|
||
const webpackStats = {
|
||
title: 'Webpack 4: Stats Data',
|
||
url: 'https://v4.webpack.js.org/api/stats/',
|
||
note: 'структура JSON-статистики сборки: assets, chunks, modules, errors и warnings',
|
||
};
|
||
|
||
const webpackDevtool = {
|
||
title: 'Webpack 4: devtool',
|
||
url: 'https://v4.webpack.js.org/configuration/devtool/',
|
||
note: 'варианты source map и компромиссы между удобством диагностики, скоростью и раскрытием исходного кода',
|
||
};
|
||
|
||
const jqueryExtend = {
|
||
title: 'jQuery API: jQuery.fn.extend()',
|
||
url: 'https://api.jquery.com/jQuery.fn.extend/',
|
||
note: 'плагин добавляет метод в прототип конкретного объекта jQuery, то есть в конкретный $.fn',
|
||
};
|
||
|
||
const fieldArticle = createRevision(
|
||
{
|
||
slug: 'editorial-2019-01-field-jquery-webpack',
|
||
title: 'jQuery + Webpack: почему legacy-плагин исчезает только в production',
|
||
categories: ['JavaScript', 'Webpack', 'jQuery', 'Разбор'],
|
||
cover: '/assets/editorial/2019/jquery-webpack-production-bridge-2019.svg',
|
||
excerpt: 'Плагин виден в development, но после production-сборки у $.fn нет метода. Разделяем три причины: глобал не создан, плагин выполнился рано или приложение держит второй jQuery.',
|
||
readingMinutes: 11,
|
||
},
|
||
[
|
||
paragraph('В development старый плагин маски ввода работает, а в production вызов <code>$(input).legacyMask()</code> падает: метода нет в <code>$.fn</code>. Цена ошибки выше сломанного поля — сборка может уйти в релиз с нерабочим оформлением или проверкой номера, а срочная правка начнёт менять Webpack вслепую.'),
|
||
paragraph('Разберём один вопрос: как доказать, что плагин потерялся именно на границе <code>window.jQuery</code>, порядка исполнения или второго экземпляра <code>jquery</code>, а не из-за минификации. Это учебный сценарий для Webpack 4 и jQuery; он показывает форму проверки. Ни production-бандл конкретного проекта, ни браузерную трассу я здесь не выдаю за выполненные.'),
|
||
heading('Сначала фиксируем, что именно исчезло'),
|
||
paragraph('Плагин jQuery обычно добавляет функцию в <code>$.fn</code>. Значит, выражение <code>typeof $.fn.legacyMask</code> отвечает не на вопрос «плагин подключён вообще», а на более полезный: установил ли он метод на тот экземпляр jQuery, которым пользуется код страницы. Официальный API описывает <code>jQuery.fn.extend()</code> как расширение прототипа jQuery. Если в окне живут два разных объекта jQuery, метод может оказаться только на одном из них.'),
|
||
paragraph('Development часто скрывает границу. На локальной странице jQuery мог приехать отдельным тегом <code>script</code> раньше vendor-файла, а dev-сервер мог не собрать второй entry в тот же путь. Production собирает зависимости в модули и чанки. Это не делает Webpack виновником: меняется способ доставки, и скрытая зависимость плагина от глобального объекта становится видна.'),
|
||
dataTable(
|
||
['Наблюдение', 'Вероятная причина', 'Короткая проверка', 'Действие после проверки'],
|
||
[
|
||
['<code>window.jQuery</code> пустой до старого плагина', 'Импорт есть только в области модуля', 'Остановиться перед загрузкой плагина и вывести <code>window.jQuery</code>', 'Создать явный legacy-мост до выполнения плагина'],
|
||
['Метод есть у <code>window.jQuery.fn</code>, но нет у <code>$ .fn</code> приложения', 'Плагин и приложение держат разные экземпляры', 'Сравнить <code>window.jQuery === $</code>', 'Убрать второй путь резолвации и оставить одну зависимость'],
|
||
['Метода нет у обоих объектов', 'Файл плагина не выполнился или выполнился до моста', 'Проверить порядок модулей, ошибку в Console и включение файла в stats', 'Подключить адаптер после моста, затем проверить production-артефакт'],
|
||
['Сбой только при втором entry', 'jQuery попал в несколько entry или загрузка чанков не согласована', 'Посмотреть modules/chunks в <code>stats.json</code>', 'Настроить общую зависимость и проверить все точки входа'],
|
||
],
|
||
),
|
||
paragraph('В таблице есть важное ограничение: это дерево гипотез, не диагноз вашего сайта. Один и тот же текст ошибки может появиться при 404 vendor-файла, при CSP или при версии плагина, которая не совместима с закреплённой jQuery. Поэтому сначала собираем идентичности объектов и факт выполнения кода, а уже затем трогаем оптимизацию.'),
|
||
heading('Учебный пример: плагин читает window.jQuery'),
|
||
paragraph('Ниже минимальный legacy-файл. Он намеренно не импортирует jQuery: автор плагина рассчитывает, что глобальная переменная уже существует. Такой код неудобен для модулей, но он встречается в старых виджетах. Ошибка в примере воспроизводима без сервера: если в момент выполнения <code>root.jQuery</code> отсутствует, модуль бросает понятное исключение; если объект есть, метод появляется именно на его <code>fn</code>.'),
|
||
codeBlock(String.raw`
|
||
// src/vendor/legacy-mask.js
|
||
(function installLegacyMask(root) {
|
||
var $ = root.jQuery;
|
||
|
||
if (!$ || !$.fn) {
|
||
throw new Error('legacy-mask ожидает window.jQuery до своего запуска');
|
||
}
|
||
|
||
$.fn.legacyMask = function legacyMask() {
|
||
return this.addClass('has-legacy-mask');
|
||
};
|
||
}(window));
|
||
`),
|
||
paragraph('Соблазнительный вариант ниже выглядит как правильный порядок сверху вниз: сначала импорт, затем присваивание, затем импорт плагина. Но статический <code>import</code> описывает зависимость модуля, а не вызов, который исполняется на этой строке после предыдущего оператора. Зависимый <code>legacy-mask.js</code> должен быть подготовлен и выполнен до тела модуля <code>bootstrap.bad.js</code>; присваивание в <code>window</code> для него опаздывает.'),
|
||
codeBlock(String.raw`
|
||
// src/bootstrap.bad.js
|
||
import $ from 'jquery';
|
||
import './vendor/legacy-mask';
|
||
|
||
window.jQuery = window.$ = $; // для legacy-mask это уже поздно
|
||
|
||
$('.js-phone').legacyMask();
|
||
`),
|
||
paragraph('Для одного старого плагина не обязательно переводить весь код назад на CommonJS. Достаточно сделать маленький адаптер с явной границей. В нём <code>require()</code> вызывается после записи в <code>window</code>; поэтому legacy-файл получает именно тот объект, который импортировал bootstrap. Этот приём выбран здесь ради порядка выполнения, а не как общий стиль нового кода.'),
|
||
codeBlock(String.raw`
|
||
// src/legacy-jquery-bridge.js
|
||
import $ from 'jquery';
|
||
|
||
window.jQuery = window.$ = $;
|
||
require('./vendor/legacy-mask');
|
||
|
||
export default $;
|
||
|
||
// src/bootstrap.js
|
||
import $ from './legacy-jquery-bridge';
|
||
|
||
$('.js-phone').legacyMask();
|
||
`),
|
||
paragraph('После такого моста минимальная проверка не должна ограничиваться отсутствием исключения. Нужно удостовериться, что глобальный объект и импорт имеют одну ссылку, а метод лежит на том же <code>$.fn</code>, с которым работает приложение. Так мы отделяем проблему порядка от ситуации, когда плагин успешно установился, но на чужой копии jQuery.'),
|
||
codeBlock(String.raw`
|
||
// В Console страницы или во временном диагностическом модуле.
|
||
import $ from './legacy-jquery-bridge';
|
||
|
||
var report = {
|
||
hasGlobal: Boolean(window.jQuery),
|
||
sameInstance: window.jQuery === $,
|
||
pluginOnImport: typeof $.fn.legacyMask,
|
||
pluginOnGlobal: window.jQuery && typeof window.jQuery.fn.legacyMask,
|
||
};
|
||
|
||
console.table(report);
|
||
console.assert(report.sameInstance, 'jQuery резолвится в разные экземпляры');
|
||
console.assert(report.pluginOnImport === 'function', 'плагин не установлен на импорт');
|
||
`),
|
||
heading('Почему ProvidePlugin не заменяет мост'),
|
||
paragraph('У <code>ProvidePlugin</code> другая задача. Документация Webpack 4 описывает его как способ сделать пакет переменной в модулях, которые компилирует Webpack, когда встречается нужный идентификатор. Это полезно для legacy-модуля, который обращается к свободной переменной <code>jQuery</code>, но не является автоматическим присваиванием свойства <code>window.jQuery</code>.'),
|
||
paragraph('Поэтому решение должно следовать из самого плагина. Если файл принимает <code>jQuery</code> как параметр или использует свободную переменную, можно проверить настройку <code>ProvidePlugin</code>. Если он явно читает <code>window.jQuery</code>, нужен мост в <code>window</code> либо отдельная настройка loader, которая документированно передаёт зависимость. Подменять оба варианта одной конфигурацией опасно: в development симптом может исчезнуть из-за случайного порядка тегов, а в production вернуться.'),
|
||
figure('/assets/editorial/2019/jquery-webpack-production-bridge-2019.svg', 'Схема диагностики legacy jQuery-плагина: неправильный статический импорт запускает плагин до назначения window.jQuery, а проверка равенства выявляет второй экземпляр jQuery', 'Проверка идёт от порядка исполнения к идентичности экземпляра: сначала мост, затем плагин, затем сравнение объектов.'),
|
||
heading('Как искать второй экземпляр без догадки по размеру bundle'),
|
||
paragraph('Два пакета не обязаны выглядеть как два одинаковых больших файла. Один экземпляр мог войти в entry страницы, другой — в зависимость виджета по другому пути или версии. Поэтому размер итогового JavaScript — слабое доказательство. Надёжнее сравнить объекты в рантайме и посмотреть список модулей в статистике именно той production-сборки, которая будет доставлена пользователю.'),
|
||
paragraph('Webpack 4 документирует JSON-статистику как представление assets, chunks и modules. В реальном репозитории её можно запросить отдельной командой. Команду ниже не запускали для этой статьи: она является маршрутом диагностики, который нужно выполнять в ветке проекта и сохранять рядом с версией lock-файла. Source map включается только на время разбора и только если правила публикации исходников это позволяют.'),
|
||
codeBlock(String.raw`
|
||
# Команды для реального проекта, а не результат этого учебного примера.
|
||
npx webpack --mode production --devtool source-map --profile --json > dist/stats.json
|
||
npm ls jquery
|
||
|
||
# В stats.json ищем пути и чанки, где встречается jquery.
|
||
# Затем в браузере сравниваем window.jQuery с импортом из legacy-моста.
|
||
`),
|
||
paragraph('Если <code>npm ls jquery</code> показывает несколько веток, это ещё не приговор: сборщик может дедуплицировать совместимые зависимости. Если в <code>stats.json</code> видны несколько модулей jQuery или разные resolved-пути, это также не доказывает, что два объекта дошли до страницы. Диагноз закрывается только вместе с равенством <code>window.jQuery === $</code>, фактом появления метода и сетевой записью тех чанков, которые фактически загрузил браузер.'),
|
||
heading('Порядок проверки production-сценария'),
|
||
orderedList([
|
||
'Зафиксировать точный симптом: имя метода, страницу, один input и версию собранных ассетов. Не менять конфигурацию до записи исходной ошибки.',
|
||
'В точке перед вызовом плагина вывести <code>window.jQuery</code>, импорт <code>$</code>, их равенство и тип <code>$.fn.legacyMask</code>. Это отделяет отсутствие глобала от второго экземпляра.',
|
||
'Открыть Network и убедиться, что нужные entry и lazy-chunk действительно получили ответ, а не старую страницу из кеша. Записать имена файлов и hash, не делать вывод по одному названию bundle.',
|
||
'Собрать production-статистику на той же версии lock-файла. Найти resolved-пути <code>jquery</code>, их chunks и причины подключения.',
|
||
'Если плагин читает глобал, создать один изолированный bridge до его загрузки; если он принимает импорт, удалить глобальную зависимость вместо добавления нового shim.',
|
||
'Повторить проверку на чистой странице и в каждом entry, где живёт виджет. Готовность — одинаковый объект jQuery и функция плагина на его <code>fn</code>, а не только исчезнувшая ошибка в Console.',
|
||
]),
|
||
heading('Что считать исправлением'),
|
||
paragraph('Исправлением является не строка <code>window.$ = $</code> сама по себе. Нужен маленький контракт: bridge импортирует одну зависимость, публикует её в global до legacy-файла, подключает нужный side effect и экспортирует тот же объект приложению. Так следующий разработчик видит, где заканчивается старый API и почему этот файл нельзя переставить среди обычных импортов.'),
|
||
paragraph('Если обнаружен второй экземпляр, сначала устраняем причину его попадания в граф: разный resolved-путь, несовместимая версия или отдельный entry без общей оптимизации. Webpack 4 отдельно предупреждает, что несколько entry могут дублировать общий импорт; для этого есть SplitChunksPlugin. Но включить splitChunks «для лечения плагина» недостаточно: после изменения всё равно проверяем идентичность объектов и метод в runtime.'),
|
||
heading('Ограничения и границы примера'),
|
||
bulletList([
|
||
'Пример предполагает браузерный <code>window</code> и Webpack 4. В SSR, worker или тестовой среде global-объект другой; мост надо либо не исполнять на сервере, либо изолировать адаптером окружения.',
|
||
'Вызов <code>require()</code> оставлен только внутри legacy-моста ради наблюдаемого порядка. Он не является рекомендацией смешивать системы модулей во всём новом коде.',
|
||
'Source map может раскрывать пути и исходный код. Его нельзя включать в публичную production-доставку без проверки политики проекта; для расследования подойдёт защищённый артефакт.',
|
||
'CSP, 404 чанка, несовместимая версия плагина и кеш CDN могут дать похожий внешний симптом. Этот текст не заменяет Network, Console и точную версию зависимостей.',
|
||
'Глобальная jQuery — совместимость с конкретным legacy-файлом, а не архитектурная цель. Новый виджет лучше получает зависимость импортом и не меняет <code>window</code>.',
|
||
]),
|
||
heading('Итог'),
|
||
paragraph('Когда <code>$.fn.legacyMask</code> пропадает только после production-сборки, не стоит первым делом отключать минификацию. Сначала проверяем порядок: есть ли <code>window.jQuery</code> до плагина. Затем проверяем идентичность: тот ли это объект, который импортирует приложение. После этого production-статистика и Network показывают, какой модуль и какой чанк нужно исправлять. Такой маршрут оставляет одно проверяемое условие готовности: плагин установлен на том же <code>$.fn</code>, которым пользуется экран.'),
|
||
],
|
||
[webpackShimming, webpackCodeSplitting, webpackStats, webpackDevtool, jqueryExtend],
|
||
);
|
||
|
||
export const revisions = [fieldArticle]
|
||
.map(({ proseLength, ...revision }) => revision);
|
||
|
||
const isDirectRun = process.argv[1]
|
||
&& resolve(process.argv[1]) === fileURLToPath(import.meta.url);
|
||
|
||
if (isDirectRun) {
|
||
if (process.argv.includes('--print-revisions')) {
|
||
process.stdout.write(JSON.stringify(revisions, null, 2) + '\n');
|
||
} else {
|
||
process.stderr.write('Usage: node web/scripts/upgrade-2019-01-field.mjs --print-revisions\n');
|
||
process.exitCode = 1;
|
||
}
|
||
}
|