Adding jQuery to a Next.js Project – A Comprehensive Guide

Introduction

Next.js is a powerful React framework used for building modern web applications with server-side rendering (SSR), static site generation (SSG), and API routes. While Next.js encourages the use of React’s built-in capabilities, there are cases where you might need to integrate jQuery into a Next.js project, especially when working with legacy code, existing jQuery plugins, or third-party libraries.

In this detailed guide, we will cover how to properly add jQuery to a Next.js project, different methods to integrate it, and best practices to ensure smooth functionality.

---

Table of Contents

1. Why Use jQuery in a Next.js Project?
2. Installing jQuery in a Next.js Project
3. Using jQuery in Next.js Components
4. Loading jQuery via a CDN in Next.js
5. Using jQuery Plugins in Next.js
6. Handling jQuery with Next.js SSR and Client-side Rendering
7. Avoiding Common Issues with jQuery in Next.js
8. Optimizing jQuery in Next.js for Performance
9. Alternative Approaches Without jQuery
10. Conclusion

---

1. Why Use jQuery in a Next.js Project?

Although Next.js is primarily designed for React-based development, there are a few scenarios where integrating jQuery can be beneficial:

✅ Legacy Code Compatibility – If you’re migrating a legacy project that already uses jQuery, it’s easier to integrate it into Next.js rather than rewrite everything in React.
✅ Third-party jQuery Plugins – Some external libraries, such as DataTables, jQuery UI, or Bootstrap jQuery plugins, still require jQuery.
✅ Quick DOM Manipulations – If you need to make quick DOM manipulations without React state management, jQuery can be helpful.
✅ AJAX Requests – While Fetch API and Axios are preferred, some older APIs or systems may rely on jQuery’s AJAX methods.

However, avoid using jQuery for core application logic in Next.js, as React’s declarative approach is more efficient.

---

2. Installing jQuery in a Next.js Project

The first step is to install jQuery as a dependency in your Next.js project.

Step 1: Create a Next.js Project

If you haven’t already created a Next.js project, you can set one up using:

npx create-next-app my-nextjs-app
cd my-nextjs-app

Step 2: Install jQuery via npm

Run the following command inside your Next.js project:

npm install jquery

or using yarn:

yarn add jquery

This will add jQuery to your project’s node_modules.

---

3. Using jQuery in Next.js Components

Now that jQuery is installed, let’s see how to use it inside a Next.js component.

Step 1: Import jQuery in a Component

Next.js uses server-side rendering (SSR) by default, which means that we need to ensure jQuery is only accessed on the client side. The best way to do this is by using the useEffect hook from React.

Example: Using jQuery Inside a Component

Create a new file components/JQueryComponent.js:

import { useEffect } from "react";
import $ from "jquery"; // Import jQuery

const JQueryComponent = () => {
  useEffect(() => {
    $("#clickMe").on("click", function () {
      $("#text").toggle();
    });

    return () => {
      $("#clickMe").off("click"); // Clean up event listener
    };
  }, []);

  return (
    <div>
      <button id="clickMe">Click Me</button>
      <p id="text" style={{ display: "none" }}>Hello, this text is toggled by jQuery!</p>
    </div>
  );
};

export default JQueryComponent;

Step 2: Use This Component in a Page

Modify pages/index.js to include this component:

import JQueryComponent from "../components/JQueryComponent";

export default function Home() {
  return (
    <div>
      <h1>Using jQuery in Next.js</h1>
      <JQueryComponent />
    </div>
  );
}

How It Works

• The useEffect hook ensures jQuery runs only after the component mounts.
• $("#clickMe").on("click", function() {...}) adds an event listener using jQuery.
• $("#clickMe").off("click") cleans up the event listener to prevent memory leaks.

---

4. Loading jQuery via a CDN in Next.js

Instead of installing jQuery via npm, you can include it via a CDN inside your _document.js file.

Step 1: Modify _document.js to Include jQuery

Inside pages/_document.js, add the following:

import { Html, Head, Main, NextScript } from "next/document";

export default function Document() {
  return (
    <Html>
      <Head>
        <script
          src="https://code.jquery.com/jquery-3.6.0.min.js"
          integrity="sha384-KyZXEAg3QhqLMpG8r+Knujsl5+5hb7aZZF9HB4M4F++OY5CZey0v9VV4xk5kaGJ5"
          crossOrigin="anonymous"
          defer
        ></script>
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

This method ensures that jQuery is loaded globally before your Next.js app runs.

---

5. Using jQuery Plugins in Next.js

Some jQuery plugins require jQuery to be available globally. To load a plugin, follow these steps:

Step 1: Install a jQuery Plugin

For example, install jquery-ui:

npm install jquery-ui

Step 2: Use It in a Component

Modify components/JQueryComponent.js:

import { useEffect } from "react";
import $ from "jquery";
import "jquery-ui/ui/widgets/datepicker"; // Import the datepicker widget

const JQueryComponent = () => {
  useEffect(() => {
    $("#datePicker").datepicker(); // Initialize datepicker
  }, []);

  return (
    <div>
      <input type="text" id="datePicker" placeholder="Select a date" />
    </div>
  );
};

export default JQueryComponent;

---

6. Handling jQuery with Next.js SSR and Client-side Rendering

Since Next.js supports server-side rendering (SSR), jQuery might cause issues if accessed before the document is available.

Solution: Use useEffect

Always wrap jQuery code inside useEffect:

useEffect(() => {
  if (typeof window !== "undefined") {
    $("#element").hide();
  }
}, []);

---

7. Avoiding Common Issues with jQuery in Next.js

🚨 “$ is not defined” error – Ensure jQuery is imported correctly:

import $ from "jquery";

🚨 jQuery is not working inside components – Wrap jQuery code inside useEffect().
🚨 Plugin dependency issues – Use dynamic imports or load via CDN.

---

8. Optimizing jQuery in Next.js for Performance

✅ Use jQuery only where necessary and prefer React’s built-in methods.
✅ Load jQuery only on specific pages instead of globally.
✅ Remove event listeners inside useEffect cleanup.

---

9. Alternative Approaches Without jQuery

If possible, use React hooks and vanilla JavaScript instead of jQuery.

Example: jQuery vs React for Toggling Visibility 🔴 jQuery Approach

$("#button").click(function() {
  $("#text").toggle();
});

✅ React Approach

const [visible, setVisible] = useState(false);

return (
  <button onClick={() => setVisible(!visible)}>Toggle</button>
  {visible && <p>Hello!</p>}
);

---

• jQuery can be used inside Next.js, but should be limited to specific cases.
• Use React hooks for better performance.
• Always wrap jQuery inside useEffect.
• Consider using CDNs for faster load times.

Would you like more examples or troubleshooting tips?