Отказ от Node.js полифилов по умолчанию

До Webpack 5 многие Node.js API автоматически подменялись браузерными аналогами. При использовании модулей вроде crypto, path, stream, buffer или process Webpack silently добавлял соответствующие полифилы в итоговый bundle.

Такое поведение приводило к ряду проблем:

существенному увеличению размера сборки;
неявным зависимостям;
сложностям анализа производительности;
случайному попаданию серверного кода в браузер;
несовместимостям между браузерной и серверной средой.

Webpack 5 изменил философию работы: теперь автоматические полифилы отключены по умолчанию.

При попытке использовать Node.js API в браузерной сборке появляется ошибка:

Module not found: Error: Can't resolve 'crypto'

или:

BREAKING CHANGE: webpack < 5 used to include polyfills for node.js core modules by default.

Такое поведение делает архитектуру более прозрачной и предсказуемой.

Какие модули раньше полифилились автоматически

Webpack 4 автоматически подключал аналоги для следующих Node.js модулей:

Node.js модуль	Типичный браузерный полифил
`buffer`	`buffer`
`crypto`	`crypto-browserify`
`stream`	`stream-browserify`
`path`	`path-browserify`
`util`	`util`
`assert`	`assert`
`os`	`os-browserify`
`http`	`stream-http`
`https`	`https-browserify`
`zlib`	`browserify-zlib`

В Webpack 5 эти зависимости больше не подключаются автоматически.

Основная причина изменений

Автоматические полифилы нарушали важный принцип:

браузерный код не должен случайно зависеть от Node.js окружения.

Пример проблемы:

import crypto from 'crypto';

export function hash(data) {
    return crypto
        .createHash('sha256')
        .update(data)
        .digest('hex');
}

В Node.js такой код работает естественно.

В браузере Webpack 4 автоматически подтягивал огромный пакет crypto-browserify, включая дополнительные зависимости:

stream
buffer
inherits
randombytes
bn.js

В результате:

bundle увеличивался на сотни килобайт;
ухудшалась загрузка;
разработчик мог даже не знать о появлении этих зависимостей.

Webpack 5 делает подобные зависимости явными.

Проверка зависимостей после миграции на Webpack 5

После обновления часто выясняется, что Node.js API используются не напрямую, а через сторонние библиотеки.

Типичный пример:

import jwt from 'jsonwebtoken';

Пакет jsonwebtoken зависит от crypto, buffer, stream и других Node.js модулей.

В браузерной сборке появляется каскад ошибок:

Can't resolve 'crypto'
Can't resolve 'stream'
Can't resolve 'buffer'

Это означает, что библиотека изначально проектировалась для Node.js.

Способы решения проблемы

Существует несколько стратегий.

Полный отказ от Node.js API в браузере

Наиболее правильный подход — использовать браузерные аналоги.

Например, вместо:

import crypto from 'crypto';

используется Web Crypto API:

const encoder = new TextEncoder();

const data = encoder.encode('hello');

const hashBuffer = await crypto.subtle.digest(
    'SHA-256',
    data
);

Преимущества:

отсутствие полифилов;
меньший размер bundle;
использование нативных браузерных API;
лучшая производительность.

Явное подключение полифилов

Если библиотека действительно необходима, полифил подключается вручную.

Установка зависимостей

npm install buffer process util

или:

yarn add buffer process util

Использование `resolve.fallback`

Webpack 5 предоставляет механизм fallback.

Пример:

const webpack = require('webpack');

module.exports = {
    resolve: {
        fallback: {
            buffer: require.resolve('buffer/'),
            util: require.resolve('util/'),
            process: require.resolve('process/browser')
        }
    },

    plugins: [
        new webpack.ProvidePlugin({
            Buffer: ['buffer', 'Buffer'],
            process: 'process/browser'
        })
    ]
};

Как работает `fallback`

Webpack анализирует импорт:

import { Buffer } from 'buffer';

или:

require('buffer');

После этого выполняется перенаправление:

buffer -> buffer/

То есть вместо Node.js builtin-модуля используется npm-пакет.

Отключение полифила полностью

Иногда модуль вообще не нужен в браузере.

Тогда используется значение false.

Пример:

module.exports = {
    resolve: {
        fallback: {
            fs: false,
            path: false,
            net: false,
            tls: false
        }
    }
};

Это особенно важно для серверных библиотек, которые частично импортируются в frontend.

Пример проблемы с `fs`

Рассмотрим код:

import fs from 'fs';

export function readConfig() {
    return fs.readFileSync('./config.json');
}

Такой код не может работать в браузере:

браузер не имеет доступа к файловой системе;
Webpack 5 больше не скрывает эту проблему.

При указании:

fallback: {
    fs: false
}

Webpack явно сообщает о невозможности использования API.

Разделение серверного и браузерного кода

После отказа от автоматических полифилов особенно важным становится разделение runtime-сред.

Неправильный подход

import fs from 'fs';

export function loadData() {
    if (typeof window === 'undefined') {
        return fs.readFileSync('./file.txt');
    }
}

Даже несмотря на условие, Webpack всё равно анализирует импорт.

Правильный подход

Серверный модуль

// server.js

import fs from 'fs';

export function loadData() {
    return fs.readFileSync('./file.txt');
}

Браузерный модуль

// client.js

export function loadData() {
    return fetch('/api/data');
}

Conditional exports

Современные библиотеки используют разные entry-point для браузера и Node.js.

Пример package.json:

{
    "exports": {
        ".": {
            "browser": "./browser.js",
            "node": "./node.js",
            "default": "./browser.js"
        }
    }
}

Webpack умеет автоматически выбирать подходящую реализацию.

Поле `browser` в package.json

Более старый механизм:

{
    "browser": {
        "fs": false,
        "./server.js": "./browser.js"
    }
}

Такой подход всё ещё широко используется.

Использование `target`

Настройка target влияет на обработку встроенных модулей.

Browser target

module.exports = {
    target: 'web'
};

Webpack ожидает браузерное окружение.

Node target

module.exports = {
    target: 'node'
};

В этом режиме:

Node.js builtin-модули не полифилятся;
require('fs') сохраняется;
Webpack ориентируется на серверное выполнение.

Multi-target конфигурации

Крупные приложения часто используют две сборки:

module.exports = [
    {
        target: 'web',
        entry: './src/client.js'
    },

    {
        target: 'node',
        entry: './src/server.js'
    }
];

Это позволяет полностью разделить окружения.

Проблемы с legacy-библиотеками

Некоторые старые npm-пакеты предполагают наличие Node.js API даже в браузере.

Типичные признаки:

использование process.nextTick;
использование Buffer;
импорт stream;
импорт crypto;
CommonJS-only архитектура.

После перехода на Webpack 5 подобные библиотеки начинают ломаться.

Замена устаревших библиотек

Часто лучше заменить зависимость, чем подключать цепочку полифилов.

Пример

Вместо:

crypto-browserify

используется:

window.crypto.subtle

Вместо:

stream-browserify

используются:

WHATWG Streams;
Web Streams API;
native fetch streams.

Проверка размера bundle

После удаления полифилов bundle часто уменьшается на сотни килобайт.

Особенно тяжёлыми являются:

Полифил	Размер
crypto-browserify	очень большой
stream-browserify	большой
buffer	средний
path-browserify	маленький

Анализ зависимостей

Для поиска скрытых Node.js зависимостей используется:

npm ls crypto

или:

npm ls stream

Также помогает анализ bundle:

webpack --json > stats.json

Использование webpack-bundle-analyzer

Пакет:

npm install webpack-bundle-analyzer --save-dev

Конфигурация:

const {
    BundleAnalyzerPlugin
} = require('webpack-bundle-analyzer');

module.exports = {
    plugins: [
        new BundleAnalyzerPlugin()
    ]
};

Позволяет быстро обнаружить:

browserify-полифилы;
oversized dependencies;
случайные Node.js модули.

Глобальные переменные Node.js

Webpack 4 автоматически добавлял:

process
Buffer
global

Webpack 5 этого больше не делает.

Ручное подключение `process`

npm install process

const webpack = require('webpack');

module.exports = {
    plugins: [
        new webpack.ProvidePlugin({
            process: 'process/browser'
        })
    ]
};

Ручное подключение `Buffer`

npm install buffer

const webpack = require('webpack');

module.exports = {
    plugins: [
        new webpack.ProvidePlugin({
            Buffer: ['buffer', 'Buffer']
        })
    ]
};

Использование `node` в Webpack 5

В Webpack 4 существовала секция:

node: {
    fs: 'empty'
}

В Webpack 5 этот механизм считается устаревшим.

Современная замена:

resolve: {
    fallback: {
        fs: false
    }
}

Ошибка `process is not defined`

Типичная проблема после миграции:

ReferenceError: process is not defined

Причина:

библиотека ожидает Node.js environment;
глобальный объект больше не внедряется автоматически.

Решение:

new webpack.ProvidePlugin({
    process: 'process/browser'
})

или отказ от несовместимой библиотеки.

Ошибка `Buffer is not defined`

Аналогичная ситуация:

ReferenceError: Buffer is not defined

Решение:

new webpack.ProvidePlugin({
    Buffer: ['buffer', 'Buffer']
})

Почему Webpack отказался от старого поведения

Основные причины:

Прозрачность

Разработчик явно видит зависимости.

Производительность

Bundle перестаёт раздуваться скрытыми полифилами.

Совместимость

Node.js и browser runtime больше не смешиваются неявно.

Современные Web API

Большинство старых задач уже решаются нативными браузерными средствами:

Node.js API	Современная альтернатива
`crypto`	Web Crypto API
`stream`	Web Streams API
`http`	Fetch API
`url`	URL API
`querystring`	URLSearchParams

Практика миграции старых проектов

Типичный порядок действий:

Обновление до Webpack 5.
Получение списка отсутствующих модулей.
Анализ источника зависимостей.
Удаление ненужных Node.js библиотек.
Подключение только необходимых полифилов.
Проверка размера bundle.
Разделение server/client кода.

Минимизация количества полифилов

Хорошей практикой считается:

не полифилить crypto без крайней необходимости;
избегать stream-browserify;
не подключать buffer глобально без причины;
удалять legacy-зависимости;
использовать browser-native API.

Современная архитектурная тенденция

Frontend ecosystem постепенно уходит от browserify-совместимого подхода.

Современные инструменты:

Webpack 5
Vite
esbuild
Rollup

предпочитают:

нативные браузерные возможности;
ESM;
минимальный runtime;
отсутствие Node.js shim-слоя.

Отказ от автоматических полифилов стал важным этапом этой эволюции.

Отказ от Node.js полифилов по умолчанию

Какие модули раньше полифилились автоматически

Основная причина изменений

Проверка зависимостей после миграции на Webpack 5

Способы решения проблемы

Полный отказ от Node.js API в браузере

Явное подключение полифилов

Установка зависимостей

Использование resolve.fallback

Как работает fallback

Отключение полифила полностью

Пример проблемы с fs

Разделение серверного и браузерного кода

Неправильный подход

Правильный подход

Серверный модуль

Браузерный модуль

Conditional exports

Поле browser в package.json

Использование target

Browser target

Node target

Multi-target конфигурации

Проблемы с legacy-библиотеками

Замена устаревших библиотек

Пример

Проверка размера bundle

Анализ зависимостей

Использование webpack-bundle-analyzer

Глобальные переменные Node.js

Ручное подключение process

Ручное подключение Buffer

Использование node в Webpack 5

Ошибка process is not defined

Ошибка Buffer is not defined

Почему Webpack отказался от старого поведения

Прозрачность

Производительность

Совместимость

Современные Web API

Практика миграции старых проектов

Минимизация количества полифилов

Современная архитектурная тенденция

Использование `resolve.fallback`

Как работает `fallback`

Пример проблемы с `fs`

Поле `browser` в package.json

Использование `target`

Ручное подключение `process`

Ручное подключение `Buffer`

Использование `node` в Webpack 5

Ошибка `process is not defined`

Ошибка `Buffer is not defined`