fix: React hooks null reference error (#211)

* fix: resolve React hooks null reference error and update demo dependencies

This commit fixes the "Cannot read properties of null (reading 'useState')" error
that occurred when using the library with Next.js.

Changes:
- Updated Vite config to explicitly set jsxRuntime: 'automatic' for proper JSX transformation
- Updated demo to use Next.js 15.5.6 (from 14.2.33) for better React 19 support
- Updated demo React to 19.0.0 (from 18.2.0) to match library peer dependencies
- Added .eslintrc.json to demo for Next.js 15 ESLint compatibility

The root cause was a combination of:
1. Implicit JSX runtime configuration in Vite
2. Outdated Next.js version with React version mismatch
3. Module resolution issues between the library build and Next.js runtime

The fix ensures:
- Proper React externalization in the library build
- Compatible versions across the demo stack
- Correct JSX transformation for library consumers

Tested with:
- npm run build (library): ✅ Successful
- npm run build (demo): ✅ Successful (3/3 pages generated)
- React hooks now properly resolve at runtime

* docs: document local library development workflow in CONTRIBUTING.md

Added comprehensive "Development Setup" section to explain:
- Repository structure (library root + demo/ folder)
- How the demo uses `file:..` to reference the local library
- Complete getting started guide for new contributors
- Step-by-step workflow for making and testing changes
- Important notes about the local development approach

This documentation helps contributors understand:
- Why demo uses `file:..` instead of the published npm version
- How to test library changes in the demo before publishing
- The rebuild workflow required when modifying library source

Related to the React hooks null error fix, this ensures contributors
know how to properly set up and test the local development environment.

* refactor: switch demo to use published npm package by default

Changes the demo application to use the published "react-lite-youtube-embed"
package instead of the local build, while documenting how contributors can
switch to local development mode when needed.

Changes:
- Updated demo/package.json to use "react-lite-youtube-embed": "*"
- Updated all imports from "@ibrahimcesar/react-lite-youtube-embed" to "react-lite-youtube-embed"
- Updated next.config.js transpilePackages to use new package name
- Rewrote CONTRIBUTING.md Development Setup section:
  - Demo uses published package by default (showcases what users install)
  - Added instructions for switching to local dev with "file:.." when testing changes
  - Emphasized reverting to published package before committing
  - Clearer workflow: getting started, running demo, local development, testing

Why this change:
- Demo showcases the actual package users will install from npm
- Contributors can still test locally by temporarily using "file:.."
- Ensures demo always represents the published user experience
- Reduces confusion about which version is being used

Local development workflow:
1. Change package.json to use "file:.." when testing library changes
2. Always revert to "react-lite-youtube-embed": "*" before committing

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: ibrahimcesar

CONTRIBUTING.md

@@ -1,93 +1,146 @@
 # Contributing
 
 When contributing to this repository, please first discuss the change you wish to make via issue,
-email, or any other method with the owners of this repository before working on a change. 
+email, or any other method with the owners of this repository before working on a change.
 
 Please note we have a code of conduct, please follow it in all your interactions with the project.
 
-## Local Development and Testing
+## Development Setup
 
-### Setting Up Your Development Environment
+### Repository Structure
 
-1. **Clone the repository and install dependencies:**
+This is a monorepo containing:
+- **Root** - The library package (`react-lite-youtube-embed`)
+- **demo/** - Next.js demo application showcasing the library
+
+### Getting Started
+
+1. **Clone the repository:**
+   ```bash
+   git clone https://github.com/ibrahimcesar/react-lite-youtube-embed.git
+   cd react-lite-youtube-embed
+   ```
+
+2. **Install library dependencies:**
    ```bash
    npm install
    ```
 
-2. **Build the library:**
+3. **Build the library:**
    ```bash
    npm run build
    ```
-   This creates the distributable files in the `dist/` directory.
+   This creates the `dist/` folder with the built library files.
+
+4. **Run tests:**
+   ```bash
+   npm test
+   ```
 
-### Testing Your Changes in the Demo App
+5. **Check coverage:**
+   ```bash
+   npm run coverage
+   ```
 
-The demo app is already configured to use the local package via `"file:.."` in its `package.json`. Here's how to test your changes:
+### Running the Demo
 
-#### One-Time Setup
+The demo application uses the **published npm package** by default:
 
-1. **Navigate to the demo directory:**
-   ```bash
-   cd demo
+```json
+// demo/package.json
+{
+  "dependencies": {
+    "react-lite-youtube-embed": "*"
+  }
+}
+```
+
+To run the demo:
+
+```bash
+cd demo
+npm install
+npm run dev
+```
+
+The demo will be available at `http://localhost:3000`
+
+### Local Development Workflow
+
+When you need to test library changes in the demo **before publishing**, switch to local development mode:
+
+1. **Update demo/package.json:**
+   ```json
+   {
+     "dependencies": {
+       "react-lite-youtube-embed": "file:.."
+     }
+   }
    ```
 
-2. **Install demo dependencies:**
+2. **Reinstall demo dependencies:**
    ```bash
+   cd demo
+   rm -rf node_modules package-lock.json
    npm install
    ```
    This will automatically link to your local package (in the parent directory).
 
-#### Testing Workflow
+3. **Testing Workflow - Method 1: Build and Test (Recommended for Final Testing)**
 
-**Method 1: Build and Test (Recommended for Final Testing)**
-
-1. **Build the library** (from the root directory):
+   a. **Build the library** (from the root directory):
    ```bash
    npm run build
    ```
 
-2. **Start the demo app** (from the `demo/` directory):
+   b. **Start the demo app:**
    ```bash
    cd demo
    npm run dev
    ```
 
-3. **View the demo:**
-   Open [http://localhost:3000](http://localhost:3000) in your browser.
-
-4. **Make changes and rebuild:**
+   c. **Make changes and rebuild:**
    - Make your changes to the library source files in `src/`
    - Run `npm run build` from the root directory
    - Refresh your browser to see the changes
 
-**Method 2: Watch Mode (Recommended for Active Development)**
+4. **Testing Workflow - Method 2: Watch Mode (Recommended for Active Development)**
 
-For a faster development cycle, you can use Vite's build watch mode:
+   For a faster development cycle, you can use Vite's build watch mode:
 
-1. **Start the build watcher** (from the root directory):
+   a. **Start the build watcher** (from the root directory):
    ```bash
    npm run build -- --watch
    ```
    This rebuilds automatically whenever you save changes to source files.
 
-2. **In a separate terminal, start the demo app:**
+   b. **In a separate terminal, start the demo app:**
    ```bash
    cd demo
    npm run dev
    ```
 
-3. **Develop with hot reload:**
+   c. **Develop with hot reload:**
    - Edit files in `src/`
    - Vite automatically rebuilds the library
    - Next.js may require a manual browser refresh to pick up changes
 
-#### Verifying Your Changes
+**Important:** Before committing, revert `demo/package.json` back to using the published package:
+```json
+{
+  "dependencies": {
+    "react-lite-youtube-embed": "*"
+  }
+}
+```
+
+### Verifying Your Changes
 
 After making changes, always verify:
 
 1. **Run tests:**
    ```bash
-   npm run test
+   npm test
    ```
 
 2. **Check test coverage:**
@@ -96,29 +149,50 @@ After making changes, always verify:
    ```
    Ensure coverage remains at 100%.
 
-3. **Run linting:**
+3. **Build the library:**
+   ```bash
+   npm run build
+   ```
+
+4. **Run linting:**
    ```bash
    npm run lint
    ```
 
-4. **Check formatting:**
+5. **Check formatting:**
    ```bash
    npm run format:check
    ```
 
-5. **Type check:**
+6. **Type check:**
    ```bash
    npm run type-check
    ```
 
-6. **Run all checks at once:**
+7. **Run all checks at once:**
    ```bash
    npm run ci
    ```
+   This runs linting, type checking, tests, and builds the project—ensuring your changes will pass CI checks.
+
+8. **Test the demo builds:**
+   ```bash
+   cd demo
+   npm run build
+   ```
+
+### Working with CSS
+
+If you modify styles in `src/lib/LiteYouTubeEmbed.css`:
+
+1. Rebuild the library: `npm run build`
+2. The CSS is automatically copied to `dist/LiteYouTubeEmbed.css`
+3. Refresh the demo app to see style changes
 
-#### Troubleshooting
+### Troubleshooting
 
 **Changes not appearing in the demo?**
+- Ensure you switched to local development mode (`"file:.."` in demo/package.json)
 - Ensure you ran `npm run build` after making changes
 - Try clearing Next.js cache: `cd demo && rm -rf .next && npm run dev`
 - Hard refresh your browser (Ctrl+Shift+R or Cmd+Shift+R)
@@ -133,23 +207,13 @@ After making changes, always verify:
 - Check TypeScript errors: `npm run type-check`
 - Clear dist folder: `rm -rf dist && npm run build`
 
-### Working with CSS
-
-If you modify styles in `src/lib/LiteYouTubeEmbed.css`:
-
-1. Rebuild the library: `npm run build`
-2. The CSS is automatically copied to `dist/LiteYouTubeEmbed.css`
-3. Refresh the demo app to see style changes
-
-### Before Submitting Your PR
-
-Make sure to run the full CI pipeline locally:
-
-```bash
-npm run ci
-```
+### Development Tips
 
-This runs linting, type checking, tests, and builds the project—ensuring your changes will pass CI checks.
+- **Library changes** require rebuilding (`npm run build`) to take effect in the demo
+- **Always revert** `demo/package.json` to use the published package before committing
+- The demo showcases the **published version** that users actually install
+- Use `file:..` only temporarily for local testing during development
+- Use watch mode (`npm run build -- --watch`) for faster iteration during active development
 
 ## Pull Request Guidelines
 

demo/.eslintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": ["next/core-web-vitals"]
+}

demo/next.config.js

@@ -11,6 +11,6 @@ const nextConfig = {
     unoptimized: true,
   },
   // Transpile local package to ensure React imports work correctly
-  transpilePackages: ['@ibrahimcesar/react-lite-youtube-embed'],
+  transpilePackages: ['react-lite-youtube-embed'],
 }
 module.exports = nextConfig