Next Theme Toggle

A CLI tool that instantly sets up dark/light theme toggling in your Next.js projects + Tailwind CSS v4 with zero configuration hassle.

Features

• One command setup - Get theme switching working in seconds
• Tailwind CSS v4 - Automatically installs/upgrades to latest Tailwind
• TypeScript & JavaScript - Full support for both
• Smooth transitions - Elegant animations between themes
• Smart theme toggle - Uses next-themes for system preference detection
• Responsive design - Works perfectly on mobile and desktop
• Non-destructive - Only adds new files and overwrite few existing files
• Smart detection - Automatically detects your project structure
• Custom components - Includes Header, ThemeToggle, and ExampleCard
• Modern styling - Uses system preferences with manual override
• Zero configuration - Works out of the box

Quick Start

Prerequisites

• Node.js 16+
• A Next.js project (App Router - recommended)
• npm, yarn, or pnpm

Dependencies

• next-themes - Theme switching logic
• lucide-react - Icons for sun/moon
• tailwindcss@latest - Styling (v4+)

Installation & Usage

Option 1: Direct execution (Recommended)

npx next-theme-toggle

Option 2: Install then run

npm i next-theme-toggle

next-theme-toggle

Watch Demo

next-theme-toggle-demo-video.mp4

Expected Output

Scenario 1: Fresh Tailwind CSS Installation

🚀 Setting up Next.js theme toggle...

√ Next.js project detected
[i] Using npm package manager
[i] Installing Tailwind CSS dependencies:
  - tailwindcss
  - @tailwindcss/postcss
  - postcss

√ Packages installed: tailwindcss, @tailwindcss/postcss, postcss
√ Created postcss.config.mjs with Tailwind CSS v4 configuration
√ Complete globals.css copied from template to src\app\globals.css

[i] Installing dependencies:
  - lucide-react
  - next-themes

√ Packages installed: lucide-react, next-themes
√ Dependencies installed successfully

[i] Using app directory: src/app

√ Successfully created component 'ThemeToggle.tsx' in src/app/components
√ Successfully created component 'Header.tsx' in src/app/components/layout
√ Successfully created component 'ExampleCard.tsx' in src/app/components
√ Successfully overwritten layout.tsx in src/app with ThemeProvider
√ Successfully overwritten page.tsx in src/app

Theme toggle setup complete!

Scenario 2: Existing Tailwind CSS Setup

🚀 Setting up Next.js theme toggle...

√ Next.js project detected
[i] Using npm package manager
√ Tailwind CSS v4+ already installed

√ Custom theme styles appended to src\app\globals.css

[i] Installing dependencies:
  - lucide-react
  - next-themes

√ Packages installed: lucide-react, next-themes
√ Dependencies installed successfully

[i] Using app directory: src/app

√ Successfully created component 'ThemeToggle.tsx' in src/app/components
√ Successfully created component 'Header.tsx' in src/app/components/layout
√ Successfully created component 'ExampleCard.tsx' in src/app/components
√ Successfully overwritten layout.tsx in src/app with ThemeProvider
√ Successfully overwritten page.tsx in src/app

Theme toggle setup complete!

That's it! The tool will automatically:

• Detect your package manager (npm/yarn/pnpm)
• Verify you're in a Next.js project
• Install/upgrade Tailwind CSS to v4
• Inject Tailwind directives into your CSS
• Install required dependencies (next-themes, lucide-react)
• Create theme toggle components
• Set up your layout with ThemeProvider
• Update your layout and page files
• Configure CSS with smooth transitions

What Gets Created

Components Structure

src/app/components/          # or app/components/
├── layout/
│   └── Header.tsx          # Navigation with theme toggle
├── ExampleCard.tsx         # Sample card component
└── ThemeToggle.tsx         # The magic toggle button

• components/ThemeToggle.tsx - The theme toggle button
• components/layout/Header.tsx - Header component with the toggle
• components/ExampleCard.tsx - Example Card component

Updated Files

• layout.tsx - Wrapped with ThemeProvider
• page.tsx - Updated with new components
• globals.css - add custom css varient and smooth transition effect
• postcss.config.mjs - Configured for Tailwind v4

Manual Integration

After running the command, your components are ready to use:

// In your layout.tsx (automatically done)
import { ThemeProvider } from "next-themes";

export default function RootLayout({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider
          attribute="data-theme"
          defaultTheme="system"
          enableSystem
        >
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}

// In your page.tsx or any component
import Header from "@/app/components/layout/Header";
import ExampleCard from "@/app/components/ExampleCard";

export default function HomePage() {
  return (
    <div>
      <Header />
      <main className="container mx-auto px-4 py-8">
        <ExampleCard />
      </main>
    </div>
  );
}

Command Options

# Default installation
npx next-theme-toggle

# Skip Tailwind CSS setup (if you have custom setup)
npx next-theme-toggle --no-tailwind
# or
npx next-theme-toggle -T

Customization

Theme Colors

The tool creates CSS variables you can customize in globals.css:

:root {
  --background: #ffffff;
  --foreground: #171717;
}

@media (prefers-color-scheme: dark) {
  :root {
    --background: #0a0a0a;
    --foreground: #ededed;
  }
}

Component Styling

All components use Tailwind classes and can be easily customized:

// Example: Customize the theme toggle button
<button className="your-custom-classes">{/* Theme toggle content */}</button>

Troubleshooting

Common Issues

Theme not working?

• Make sure Tailwind's dark: classes are in your CSS
• Check that ThemeProvider wraps your app in layout.tsx

Components not found?

• Verify the components are copied to your components folder
• Check your import paths match your project structure

"No package.json found"

• Make sure you're in your Next.js project root directory

"This doesn't appear to be a Next.js project"

• Ensure Next.js is installed in dependencies or devDependencies

Tailwind styles not working

• Make sure your postcss.config.mjs includes @tailwindcss/postcss
• Restart your dev server after installation

Still having issues?

• Make sure you're running npm run dev after setup
• Check console for any import/export errors

Manual Path Configuration

If path aliases don't work, update your imports:

// Instead of @/app/components/...
import ThemeToggle from "./components/ThemeToggle";
import Header from "./components/layout/Header";

Contributing

We love contributions! Issues and PRs welcome! This tool is designed to be simple and focused - let's keep it that way. Here's how to get started:

Development Setup

1. Fork & Clone

   git clone https://github.com/megh-bari/next-theme-toggle.git
   cd next-theme-toggle

2. Install Dependencies

   npm install

3. Test Locally

   # Link for local testing
   npm link (try running this command in the terminal as an administrator)
   
   # Test in a Next.js project
   cd /path/to/your-nextjs-project
   npm link next-theme-toggle
   next-theme-toggle

Making Changes

1. Create a Feature Branch

   git checkout -b feature/amazing-feature

2. Make Your Changes

   • Update the main script in index.js
   • Add/modify templates in templates/ directory
   • Update tests if applicable

3. Test Your Changes

   # Test with different Next.js setups
   npm run test
   
   # Test with TypeScript projects
   # Test with JavaScript projects
   # Test with different app structures (src/app vs app)

4. Commit & Push

   git add .
   git commit -m "feat: add amazing feature"
   git push origin feature/amazing-feature

5. Create Pull Request

   • Provide clear description of changes
   • Include screenshots if UI changes
   • Link any related issues

Contribution Guidelines

Bug Reports

• Use the bug report template
• Include Node.js and Next.js versions
• Provide minimal reproduction steps
• Include error messages and logs

Feature Requests

• Use the feature request template
• Explain the use case and benefits
• Consider backward compatibility
• Provide implementation ideas if possible

Code Standards

• Follow existing code style
• Add comments for complex logic
• Update documentation for new features
• Include error handling
• Test with both TypeScript and JavaScript projects

Testing

Before submitting:

• Test with fresh Next.js project
• Test with existing Tailwind setup
• Test with both src/app and app structures
• Test with npm, yarn, and pnpm
• Verify all generated files work correctly

Project Structure

next-theme-toggle/
├── templates/              # Component templates
│   ├── app/
│   │   ├── layout.tsx
│   │   ├── layout.js
│   │   ├── page.tsx
│   │   └── page.js
│   ├── components/
│   │   ├── layout/
│   │   │   ├── Header.tsx
│   │   │   └── Header.jsx
│   │   ├── ExampleCard.tsx
│   │   ├── ExampleCard.jsx
│   │   ├── ThemeToggle.tsx
│   │   └── ThemeToggle.jsx
│   └── globals.css
├── index.js               # Main CLI script
├── package.json
└── README.md

Release Process

1. Update version in package.json
2. Update CHANGELOG.md
3. Create release tag
4. Publish to npm

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Next.js for the amazing React framework
• Tailwind CSS for utility-first styling
• next-themes for theme management
• Lucide for beautiful icons

Stats

• ⭐ Star this repo if it helped you!
• 🐛 Report issues on GitHub Issues
• 💡 Request features on GitHub Discussions

---

Built By

• Twitter: @meghtrix
• GitHub: @megh-bari

Happy theming!