Light Dark System

Integrating with NextJS

This page explains how to integrate Pure UI with a NextJS app.

There are 2 guides available:

Usage with App Router (NextJS 14)

  • Node: v20.11.1
  • NextJS: 14.2.4
  • Pure UI: 2.15.1

Working with ESM

If you haven’t already, create your NextJS app. You can find the documentation for that here: https://nextjs.org/docs/getting-started/installation

After you’ve created your app, the first step to using Pure UI is modifying your package.json to have "type": "module" in it since Pure UI ships ES Modules. 

// package.json
{
  "type": "module"
}

Installing packages

To get started using Pure UI with NextJS, the following packages must be installed.

npm install pure-uikit copy-webpack-plugin

Pure UI for obvious reasons, and the copy-webpack-plugin will be used later for adding our icons to our public/ folder.

Modifying your Next Config

We’ll start with modifying our next.config.js to copy Pure UI’s assets and to properly work with ESM.

Here’s what your next.config.js should look like:

NextJS 14 Webpack Config

In order to add Pure UI’s assets to the final build output, we need to modify next.config.js to look like this. 

// next.config.js

import { dirname, resolve } from "path";
import { fileURLToPath } from "url";
import CopyPlugin from "copy-webpack-plugin";

const __dirname = dirname(fileURLToPath(import.meta.url));

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: { esmExternals: "loose" },
  webpack: (config, options) => {
    config.plugins.push(
      new CopyPlugin({
        patterns: [
          {
            from: resolve(__dirname, "node_modules/pure-uikit/dist/assets/"),
            to: resolve(__dirname, "public/pure-ui-assets/assets/"),
          },
        ],
      }),
    );
    return config;
  },
};

export default nextConfig;

Importing the Pure UI’s CSS (default theme)

Once we’ve got our webpack config / next config setup, lets modify our app/layout.tsx to include Pure UI’s default theme. 

// app/layout.tsx
import "./globals.css";
import "pure-uikit/dist/themes/light.css";
// We can also import the dark theme here as well.
// import "pure-uikit/dist/themes/dark.css";

Writing a “setup” component

Now, we need to create a Pure UISetup component that will be a client component in charge of setting the basePath for our assets / icons.

To do so, create a file called app/pure-ui-setup.tsx

'use client';
// ^ Make sure to have 'use client'; because `setBasePath()` requires access to `document`.

import { setBasePath } from "pure-uikit/dist/utilities/base-path.js"

export default function Pure UISetup({
  children,
}: {
  children: React.ReactNode
}) {
  setBasePath(`/pure-ui-assets/`);
  return <>{children}</>
}

Then we’ll add this setup component into app/layout.tsx

Our layout.tsx Should now look something like this:

import type { Metadata } from "next";
import { Inter } from "next/font/google";
import "./globals.css";
+ import "pure-uikit/dist/themes/light.css";

+ import Pure UISetup from "./pure-ui-setup";

const inter = Inter({ subsets: ["latin"] });

export const metadata: Metadata = {
  title: "Create Next App",
  description: "Generated by create next app",
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body className={inter.className}>
+         <Pure UISetup>
            {children}
+         </Pure UISetup>
      </body>
    </html>
  );
}

Writing components that use Pure UI

Now that we have the setup in place, we can write an app/page.tsx to use Pure UI components in combination with the dynamic() component loader from NextJS.

Here’s what that would look like, do note the "use client"; at the top of the component is required. 

// app/page.tsx
'use client';

import React from "react";
import dynamic from "next/dynamic";

const SlButton = dynamic(
  // Notice how we use the full path to the component. If you only do `import("pure-uikit/dist/react")` you will load the entire component library and not get tree shaking.
  () => import("pure-uikit/dist/react/button/index.js"),
  {
    loading: () => <p>Loading...</p>,
    ssr: false,
  },
);

const SlIcon = dynamic(
  () => import("pure-uikit/dist/react/icon/index.js"),
  {
    loading: () => <p>Loading...</p>,
    ssr: false,
  },
);

export default function Home() {
  return (
    <main>
      <SlButton>Test</SlButton>
      <SlIcon name="gear" />
    </main>
  );
}

Now you should be up and running with NextJS + Pure UI!

If you’re stuck, there’s an example repo here you can checkout.

Usage with Pages Router (NextJS 12)

  • Node: 16.13.1
  • NextJS: 12.1.6
  • Pure UI: 2.0.0-beta.74

To get started using Pure UI with NextJS, the following packages must be installed.

yarn add pure-uikit copy-webpack-plugin next-compose-plugins next-transpile-modules

Enabling ESM

Because Pure UI utilizes ESM, we need to modify our package.json to support ESM packages. Simply add the following to your root of package.json: 

"type": "module"

There’s one more step to enable ESM in NextJS, but we’ll tackle that in our Next configuration modification.

Importing the Default Theme

The next step is to import Pure UI’s default theme (stylesheet) in your _app.js file:

import 'pure-uikit/dist/themes/light.css';

Defining Custom Elements

After importing the theme, you’ll need to import the JavaScript files for Pure UI. However, this is a bit tricky to do in NextJS thanks to the SSR environment not having any of the required browser APIs to define endpoints.

We’ll want to create a component that uses React’s useLayoutEffect to add in the custom components before the first render: 

function CustomEls({ URL }) {
  // useRef to avoid re-renders
  const customEls = useRef(false);

  useLayoutEffect(() => {
    if (customEls.current) {
      return;
    }

    import("pure-uikit/dist/utilities/base-path").then(({ setBasePath }) => {
      setBasePath(`${URL}/static/static`);

      // This imports all components
      import("pure-uikit/dist/react");
      // If you're wanting to selectively import components, replace this line with your own definitions

      // import("pure-uikit/dist/components/button/button");
      customEls.current = true;
    });
  }, [URL, customEls]);

  return null;
}

You may be wondering where the URL property is coming from. We’ll address that in the next few sections.

Using Our New Component In Code

While we need to use useLayoutEffect for the initial render, NextJS will throw a warning at us for trying to use useLayoutEffect in SSR, which is disallowed. To fix this problem, we’ll conditionally render the CustomEls component to only render in the browser 

function MyApp({ Component, pageProps, URL }) {
  const isBrowser = typeof window !== "undefined";
  return (
    <>
      {isBrowser && <CustomEls URL={URL} />}
      <Component {...pageProps} />
    </>
  );
}

Additional Resources