TAL Radio Widget

A customizable live radio widget for React and Next.js applications with Firebase realtime database support.

TAL LiveRadio Widget — a simple, lightweight React component that connects to a Firebase Realtime Database to show and control live radio streams. This README contains clear usage examples and helpful comments so you can drop the widget into React or Next.js projects quickly.

Table of contents

1. Features

2. Requirements (peer dependencies)

3. Installation

4. Firebase setup

5. Usage

   • React example
   • Next.js (app router) example

6. Component props and customization options

7. Styling

8. Building & publishing notes

9. Contributing

10. License

1. Features

• Connects to Firebase Realtime Database for live metadata and control
• Play / pause live radio stream
• Lightweight and customizable UI
• Works in React and Next.js projects (both pages & app routers)

2. Requirements (peer dependencies)

Make sure your project already includes these peer dependencies:

npm install react react-dom firebase

These are peer dependencies because the host app should control their versions. The widget expects the host app to initialize Firebase or pass the firebaseConfig.

3. Installation

Install the widget package from npm:

npm install tal-live-radio-player

4. Firebase setup

Create a small firebase.js (or firebase.ts) helper in your project to initialize Firebase. The widget needs either a firebaseConfig object or a pre-initialized Firebase database instance.

// firebase/firebase.js
// --------------------
// Example Firebase initialization for the Realtime Database

import { initializeApp } from "firebase/app";
import { getDatabase } from "firebase/database";

// Replace these values with your project's config values from the Firebase console
export const firebaseConfig = {
  apiKey: "YOUR_API_KEY",
  authDomain: "YOUR_PROJECT.firebaseapp.com",
  databaseURL: "https://YOUR_PROJECT.firebaseio.com",
  projectId: "YOUR_PROJECT_ID",
  storageBucket: "YOUR_PROJECT.appspot.com",
  messagingSenderId: "YOUR_SENDER_ID",
  appId: "YOUR_APP_ID",
};

// Initialize firebase app and export database
// Note: if your app already initializes Firebase, export the same database instance instead
export const firebaseApp = initializeApp(firebaseConfig);
export const database = getDatabase(firebaseApp);

Comments:

• If your project already initializes Firebase at a higher level, you can pass the database instance or firebaseApp into the widget instead of firebaseConfig.
• Ensure your Realtime Database rules allow the widget to read the necessary nodes (or require authentication if that's desired).

5. Usage

5.1 React (create-react-app, Vite, or similar)

// ExampleComponent.jsx
"use client"; // not necessary for CRA/Vite, but harmless if you use it

import React from "react";
import { LiveRadioWidget } from "tal-live-radio-player";
import { firebaseConfig } from "../firebase/firebase"; // path to your firebase helper
import "tal-live-radio-player/style.css"; // import widget styles

const RadioComponent = () => {
  return (
    <div>
      {/* Pass your firebaseConfig so widget can initialize / connect */}
      <LiveRadioWidget firebaseConfig={firebaseConfig} />
    </div>
  );
};

export default RadioComponent;

5.2 Next.js (App Router - app/ directory)

If you are using Next.js App Router (React Server Components by default), the widget must be rendered on the client. Use a client component wrapper.

// app/components/RadioClient.jsx
"use client"; // required for Next.js app router: renders this component on the client

import React from "react";
import { LiveRadioWidget } from "tal-live-radio-player";
import { firebaseConfig } from "../../firebase/firebase"; // update path
import "tal-live-radio-player/style.css";

export default function RadioClient() {
  return <LiveRadioWidget firebaseConfig={firebaseConfig} />;
}

Then import this RadioClient into any server or client components safely.

Comments:

• In Next.js pages router (pages/), treat it like a normal client-side React component.
• Always add "use client" at the top of components that directly use the widget when in the app/ directory.

6. Component props and customization options

These props are the recommended options the widget accepts. Update this section to match your package's implementation if you add or change props.

interface LiveRadioWidgetProps {
  // Provide your firebase config object (as shown above). Either this OR `database` must be provided.
  firebaseConfig?: Record<string, any>;

  // Alternatively, you can pass an already-initialized Realtime Database instance
  database?: any;

  // URL or stream source to play by default (optional) — widget may fallback to DB-provided stream
  defaultStreamUrl?: string;

  // Optional: show/hide controls
  showControls?: boolean; // default: true

  // Optional: callback when play state changes
  onPlay?: () => void;
  onPause?: () => void;
}

Comments:

• If both firebaseConfig and database are provided, database takes precedence.
• defaultStreamUrl is optional — many setups will store the current stream URL in Firebase and the widget reads it live.

7. Styling

Import the widget stylesheet in your top-level component or inside the component that uses the widget:

import "tal-live-radio-player/style.css";

You can override styles by targeting the widget's CSS classes from your app stylesheet. Prefer CSS variables if the widget exposes any — check the widget source for available variables.

8. Building & publishing notes

• Build the package with your preferred bundler (Rollup, Vite, or similar). Ensure react and firebase are marked as external/peer dependencies in your bundler config.
• Update package.json fields (main, module, types) and include the README when publishing to npm.

Example package.json snippet

{
  "name": "tal-live-radio-player",
  "version": "1.0.0",
  "main": "dist/index.cjs.js",    
  "module": "dist/index.esm.js",
  "peerDependencies": {
    "react": "^18.0.0",
    "react-dom": "^18.0.0",
    "firebase": "^9.0.0"
  }
}

9. Contributing

Contributions are welcome! Please open issues or pull requests in the GitHub repo. Include reproducible examples and indicate whether the issue is React-only or Next.js-specific.

10. License

Specify your license (e.g., MIT).

Final comments / checklist for README

• [ ] Verify prop names and behavior against the actual component source
• [ ] Make sure the styles file path (tal-live-radio-player/style.css) is accurate in the package's dist/ folder.
• [ ] Update examples to use the correct import paths used in your published package

If you want, I can also:

• Produce a README.md file ready for your npm package root (I can save it here), or
• Generate example source files (firebase helper, example components) as downloadable files.