Практические ошибки и как их избежать

При работе с файлами и ресурсами в React-приложениях часто возникают ошибки, связанные с непониманием того, как сборщик (Webpack/Vite) обрабатывает зависимости. Большинство проблем проявляются только в продакшене, что усложняет отладку.

Типичные ошибки и решения

1. Использование строк вместо импорта для ресурсов

Ошибка: 

<img src="./assets/logo.png" />

Почему плохо:
Сборщик не видит зависимость → файл не копируется в сборку → изображение не загружается в продакшене.
Решение:
Всегда импортируйте: 

import logo from './assets/logo.png';
<img src={logo} />

2. Попытка использовать require() для изображений

Ошибка: 

<img src={require('./logo.png')} />

Почему плохо:
require — часть CommonJS, не поддерживается в Vite и не рекомендуется в современных проектах.
Решение:
Используйте ES-модули: import logo from './logo.png';.

3. Хранение обычных изображений в public/

Ошибка:
Кладёте logo.png в public/ и используете <img src="/logo.png" />.
Почему плохо:

  • Нет хеширования → кэширование ломается при обновлении,
  • Сборщик не проверяет наличие файла → опечатка = 404 в продакшене,
  • Нарушается модульность компонентов.
    Решение:
    Используйте public/ только для favicon.ico, robots.txt, manifest.json. Остальное — через импорт из src/.

4. Неправильные пути в CSS (url())

Ошибка: 

background: url('assets/bg.jpg');

Почему плохо:
Путь не относительный от CSS-файла → сборщик не находит файл.
Решение:
Всегда используйте относительные пути: 

background: url('../assets/images/bg.jpg');

5. Динамический импорт ресурсов по переменной

Ошибка: 

const icon = `./icons/${name}.png`;
// или
import(`./icons/${name}.png`);

Почему плохо:
Сборщик не может определить, какие файлы нужны → либо ошибка, либо в бандл попадают все файлы из папки.
Решение:
Используйте маппинг или заранее импортируйте нужные файлы: 

const icons = {
  home: require('./icons/home.png'),
  user: require('./icons/user.png')
};
// или с import (в верхнем уровне модуля)
import homeIcon from './icons/home.png';
import userIcon from './icons/user.png';

Как избежать ошибок

  • Всегда проверяйте сборку: запускайте npm run build и открывайте build/ или dist/ локально.
  • Не полагайтесь на поведение dev-сервера: то, что работает в разработке, может сломаться в продакшене.
  • Используйте IDE-подсказки: если путь в import подсвечивается как ошибка — файл не найден.
  • Храните все ресурсы в src/, кроме тех, что явно требуют размещения в public/.

Понимание границ ответственности сборщика — ключ к стабильной работе с файлами в React.