react-native-web-sound

0.2.1 verified Fri May 01 auth: no javascript

A drop-in replacement for react-native-sound that works with react-native-web. Version 0.2.1 is the current stable release. It allows playing audio in web browsers by aliasing the react-native-sound package to this web implementation. The library mirrors the original API exactly, so no code changes are needed beyond the webpack alias configuration. It has low maintenance cadence but remains functional for basic audio playback needs. Alternatives include react-native-sound directly (native only) or web-specific libraries like Howler.js, but this package minimizes migration effort for existing react-native-sound users.

Common errors

error Cannot find module 'react-native-sound' ↓

cause Webpack alias not configured or missing in resolve.alias.

fix

Add the alias as shown in the README: 'react-native-sound': 'react-native-web-sound'

error TypeError: Sound is not a constructor ↓

cause Using named import instead of default import or missing .default in CommonJS.

fix

Use default import: import Sound from 'react-native-sound' or const Sound = require('react-native-sound').default

error Failed to load sound: The request is not allowed by the user agent or the platform in the current context, possibly because the user denied permission. ↓

cause Autoplay restriction due to browser policy; sound.play() must be triggered by user gesture.

fix

Wrap sound.play() in a user-initiated event handler (e.g., onClick).

Warnings

gotcha Webpack alias configuration is required for package to work; direct import of 'react-native-web-sound' is possible but may lead to inconsistent behavior if other parts of code expect 'react-native-sound'. ↓

fix Add the alias as shown in the README.

breaking The package does not support all features of react-native-sound, such as file system paths or bundled assets. Only URL playback is verified to work. ↓

fix Use only remote URLs for audio files.

gotcha The Sound constructor callback may not fire in all browsers due to autoplay policies. User interaction must precede sound.play(). ↓

fix Ensure play() is called from a user-initiated event handler like a button press.

deprecated react-native-web-sound has not been updated in over 2 years; newer versions of react-native-web may cause compatibility issues. ↓

fix Consider migrating to a more actively maintained web audio library like Howler.js or native solution.

Install

npm install react-native-web-sound

yarn add react-native-web-sound

pnpm add react-native-web-sound

Imports

Sound
wrong
```
import { Sound } from 'react-native-sound'
```
correct
```
import Sound from 'react-native-sound'
```
The library uses default export, mirroring react-native-sound. Named export does not exist.
Sound
wrong
```
const Sound = require('react-native-sound')
```
correct
```
const Sound = require('react-native-sound').default
```
CommonJS require needs .default because the package uses ESM default export internally.
Sound
```
import Sound from 'react-native-web-sound'
```
Direct import of this package works, but recommended usage is via webpack alias to react-native-sound.

Quickstart

Demonstrates how to configure webpack alias and use the Sound API to play remote audio in a React Native Web app.

// webpack.config.js
resolve: {
  alias: {
    'react-native': 'react-native-web',
    'react-native-sound': 'react-native-web-sound',
  }
}

// App.js
import React from 'react';
import { Button } from 'react-native';
import Sound from 'react-native-sound';

const App = () => {
  const playSound = () => {
    const sound = new Sound('https://example.com/audio.mp3', null, (error) => {
      if (error) {
        console.error('Failed to load sound', error);
        return;
      }
      sound.play(() => sound.release());
    });
  };

  return <Button title="Play" onPress={playSound} />;
};

export default App;