Как добавить MP3 в проект React и TypeScript

Короткий ответ: в React-проекте на TypeScript mp3 можно добавить двумя нормальными способами. Первый: положить файл в src/assets, импортировать его в компонент и передать в <audio controls src={trackUrl}>. Второй: положить mp3 в public и указать прямой путь вроде /audio/track.mp3. Для большинства учебных и небольших проектов удобнее первый вариант, потому что сборщик проверяет путь и включает файл в сборку

Содержание

Вариант через src/assets
Если TypeScript не понимает mp3
Вариант через public
Мини-проект: кнопка выбора трека
Частые ошибки
Самопроверка
Что почитать дальше по TypeScript

Вариант через src/assets

Структура проекта:

src/
  assets/
    intro.mp3
  components/
    AudioPlayer.tsx
  App.tsx

Компонент AudioPlayer.tsx:

import introTrack from "../assets/intro.mp3";

export function AudioPlayer() {
  return (
    <section>
      <h2>Аудио урок</h2>
      <audio controls src={introTrack}>
        Ваш браузер не поддерживает аудио.
      </audio>
    </section>
  );
}

Подключите компонент в App.tsx:

import { AudioPlayer } from "./components/AudioPlayer";

function App() {
  return (
    <main>
      <h1>React + TypeScript + mp3</h1>
      <AudioPlayer />
    </main>
  );
}

export default App;

Запустите проект:

npm run dev

или, если проект создан через Create React App:

npm start

На странице должен появиться стандартный аудиоплеер браузера

Если TypeScript не понимает mp3

В Vite шаблон react-ts обычно уже умеет работать с импортом ассетов. Но в некоторых проектах TypeScript может показать ошибку вида:

Cannot find module '../assets/intro.mp3'

Тогда добавьте файл деклараций, например src/declarations.d.ts:

declare module "*.mp3" {
  const src: string;
  export default src;
}

Эта декларация объясняет TypeScript, что импорт mp3 возвращает строку с адрес файла после сборки

Вариант через public

Если mp3 должен лежать как статический файл и не проходить через импорт, создайте папку:

public/
  audio/
    intro.mp3

А в компоненте укажите путь:

export function AudioPlayer() {
  return (
    <audio controls src="/audio/intro.mp3">
      Ваш браузер не поддерживает аудио.
    </audio>
  );
}

Плюс этого варианта — простота. Минус — сборщик не проверит, что файл реально существует. Если вы ошиблись в имени, TypeScript не предупредит, а браузер просто не загрузит аудио

Мини-проект: кнопка выбора трека

Можно сделать маленький плеер с несколькими mp3:

import intro from "../assets/intro.mp3";
import lesson from "../assets/lesson.mp3";

type Track = {
  title: string;
  url: string;
};

const tracks: Track[] = [
  { title: "Вступление", url: intro },
  { title: "Урок", url: lesson },
];

export function AudioPlayer() {
  const [currentTrack, setCurrentTrack] = useState<Track>(tracks[0]);

  return (
    <section>
      <h2>{currentTrack.title}</h2>
      <audio controls src={currentTrack.url} />
      <div>
        {tracks.map((track) => (
          <button key={track.title} onClick={() => setCurrentTrack(track)}>
            {track.title}
          </button>
        ))}
      </div>
    </section>
  );
}

Не забудьте импортировать useState:

import { useState } from "react";

Здесь TypeScript следит, чтобы каждый трек имел title и url, а состояние currentTrack не стало случайной строкой или null

Частые ошибки

Первая ошибка — путь к файлу. В импорте ../assets/intro.mp3 путь считается от текущего файла компонента, а не от корня проекта

Вторая ошибка — попытка включить autoplay. Современные браузеры часто блокируют автоматическое воспроизведение со звуком, пока пользователь не взаимодействовал со страницей. Поэтому для учебного примера используйте controls, а не рассчитывайте на автозапуск

Третья ошибка — слишком большой mp3 внутри src/assets. Если файл тяжелый и нужен как публичный медиафайл, разумнее хранить его в public или вынести на CDN/медиахостинг

Четвертая ошибка — забытый импорт useState в мини-плеере. Если используете состояние, React-хук нужно импортировать отдельно

Самопроверка

Переименуйте файл intro.mp3 в intro-old.mp3 и запустите сборку. При варианте через импорт сборщик должен показать проблему с путем. Верните имя обратно и проверьте, что аудио снова загружается

Потом добавьте второй трек и убедитесь, что кнопки переключают src у аудиоплеера. Это хороший быстрый тест, что mp3 подключен не случайно, а управляется React-компонентом