react-nextjs-adsense

A modern React component library for seamlessly integrating Google AdSense into your Next.js applications, with built-in ethical content filtering.

Demo: https://toolcluster.com/adsense-demo

Why Choose react-nextjs-adsense?

• Effortless Integration: Simple, declarative API designed specifically for Next.js apps
• Ethical Advertising: Built-in Islamic content filtering to ensure your ads align with ethical standards
• Developer-Friendly: Comprehensive TypeScript support and intuitive props
• Performance Optimized: Minimizes impact on your site's loading speed and user experience

Getting Started

Installation

Choose your preferred package manager:

# Using npm
npm install react-nextjs-adsense

# Using yarn
yarn add react-nextjs-adsense

# Using pnpm
pnpm add react-nextjs-adsense

Quick Start

Adding AdSense to your Next.js application is as simple as:

import { AdSense } from 'react-nextjs-adsense';

function HomePage() {
  return (
    <div className="content">
      <h1>Welcome to My Site</h1>
      <p>Valuable content for my visitors</p>
      
      {/* Add your AdSense ad unit */}
      <AdSense
        client="ca-pub-XXXXXXXXXXXXXXXX"  // Your AdSense Publisher ID
        slot="1234567890"                 // Your AdSense Ad Unit ID
      />
    </div>
  );
}

That's it! Your AdSense ads will display with ethical content filtering automatically enabled.

Component API

AdSense Props

| Prop | Type | Required | Default | Description | |------|------|:--------:|---------|-------------| | client | string | ✓ | - | Your Google AdSense publisher ID (format: 'ca-pub-XXXXXXXXXXXXXXXX') | | slot | string | ✓ | - | Your AdSense ad unit ID | | format | string | - | 'auto' | Ad format specification (e.g., 'auto', 'rectangle', 'vertical') | | responsive | string | - | 'false' | Set to 'true' for responsive ads that adapt to container width | | layout | string | - | '' | Ad layout format for advanced configurations | | layoutKey | string | - | '' | Layout key for customized ad formats | | className | string | - | '' | Additional CSS class to style the ad container | | style | React.CSSProperties | - | { display: 'block' } | Inline styles for customizing ad appearance | | pageLevelAds | boolean | - | false | Enable Google's page-level ads | | adTest | string | - | undefined | Ad test mode parameter (for development use) | | useIslamicGuidelines | boolean | - | true | Enable ethical content filtering based on Islamic guidelines | | blockCategories | string[] | - | [] | Additional ad categories you want to block |

Ethical Content Filtering

Our library comes with a built-in ethical content filtering system based on Islamic guidelines, which is enabled by default. This means you don't need to configure anything to start benefiting from cleaner, more appropriate advertising on your site.

What Gets Filtered?

The filtering system automatically blocks over 30 potentially problematic ad categories, including:

• Dating and relationship services
• Gambling and betting
• Alcohol and tobacco products
• Adult and suggestive content
• Interest-based financial products
• Contentious political material
• And many more categories that may not align with ethical values

Customizing Content Filtering

While the default settings work well for most users, you can easily customize the filtering:

<AdSense
  client="ca-pub-XXXXXXXXXXXXXXXX"
  slot="1234567890"
  // Block additional categories beyond the defaults
  blockCategories={["fashion", "travel", "entertainment"]}
/>

Disabling Ethical Filtering

In specific cases where you need to disable the ethical filtering system:

<AdSense
  client="ca-pub-XXXXXXXXXXXXXXXX"
  slot="1234567890"
  useIslamicGuidelines={false}
/>

Integration Examples

With Next.js App Router (Next.js 13+)

// app/blog/[slug]/page.jsx
"use client";

import { AdSense } from 'react-nextjs-adsense';

export default function BlogPost() {
  return (
    <article className="blog-content">
      <h1>Blog Post Title</h1>
      
      {/* Top of article ad */}
      <AdSense
        client="ca-pub-XXXXXXXXXXXXXXXX"
        slot="1234567890"
        responsive="true"
        style={{ marginBottom: '2rem' }}
      />
      
      <div className="article-content">
        <p>Your valuable blog content here...</p>
      </div>
      
      {/* Bottom of article ad */}
      <AdSense
        client="ca-pub-XXXXXXXXXXXXXXXX"
        slot="9876543210"
        responsive="true"
        style={{ marginTop: '2rem' }}
      />
    </article>
  );
}

With Next.js Pages Router

// pages/index.js
import { AdSense } from 'react-nextjs-adsense';

export default function Home() {
  return (
    <div className="homepage">
      <header>
        <h1>Welcome to My Website</h1>
      </header>
      
      <main>
        <section className="featured-content">
          {/* Content here */}
        </section>
        
        <AdSense
          client="ca-pub-XXXXXXXXXXXXXXXX"
          slot="1234567890"
          format="auto"
          responsive="true"
        />
        
        <section className="more-content">
          {/* More content here */}
        </section>
      </main>
    </div>
  );
}

TypeScript Support

Our library includes comprehensive TypeScript definitions to enhance your development experience:

import { 
  AdSense, 
  HaramCategory, 
  HARAM_AD_CATEGORIES 
} from 'react-nextjs-adsense';

// Type-safe access to the default blocked categories
const defaultCategories: readonly HaramCategory[] = HARAM_AD_CATEGORIES;

// Your component with typed props
interface ContentSectionProps {
  showAds: boolean;
}

function ContentSection({ showAds }: ContentSectionProps) {
  return (
    <section>
      {showAds && (
        <AdSense
          client="ca-pub-XXXXXXXXXXXXXXXX"
          slot="1234567890"
          blockCategories={["fashion", "beauty"]}
        />
      )}
    </section>
  );
}

Best Practices

Performance Optimization

• Strategic Placement: Place ads where they won't disrupt your content flow
• Limit Ad Units: Don't overwhelm your users with too many ads on one page
• Responsive Design: Use responsive="true" to ensure ads look good on all devices

Maximizing Revenue While Maintaining Ethics

• Quality Content First: Focus on creating valuable content that attracts engaged users
• Ad Placement Testing: Experiment with different placements to find what works best
• Ethical Balance: Maintain a balance between monetization and user experience

Troubleshooting

If your ads aren't displaying:

1. Verify your AdSense account is approved and active
2. Double-check your client and slot values
3. Ensure you've added the AdSense script to your Next.js application
4. Check your browser console for any error messages

Support and Contribution

We welcome contributions and feedback! If you encounter issues or have suggestions for improvements, please open an issue on our GitHub repository.

🔗 Further Resources

• Official Google AdSense Documentation
• Google's Ad Category Controls
• Next.js Documentation

📄 License

MIT

👋 Contributing

We welcome contributions to improve this library! Please feel free to submit issues or pull requests.