DEV Community: Mykhaylo Ryechkin 🇺🇦

All about React Server Components

Mykhaylo Ryechkin 🇺🇦 — Wed, 04 Oct 2023 20:33:00 +0000

Intro

React Server Components are a new concept in the React ecosystem, and if you're wondering what all the fuss is about, then this article is for you.

So... what are React Server Components anyway?

Background

React Server Components (often referred to as just Server Components or RSC) are a new paradigm coming to the React ecosystem, and signify what can be thought of as the 3rd Age of React - where there is a significant shift in how we write and architect our React code. The last time this happened was with introduction of hooks in function components.

Server Components introduce a new way to architect React applications and libraries, and bring along a signficant change to our React mental model and how we think about a React component's lifecycle.

You see, through most of React's lifetime (up until recently), the majority of applications built with it were what we consider client-side. Let's call this era "the age of client-side React". This is every app that was built with the create-react-app scaffold (now legacy), or a myriad of other custom Webpack configurations since React's inception.

This is your typical app where you have a <div id="root"> in your root HTML page, and your entire application bundle (including React itself) is shipped to the browser:

<!-- index.html -->
<!doctype html>
<html lang="en">
  <head>
    <!-- ... -->
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/dist/bundle.js"></script>
  </body>
</html>

When the browser loads that page, your application is initialized and React renders it into that root element using React DOM. From there, your application runs on the client side (meaning in the browser). This includes things like routing when using libraries like React Router.

This means that the browser needs to download all of the code necessary to render a particular page, and that carries a performance cost. Now, there are techniques like code-splitting to help mitigate the bundle size needed for a particular page, but that only takes you so far. At the end of the day there is still code that the browser needs to download, and then subsequently run, in order to get the final HTML output.

With Server Components, a server can do a lot of that work before sending a response to the browser - and have React do all the rendering entirely on the server. The resulting HTML is then streamed into the browser, which it knows exactly what to do with.

NOTE: In reality, it's more complex than that - but we'll keep it simple for the purposes of this explanation. See Further Reading for a list of much more detailed explanations.

But wait, isn't that called "server-side rendering"? Well, not quite.

Server-Side Rendering (SSR) and RSC

When a React app runs on the client, the first thing a user will see is a blank screen. That's because the initial HTML is just an empty <div> element, and React hasn't had a chance to render anything yet. We see a result on the screen only once the browser downloads the JavaScript bundle, and React initializes the app. Depending on the network speed, application bundle size and other factors, this may take a varying amount of time. That's not the greatest user experience.

Server-Side Rendering (or "SSR") is a way to address this problem. It is a mechanism through which a server can "pre-render" React components before the result is sent to the browser. The catch is, in order for these components to be fully interactive and work as expected, they need to be "hydrated" on the client - so the server needs to send an additional payload alongside the HTML for it to fully work. Additionally, SSR only happens on the initial page load.

Prior to Server Components, all React components were considered "client" components, because they all run in the browser (ie. the "client"). So even though SSR gives us pre-rendering of the static HTML, our React components aren't truly finished rendering until they've run on the client.

With RSC, that all changes. Server Components render entirely on the server. The result of this render is a special data format called the React Server Component Payload (or RSC Payload).

What is the React Server Component Payload (RSC)?

The RSC Payload is a compact binary representation of the rendered React Server Components tree. It's used by React on the client to update the browser's DOM. The RSC Payload contains:

The rendered result of Server Components

Placeholders for where Client Components should be rendered and references to their JavaScript files

Any props passed from a Server Component to a Client Component

Source: Next.js Docs

In the case of Next.js, the RSC Payload is then used to pre-render the initial HTML to send to the browser, as well as make subsequent updates to the UI after the initial page render (triggered by a route change, for example).

Since RSC run on the server, they allow us to execute server-only code right there in body of the main rendering function:

function ServerComponent() {
  const db = new DB(); // connect directly to database
  // ...
  return <table>{/* show data */}</table>;
}

That includes all of your favourite Node methods. Want to read from the file system? No problem - Node's fs is readily available. You couldn't do this before in regular React components.

This comes with caveats, however, as Server Components aren't without their limitations. As mentioned earlier, for components to be fully interactive, they need to be hydrated on the client. So, any attempt to run code like this on the server will result in an error:

const ServerComponent = () => {
  function handleOnClick(event) {
    // ...
  }

  return <button onClick={handleOnClick}>Click Me</button>;
};

Additionally, Server Components can't run hooks and effects, so any attempt to useEffect or useState will also result in an error.

If a React component requires any of the above, it will need to be declared a Client Component.

Client Components

Client Components are just regular React components we all use and love - they're essentially what all React components were prior to the introduction of RSC. The name "Client Component" is simply to distinguish them from the new Server Components, and doesn't introduce anything new in itself.

To declare a component as a Client Component, we need to add a "use client" directive at the very top of the file:

'use client';

import { useEffect } from 'react';

// ...

const ClientComponent = () => {
  useEffect(() => {
    // ...
  }, []);

  function handleOnClick(event) {
    // this now works!
  }

  return <button onClick={handleOnClick}>Click Me</button>;
};

This will tell React to treat anything in this file as a Client Component, and it will work exactly as you would expect a regular React component to work.

Now, this entire mechanism requires some pretty deep integration with the bundler, since our app now crosses the client / server boundary. For this and other reasons, React team recommends using a metaframework like Next.js, Remix or others when starting a new React project.

Next.js and RSC

As of the writing of this article, Next.js is the only production-ready framework which supports RSC, and thus anything discussed here relating to React behaviour is within the context of Next.js implementation and handling of Server Components.

It's important to know that Next.js uses a special canary build of React (18.3 as of October 2023) to enable support of Server Components. Though many things are pretty well finalized on the Server Component API front, there may still be some changes introduced as React team finalizes this new paradigm, and other frameworks start to adopt RSC.

To use Server Components in Next.js, one must use the new App Router. As of Next 13.4, it's now the default when running create-next-app, so if you haven't tried it out yet - it's really easy to do.

Simply run:

npx create-next-app my-next-app

Server Component Characteristics

Server Components have a few characteristics and gotchas to be aware of (see the official RFC for more details):

Server Components can't use client-only features like event handlers, React context, state, hooks, and effects
Server Components run once per request on the server, which is why they can't support client-only features like event handlers and component state
Server Components can't use browser API's
Server Components can render other Server Components, Client Components and native HTML elements
Server Components can be asynchronous (you can use await in the body of the component):

  import db from 'db';

  async function ServerComponent({ id }) {
    const note = await db.posts.get(id);

    return (
      <div>
        <h1>{note.title}</h1>
        <section>{note.body}</section>
      </div>
    );
  }

It's also worthwhile to mention that using a "use client" directive will mark everything in that specific module as a Client Component. For that reason it's important to put Client Components in their own separate files.

Another characteristic to keep in mind is that unlike regular React Components, Server Components cannot dot into a Client module. What exactly does that mean?

Say we have a Client Component like this:

// src/components/Select.jsx
'use client';

const Select = () => {
  // ...
};

const Item = () => {
  // ...
};

export default Object.assign(Select, { Item });

This component exports the sub-component Item by including it together with the default export (via Object.assign()) of the Select.

Normally, that would allow us to use Item like this:

import { Select } from '@acme/components';
// ...
const App = () => {
  return (
    <Select>
      <Select.Item>Item 1</Select.Item>
      <Select.Item>Item 2</Select.Item>
      <Select.Item>Item 3</Select.Item>
    </Select>
  );
};

However, if we try this inside a Server Component:

// src/app/page.jsx
import { Select } from '@acme/components';
// ...
const App = () => {
  return (
    <Select>
      <Select.Item>Item 1</Select.Item>
      <Select.Item>Item 2</Select.Item>
      <Select.Item>Item 3</Select.Item>
    </Select>
  );
};

We'll run into an error:

Error: Cannot access .Item on the server. You cannot dot into a client module from a server component. You can only pass the imported name through.

This has to do with how Client Components are bundled for the browser, and the server / client boundary. Without going into specifics of the why (check out Further Reading for the nitty gritty) - to use this pattern we must denote the component as a Client Component, with the "use client" directive:

// src/app/page.jsx
'use client';

import { Select } from '@acme/components';
// ...
const App = () => {
  return (
    <Select>
      <Select.Item>Item 1</Select.Item>
      <Select.Item>Item 2</Select.Item>
      <Select.Item>Item 3</Select.Item>
    </Select>
  );
};

Now, everything will work as expected.

NOTE: If curious, there is an open issue right now to provide clarity from the Next.js team on this pattern.

Note on Client Components

As mentioned earlier, Client Components are basically just a fancy name for regular React components, prior to introduction of Server Components. However, there is one very important thing to keep in mind when it comes to using them alongside RSC.

Client Components cannot simply import Server Components - they must pass them along as serializable props. This means that the following won't work:

'use client';

import { createContext, useMemo } from 'react';
import ServerComponent from './ServerComponent';

const Context = createContext();

const ClientComponent = () => {
  const value = useMemo({
    // ...
  });

  return (
    <Context.Provider value={value}>
      <ServerComponent />
    </Context.Provider>
  );
};

Instead, pass the ServerComponent as a child (or another prop) to the ClientComponent:

'use client';

import { createContext, useMemo } from 'react';

const Context = createContext();

const ClientComponent = ({ children }) => {
  const value = useMemo({
    // ...
  });

  return <Context.Provider value={value}>{children}</Context.Provider>;
};

Why is this important? Well, since Server Components can run code that's only meant to be run on the server, they may very well include 3rd party packages or Node internals that cannot run in the browser. In addition, this would bloat the client bundle (as everything from the Server Component would need to be included) - which is one of the things we're trying to avoid in the first place.

It's a weird concept at first, but just remember it as a rule (kind of like we did with the rules of hooks).

Why should you care?

So now that we know what React Server Components are and their basic characteristics, the big question is: "Why should I care?".

Here are just some of the reasons:

Allows you to run server-side code and make API requests right in the body of the component (no more relying on useEffect to fetch the data)
Helps prevent client-side data fetching waterfalls by resolving data dependencies server-side
Server Components can be asynchronous, so you can use await directly in the component body
Having access to the server means you can access server secrets and use them in your React component, without exposing them to the client
Helps save on client bundle size, since there is no need to send a large chunk of additional JavaScript anymore
Allows you to keep the React component composition mental model, but apply it on the server
Enables Streaming and React Suspense - Server Components allow you to split the rendering work into chunks and stream them to the client as they become ready, allowing the user to see parts of the page earlier without having to wait for the entire page to be rendered on the server
Faster initial page load and First Contentful Paint (FCP), since the initial static HTML can be shown to the user right away, without waiting for the client to download, parse and execute the JavaScript needed to render the page
Improved SEO (Search Engine Optimization) - the rendered HTML can be used by search engine bots to index pages (as opposed to when everything is rendered on the client)

How to get started?

As mentioned earlier, as of the writing of this article (October 2023), the main way to get started with Server Components is through Next.js App Router.

Simply run npx create-next-app@latest my-app which will ask you a few questions and scaffold a new Next.js application. By default, the App Router is used (via the app folder). Now, any React components you write inside the app folder will be considered Server Components by default, unless the "use client" directive is present in the file.

One important thing to keep in mind is that the Root Layout in the src/app/layout.jsx file must be a Server Component. However, any of its children or nested layouts can be Client Components if needed.

Authentication in Next.js with Supabase Auth and PKCE

Mykhaylo Ryechkin 🇺🇦 — Tue, 08 Aug 2023 02:37:00 +0000

Background

Seems like just the other day I published an update to my original article on using Supabase Auth with Next.js, and yet here we are with the 3rd installment in the series.

So why another article? Well, as much as I was being a bit tongue-in-cheek about libraries changing all the time, it certainly seems to be the case with Supabase. Their Next.js Auth Helpers has recently undergone several significant updates, and they are worth talking about.

On the Next.js front, the app router is now stable in release 13.4, which means a lot more projects starting to use React Server Components. Having been spending more time with RSC's myself, I'm finding certain patterns to work well, and wanted to share how I've applied those in this project.

As the saying goes, "third time's the charm"? I sure hope so 😅

Overview

A few months ago Supabase introduced support for Proof Key for Code Exchange flow (or PKCE for short, pronounced "pixy").

PKCE provides applications with a more robust and secure authorization process, protecting against various types of attacks and vulnerabilities that can arise in public client environments.

The PKCE flow introduces a code verifier (a randomly generated secret) and a code challenge (the hash of the code verifier). The authorization code is returned as a query parameter so it's accessible on the server.

Learn more about Proof Key for Code Exchange authentication flow here

Alongside this came release 0.7.0 of the Next.js Auth Helpers library, which introduced some breaking changes in order to support the new PKCE flow.

In this article, I'm going to share with you the patterns I've landed on for using PKCE with Supabase Auth in Next.js 13+. The final solution ends up being much cleaner than the previous iteration, thanks to the recent updates in Supabase and the power of React Server Components.

As a recap (or if you're reading this for the first time), here is what we're building:

The project has two authenticated pages - Home and Profile. Unauthenticated users can Sign In, Sign Up, Reset Password and Update Password. All of this is powered by Next.js app router, with usage of both Client and Server Components, and Supabase handling all of the authentication related functionality. Forms are built using Formik and Yup for field validation.

Page Structure

Aiming to take full advantage of RSC's, I've decided to have each authentication flow have its own route (ie. /sign-in, /sign-up, /reset-password, etc.). This is different from the previous implementation, where the Home route (/) was rendering both authenticated and unauthenticated state.

One of the reasons for this is to have the Reset and Update Password flow work with PKCE. I've also found this approach to result in cleaner page code, without the extra logic for determining which view to show.

So, our page routes will be:

/ (authenticated Home page)
/profile (authenticated Profile page)
/sign-in (Sign In page)
/sign-up (Sign Up page)
/reset-password (Reset Password page)
/update-password (Update Password page)

Auth Forms

In the previous iteration of this guide, the individual auth forms were provided in a single <Auth /> component, which had some internal state and used a view prop for showing a specific form (or "view").

Since each authentication flow will now have its own unique route, there isn't really a need for this single <Auth /> component anymore. We can simply use the individual form components (<SignIn />, <SignUp />, etc.) instead:

// src/app/sign-in/page.js
import SignIn from 'src/components/Auth/SignIn';

export default async function SignInPage() {
  // ...
  return <SignIn />;
}

The individual auth form components can be found in GitHub. These were built using Formik, following one of their examples in the docs. See the previous post for more details.

Supabase Client

As mentioned earlier, the Supabase Auth Helpers library for Next.js release 0.7.0 brought with it some substantial changes. In particular, these changes affected how we create and use the Supabase Client. Let's take a look at what those are and how they affect our project structure.

Client Components

One of the big changes is that Client Component Supabase clients are now singleton instances, which was not the case before. Previously, we had to ensure that a single instance of Supabase was shared across Client Components. We did that using React Context and the AuthProvider component.

Now, thanks to the clients being singletons, we can simply import createClientSupabaseClient and call it wherever we need a Supabase instance (in a Client Component):

import { createClientSupabaseClient } from '@supabase/auth-helpers-nextjs';

export default function ClientComponent() {
  const supabase = createClientSupabaseClient();
  // ...
}

This results in much cleaner code in our Client Components, since we no longer need to keep track of the client-side session manually, allowing us to essentially ditch the provider pattern (well, almost... more on that below).

Server Components

When it comes to Server Components, the pattern is pretty much the same. Except the function is named createServerComponentClient, and we also need to pass it cookies from next/headers so it can properly store the session:

import { createServerComponentClient } from '@supabase/auth-helpers-nextjs';
import { cookies } from 'next/headers';

export default function ServerComponent() {
  const supabase = createServerComponentClient({ cookies });
  // ...
}

The above changes means that we no longer need to have a separate module for our Supabase clients like we did before, and can instead use the provided functions directly.

Auth Provider

In the previous version of this guide, we used React Context and the Provider pattern by wrapping our application in an AuthProvider component, to ensure that a single instance of Supabase client was being used by our Client Components:

// src/app/layout.js
export default async function RootLayout({ children }) {
  // ...

  return (
    <html lang="en">
      <body>
        {/*...*/}
        <AuthProvider>{children}</AuthProvider>
        {/*...*/}
      </body>
    </html>
  );
}

Thanks to the recent updates described above, that's no longer needed. But does that mean we can get rid of the AuthProvider completely? Well, not quite.

There is still a good reason to use it, and that's to trigger a router refresh whenever the current session changes. So long as we setup our pages to handle authenticated / unauthenticated state correctly, this will ensure that if a user signs out, they don't stay on the authenticated page, and similarly that they don't stay on an unauthenticated page after logging in. We'll see how to do that later on.

Handling auth state changes

To handle the above, we can listen to auth state changes inside a useEffect in the AuthProvider component, and trigger Next.js router.refresh() if the new session's access_token doesn't match the existing one:

// src/components/AuthProvider.js
'use client';

import { createContext, useEffect } from 'react';
import { createClientComponentClient } from '@supabase/auth-helpers-nextjs';
import { useRouter } from 'next/navigation';

export const AuthContext = createContext();

const AuthProvider = ({ accessToken, children }) => {
  const supabase = createClientComponentClient();
  const router = useRouter();

  useEffect(() => {
    const {
      data: { subscription: authListener },
    } = supabase.auth.onAuthStateChange((event, session) => {
      if (session?.access_token !== accessToken) {
        router.refresh();
      }
    });

    return () => {
      authListener?.unsubscribe();
    };
  }, [accessToken, supabase, router]);

  return children;
};

export default AuthProvider;

The accessToken is passed in from our root layout (src/app/layout.js), where we read access_token from the initial session, and pass it to the AuthProvider:

// src/app/layout.js
import { createServerComponentClient } from '@supabase/auth-helpers-nextjs';
import { cookies } from 'next/headers';

import AuthProvider from 'src/components/AuthProvider';

// ...

export default async function RootLayout({ children }) {
  const supabase = createServerComponentClient({ cookies });

  const {
    data: { session },
  } = await supabase.auth.getSession();

  const accessToken = session?.access_token || null;

  return (
    <html lang="en">
      <body>
        {/*...*/}
        <AuthProvider accessToken={accessToken}>{children}</AuthProvider>
        {/*...*/}
      </body>
    </html>
  );
}

Now, any time the session changes or becomes invalid, our application will refresh.

As mentioned earlier, in order for this to fully work, we will also need to add logic in each page to handle the specific scenario (ie. should the user be redirected to the Home or Sign In page?).

Protected Routes and Redirecting

Authenticated Pages

For the Home and Profile pages, we want to ensure that only authenticated users have access. For this, we can check if a user exists in the current session, and redirect to the /sign-in page if not:

// src/app/page.js

import { createServerComponentClient } from '@supabase/auth-helpers-nextjs';
import { cookies } from 'next/headers';
import { redirect } from 'next/navigation';

export default async function Home() {
  const supabase = createServerComponentClient({ cookies });

  const {
    data: { user },
  } = await supabase.auth.getUser();

  if (!user) {
    redirect('/sign-in');
  }

  // ...
}

Unauthenticated Pages

Similarly, we can ensure that the unauthenticated routes are only accessible if there is no current valid session:

// src/app/sign-in/page.js

import { createServerComponentClient } from '@supabase/auth-helpers-nextjs';
import { cookies } from 'next/headers';
import { redirect } from 'next/navigation';

import SignIn from 'src/components/Auth/SignIn';

export default async function SignInPage() {
  const supabase = createServerComponentClient({ cookies });
  const { data } = await supabase.auth.getSession();

  if (data?.session) {
    redirect('/');
  }

  return <SignIn />;
}

Here, we're checking for an existing session, and if one is found we redirect our user to the Home page.

Middleware and Refreshing Session

Next up, we need to ensure that the user's session does not time out or become stale, as outlined in the docs:

"When using the Supabase client on the server, you must perform extra steps to ensure the user's auth session remains active. Since the user's session is tracked in a cookie, we need to read this cookie and update it if necessary. Next.js Server Components allow you to read a cookie but not write back to it. Middleware on the other hand allow you to both read and write to cookies. Next.js Middleware runs immediately before each route is rendered. We'll use Middleware to refresh the user's session before loading Server Component routes."

To use Next.js Middleware, we'll need to create an src/middleware.js file at the root of our source folder (NOT the app, this is a common mistake!). In there we'll fetch the current session, and let Supabase client take care of updating the cookie.

Similar to Server and Client Components, there is a separate function to create Supabase client in Middleware called createMiddlewareClient. Add the following to src/middleware.js:

// src/middleware.js

import { createMiddlewareClient } from '@supabase/auth-helpers-nextjs';
import { NextResponse } from 'next/server';

export async function middleware(req) {
  const res = NextResponse.next();
  const supabase = createMiddlewareClient({ req, res });
  await supabase.auth.getSession();
  return res;
}

export const config = {
  matcher: ['/', '/profile'],
};

Note that we really only need this to run on authenticated routes, so we're using path matcher to ensure this code runs only for Home and Profile pages.

Setting up Code Exchange for PKCE flow

Supabase Auth supports two authentication flows: Implicit and PKCE.

The PKCE flow is what we're using in this guide, and is generally preferred when on the server. It introduces a few additional steps which guard against replay and URL capture attacks. Unlike the Implicit flow, it also allows users to access the access_token and refresh_token on the server.

The Next.js Auth Helpers are configured to use the PKCE auth flow as of version 0.7.0, and require us to setup a Code Exchange route in order to exchange an auth code for the user's session, which is set as a cookie for future requests made to Supabase.

NOTE
For security purposes, the code has a validity of 5 minutes and can only be exchanged for an access token once. You will need to restart the authentication flow from scratch if you wish to obtain a new access token.

To setup the code exchange, let's create a Route Handler at the /auth/callback route. Create a file src/app/auth/callback/route.js and add the following:

// src/app/auth/callback/route.js
import { createRouteHandlerClient } from '@supabase/auth-helpers-nextjs';
import { cookies } from 'next/headers';
import { NextResponse } from 'next/server';

export async function GET(request) {
  const requestUrl = new URL(request.url);
  const code = requestUrl.searchParams.get('code');

  if (code) {
    const supabase = createRouteHandlerClient({ cookies });
    await supabase.auth.exchangeCodeForSession(code);
  }

  // URL to redirect to after sign in process completes
  return NextResponse.redirect(requestUrl.origin);
}

Now anytime a user successfully signs in, Supabase will be able to store that session, and we'll have access to it through Supabase clients.

Setting up Auth Flows

Now that we have Supabase configured, the next piece of the puzzle is to hook up our auth forms to handle the relevant authentication flows: Sign In, Sign Up, Reset Password and Update Password.

All of the forms will follow a similar pattern. We'll let Formik handle all the form-related functionality (field validation, reading the form data), and on form submit we'll create a handler function:

async function handler(formData) {
  // ...
}

<Formik onSubmit={handler} {/*...*/}>

Sign In

For Sign In, we'll use email and password credentials, and the signInWithPassword method.

Add the following to the SignIn component:

// src/components/Auth/SignIn.js
// ...

const SignIn = () => {
  const supabase = createClientComponentClient();
  // ...

  async function signIn(formData) {
    const { error } = await supabase.auth.signInWithPassword({
      email: formData.email,
      password: formData.password,
    });

    if (error) {
      // handle error
    }
  }
  // ...
};

Sign Up

Similarly for Sign Up, create a handler that will call the signUp method.

Add the following in the SignUp component:

// src/components/Auth/SignUp.js
// ...

const SignUp = () => {
  const supabase = createClientComponentClient();
  // ...

  async function signUp(formData) {
    const { error } = await supabase.auth.signUp({
      email: formData.email,
      password: formData.password,
    });

    if (error) {
      setErrorMsg(error.message);
    } else {
      setSuccessMsg('Success! Please check your email for further instructions.');
    }
  }
  //...
};

Reset Password

The Reset Password flow consists of 2 main steps:

Allow the user to login via the password reset link
Update the user's password

When the user clicks the reset link in the email they are redirected back to our application. We'll need to specify the URL for that via the redirectTo option in the resetPasswordForEmail method.

This URL will be a new route handler that will handle the authentication request from the email, and will essentially allow the user to be "logged in" in order to set a new password. That part we'll handle in the next step.

First, in our ResetPassword component, create a handler with the following:

// src/components/Auth/ResetPassword.js

const ResetPassword = () => {
  const supabase = createClientComponentClient();
  // ...

  async function resetPassword(formData) {
    const { error } = await supabase.auth.resetPasswordForEmail(formData?.email, {
      redirectTo: `${window.location.origin}/auth/update-password`,
    });

    if (error) {
      // handle error
    } else {
      // handle success
    }
  }
  //...
};

Here, /auth/update-password will be the route that users will be redirected to. Note the use of window.location.origin as well, which is an easy way to ensure the base path is always matching your environment (ie. local development vs production).

Since this handler is always called on the client side (ie. in the browser), it's safe to use window this way.

Update Password

When a user gets the Reset Password email and click on the link, they'll be redirected to the /auth/update-password route in our app. This will be a route handler that will sign the user in (using the auth code from the email), and once a session is created, redirect them to the /update-password page so that they can set the new password.

The mechanism here is very much the same as what we had setup for the /auth/callback route, only this time after exchanging the code for a session, we will redirect the user to /update-password.

Create a new file under src/app/auth/update-password/route.js and add the following:

// src/app/auth/update-password/route.js

import { createRouteHandlerClient } from '@supabase/auth-helpers-nextjs';
import { cookies } from 'next/headers';
import { NextResponse } from 'next/server';

export async function GET(request) {
  const requestUrl = new URL(request.url);
  const code = requestUrl.searchParams.get('code');

  if (code) {
    const supabase = createRouteHandlerClient({ cookies });
    await supabase.auth.exchangeCodeForSession(code);

    return NextResponse.redirect(`${requestUrl.origin}/update-password`);
  }

  console.error('ERROR: Invalid auth code or no auth code found');

  return NextResponse.redirect(`${requestUrl.origin}/sign-in`);
}

Here, if the code exchange is successful, we're redirecting the user to /update-password page, otherwise we send them back to /sign-in.

Next up, let's update our UpdatePassword component to handle the actual password update itself. For this, we'll use updateUser method.

Add the following to src/components/Auth/UpdatePassword.js:

// src/components/Auth/UpdatePassword.js
// ...

const UpdatePassword = () => {
  const supabase = createClientComponentClient();
  const router = useRouter();
  const [errorMsg, setErrorMsg] = useState(null);

  async function updatePassword(formData) {
    const { error } = await supabase.auth.updateUser({
      password: formData.password,
    });

    if (error) {
      // handle error
    } else {
      // Go to Home page
      router.replace('/');
    }
  }
  // ...
};

We also want to make sure that only authenticated users can access the /update-password route, so let's add that logic in our page code in src/app/update-password/page.js:

// src/app/update-password/page.js

import { createServerComponentClient } from '@supabase/auth-helpers-nextjs';
import { cookies } from 'next/headers';
import { redirect } from 'next/navigation';

import UpdatePassword from 'src/components/Auth/UpdatePassword';

export default async function UpdatePasswordPage() {
  const supabase = createServerComponentClient({ cookies });

  const {
    data: { session },
  } = await supabase.auth.getSession();

  if (!session) {
    redirect('/sign-in');
  }

  return <UpdatePassword />;
}

And that's it! Now our users can successfully update their password.

Wrapping Up

The complete project can be found in GitHub: github.com/mryechkin/nextjs-supabase-auth

I'm pretty happy with the patterns I've landed on here, and plan on using this setup if I'm working with Supabase for the foreseeable future (or at least until Supabase decides to change things around again 😅)

Jokes aside, this will (probably) be the last I wrote on this topic for some time. If you haven't yet, check out my previous two articles in this series for more background and the history of my explorations with Supabase:

Part 1: User Authentication in Next.js with Supabase
Part 2: Authentication in Next.js with Supabase and Next 13

Thanks for reading! Until next time.

React Server Components and Client Components with Rollup

Mykhaylo Ryechkin 🇺🇦 — Sat, 18 Mar 2023 14:10:18 +0000

Background

With the release of Next 13 and introduction of the beta app/ directory, we now have support for React Server Components, and can start building applications using these new React paradigms.

Awhile back I wrote about packaging your JavaScript library code into a dual-module bundle (ESM + CommonJS) using Rollup module bundler. Make sure to check it out (it's been updated for Rollup v3!).

A starter template for React using the setup covered in that post is available here:

✨ github.com/mryechkin/rollup-library-starter ✨

Now, that template is great. I've used it in several libraries that have been published to production for several years now without problems.

However, when trying to import a component from a library built using that starter template in a Next 13 app directory, you get the following error:

The Problem

Next 13 pages inside app directory are React Server Components by default. In fact, anything deemed a React component, when consumed within the app directory, is considered to be a Server Component by default.

To make a React component into a Client Component (ie. our regular old React components with effects and state that we all use and love), you need to denote it with a 'use client' directive at the top of the component file:

// ClientComponent.js
'use client';

export default function ClientComponent() {
  return (
    // ...
  );
}

Client Components are any components that rely on client-side only features, such as:

React context
React hooks (useEffect, useState, etc.)
Event handlers
Animations
window object

So, when I tried to import a Button component (which has event handlers and is "interactive") inside a Server Component, React had no idea that it was supposed to be a Client Component. It didn't see a 'use client' anywhere in the library code, so it assumed that it's a Server Component.

This is something that component libraries will need to start addressing soon, as Server Components start to gain ground (and some already have). I wanted to make sure that my starter template supported Server Components properly.

Possible Solution

One way to address this would be to mark all components in our library as Client Components. This would mean having a top-level 'use client' directive in each file (or at the top of the bundled file if not using directories).

To do this, include a banner option in your output options inside the rollup.config.js, and add 'use client' at the very end of it:

// rollup.config.js
const outputOptions = {
  exports: 'named',
  preserveModules: true,
  banner: `/*
 * Rollup Library Starter
 * {@link https://github.com/mryechkin/rollup-library-starter}
 * @copyright Mykhaylo Ryechkin (@mryechkin)
 * @license MIT
 */
'use client';`,
};

Now, if you leave it as is, the terser plugin will remove it, so we need to tell it to preserve directives by setting the compress.directives option to false:

// rollup.config.js
const config = {
  // ...
  plugins: [
    // ...
    terser({
      compress: { directives: false },
    }),
  ],
};

And now if you run the build script, you'll see that our bundled files have that included at the top.

Great!

...or is it? 🤔

Better Solution

While the above solution works, it's not very elegant.

We don't necessarily want every component to be a Client Component. There can be components in your library that don't rely on state or use any effects, and can very well benefit from being Server Components.

Well, we've already configured Rollup to output separate files for each of our modules. What if we simply add 'use client' to the component files themselves?

A-ha! 💡

// src/components/Button/Button.js
'use client';

const Button = (props) => ({/* */});

However... If we try to run the build, we'll see a warning like this:

Rollup will simply ignore this directory and not include it in our final bundle. And this is a good thing, in general. However, in this case we want this directive to be included. This is where Rollup community comes to the rescue 🎉

While searching for a solution, I came across this issue. Ironically, one of the suggested solutions in there was the initial solution described earlier above. However, there was also another suggestion.

Fredrik Höglund shared his plugin that solves our exact problem:

rollup-preserve-directives

This plugin, as its name implies, preserves any directives written at the top of our files:

This plugin preserves directives when preserveModules: true is set in the Rollup config.

Rollup by default always removes directives like 'use client' from the top of files. This makes sense when bundling files because directives should be applied per file, which is not possible when bundling.

When preserveModules: true is set, because each module is a separate output file, it's possible to keep directives, which is exactly what this plugin does.

Because we're already using the preserveModules option in our Rollup config, this will work great.

With this plugin, we can safely leave the 'use client' directives in our component files (where they belong), and Rollup won't remove them from our bundled files.

To use the plugin, first install it:

npm i -D rollup-plugin-preserve-directives

Then, add it to the plugins array in your rollup.config.js (before terser):

// rollup.config.js
import preserveDirectives from 'rollup-plugin-preserve-directives';
// ...
const config = {
  plugins: [
    // ...
    preserveDirectives(),
    terser(),
    // ...
  ]
};

Running the build again, we can see that the 'use client' directive is preserved in the output files:

And now we can import it in a Server Component and use without any issues:

// src/app/index.js
import { Button, Text } from 'rollup-library-starter';

export default function Home() {
  return (
    <Button>
      <Text>Hello</Text>
    </Button>
  );
}

Disabling the warning

Currently the rollup-preserve-directives plugin doesn't suppress that Rollup warning we saw earlier. Its README suggests to add a custom onwarn handler to the Rollup config if desired.

Let's do that. Add the following to rollup.config.js:

// rollup.config.js
const config = {
  // ...
  onwarn(warning, warn) {
    if (warning.code !== 'MODULE_LEVEL_DIRECTIVE') {
      warn(warning);
    }
  },
};

This will suppress any MODULE_LEVEL_DIRECTIVE warnings, and throw all others. See Rollup docs for more details.

Starter Template

The rollup-library-starter template has been updated to use this plugin, and is available in GitHub for your reference:

✨ github.com/mryechkin/rollup-library-starter ✨

Happy hacking!

Authentication in Next.js with Supabase and Next 13

Mykhaylo Ryechkin 🇺🇦 — Wed, 25 Jan 2023 23:51:51 +0000

Intro

IMPORTANT: Note that this guide is now outdated, and is using an older version of the Next.js Auth Helpers (pinned at 0.6.1). Please see the updated guide for the latest version that utilizes the Proof Key for Code Exchange (PKCE) flow.

Awhile back I wrote an article on using Supabase to implement user authentication in a Next.js app. As it often goes in the world of open-source web, things evolve quickly and a lot can change in just over a year, and so is the case with Supabase.

In this post, I would like to bring you an updated guide on implementing user auth with Supabase and Next.js in 2023.

NOTE: Make sure to read the original post first if you haven't yet, as we'll be building on the main concepts covered there. Code for the Supabase v1 implementation can be found under the v1 branch in GitHub.

What's New?

So, what all has changed? Let's start with the big stuff.

Next 13

In October 2022, Next.js team announced Next 13, and with it came the new app directory architecture.

Though officially still in beta (as of January 2023), the app directory offers a great new way of architecting our apps, and introduces new features like nested layouts and support for React Server Components.

I wanted to explore how this new paradigm would work with Supabase, and try some of the capabilities in a familiar project. Happy to say that this exploration went well, and we'll go over one approach of using the new app architecture in this guide.

Supabase v2

Next up, Supabase released v2 of their JavaScript client library (supabase-js), which brought with it a number of developer experience type improvements, and streamlined how we use some of the API's. A number of methods were also deprecated in this new release, which we'll cover later in this guide.

Supabase Auth Helpers

In addition to the new version of the client library, Supabase also introduced new Auth Helpers earlier this year, which is a collection of libraries and framework-specific utilities for working with user authentication in Supabase.

These utilities eliminate the need to keep writing the same boilerplate code over and over (e.g. initializing Supabase client, setting cookies, etc.), and let us focus on our application code instead. We'll be utilizing their Next.js helpers library in our project.

Supabase UI (Deprecated)

Lastly, the Auth component from the Supabase UI library which we were using to render our auth screens, and handle all the related flows and UI logic (Sign In, Sign Up, Reset Password, etc.) has been deprecated. Components from the original @supabase/ui package were moved into the main Supabase repo, and the package is now deprecated.

The Auth component itself now has a new name "Auth UI", and lives in its own separate repo. Though originally intending to use it, as I began migrating the code I've found this new component to not work quite as well as I'd hoped, getting in the way more than helping. For that reason, I've decided to abandon it in this guide, and build one instead.

Fortunately, building a component like this from scratch isn't all that difficult thanks to libraries like Formik, so we'll use that to help us handle all of our form logic. This has the added benefit of giving us full control of the auth flow, and the ability to customize the form UI however we'd like, without being limited by Supabase's customization options.

Project Setup

In the interest of saving some time, we'll start with the project from the original post, as we do end up re-using a bunch of existing code.

The code for that is in GitHub for your reference. If you're doing this for the first time, clone the v1 branch as your starting point.

Updating Dependencies

First things first, we'll need to update Next.js and Supabase to the latest versions, and install Formik (+ related dependencies) and the Next.js Auth Helpers:

npm install next@latest react@latest react-dom@latest @supabase/supabase-js@2.21.0 @supabase/auth-helpers-nextjs@0.6.1 classnames formik yup

We'll also utilize Tailwind's Forms Plugin to make it easier to style our Auth component, so let's install that as well:

npm install -D @tailwindcss/forms

You can also remove @supabase/ui, since we won't be using it anymore:

npm uninstall @supabase/ui

With dependencies updated, we'll need to configure Next to use the new app directory (make sure you're on version 13 or above). To enable this, add (or update) next.config.js in the project's root folder:

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  experimental: {
    appDir: true,
  },
};

module.exports = nextConfig;

This will allow us to start moving some of our existing code from the pages directory to the app folder. Note that putting the app folder under src also works, which is how the previous project was setup.

Make sure to read more about the new app directory if you aren't familiar with the new features.

Updating Tailwind Config

Last thing we need to do is specify the @tailwindcss/forms plugin in our Tailwind config file:

// tailwind.config.js
/** @type {import('tailwindcss').Config} */
const forms = require('@tailwindcss/forms');

module.exports = {
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
  darkMode: 'media',
  plugins: [forms],
};

Supabase API keys

To use Supabase, we'll need to have our Supabase API key and URL setup.

If you haven't already, create an .env file and specify the corresponding values from Supabase dashboard (refer to the previous post for more details):

// .env
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=

Supabase Client

With API keys setup, let's now create the Supabase Client so that we can interact with Supabase API's. We'll be using the Next.js Auth Helpers library installed earlier for this.

IMPORTANT: The instructions below are using @supabase/auth-helpers-nextjs@0.6.1. At the time of writing, there is an issue with password reset flow in the latest version. Additionally, some of the methods used in this guide have been renamed in version 0.7.0. See the project repo in GitHub for any future changes.

In order to support both the new Server Components and the Client Components, we'll need to have two different kinds of a Supabase Client:

Browser Client: for use with Client Components in the browser, for example within a useEffect
Server Component Client: for use specifically with Server Components

Create two files - supabase-browser.js and supabase-server.js - one for each type of client. We'll put these in the src/lib folder:

└──src/
    └── lib/
         ├── supabase-browser.js
         └── supabase-server.js

Browser Client

// src/lib/supabase-browser.js
import { createBrowserSupabaseClient } from '@supabase/auth-helpers-nextjs';
// NOTE: `createBrowserSupabaseClient` has been renamed to `createPagesBrowserClient` in version `0.7.0`

const supabase = createBrowserSupabaseClient();

export default supabase;

Server Component Client

// src/lib/supabase-server.js
import { createServerComponentSupabaseClient } from '@supabase/auth-helpers-nextjs';
// NOTE: `createServerComponentSupabaseClient` has been renamed to `createServerComponentClient` in version `0.7.0`
import { cookies, headers } from 'next/headers';

export default () =>
  createServerComponentSupabaseClient({
    headers,
    cookies,
  });

Note that this needs to export a function, as the headers and cookies are not populated with values until the Server Component is requesting data (according to Supabase docs).

With the clients setup, we can now import them in our pages and components to interact with Supabase.

E.g. in a Client Component:

import supabase from 'src/lib/supabase-browser';

function ClientComponent() {
  useEffect(() => {
    async function getData() {
      const { data } = await supabase.auth.getSession();
      // ...
    }
    getData();
  }, []);
  // ...
}

E.g. in a Server Component:

import createClient from 'src/lib/supabase-server';

async function ServerComponent() {
  const supabase = createClient();

  const { data } = await supabase.auth.getSession();

  // ...
}

Application Structure

The overall page structure and routes will largely remain the same as before, so we'll get to re-use a bunch of existing code. The biggest change will be moving all page code from the pages folder to the new app directory. As we do that, we'll also need to refactor some things to align with this new paradigm.

Our project folder structure will look like the following:

└── src/
    ├── app/
    │   ├── profile/
    │   │   └── page.js
    │   ├── head.js
    │   ├── layout.js
    │   └── page.js
    ├── components/
    │   ├── Auth/
    │   │   ├── index.js
    │   │   ├── ResetPassword.js
    │   │   ├── SignIn.js
    │   │   ├── SignUp.js
    │   │   └── UpdatePassword.js
    │   └── AuthProvider.js
    └── middleware.js

Let's go through what each of these are.

Pages and Routes

Home: `/`

This is the main Home page, showing the Auth component if no session is found (ie. user needs to sign-in), or a link to the Profile page if there is an active session with a valid user.

This page also handles the "Update Password" flow, and will be redirected to from the link in the reset password email sent by Supabase (this URL is configurable in case you'd like to use a different route).

Previously in src/pages/index.js, this page will now be in src/app/page.js.

Profile: `/profile`

This is an authenticated Profile page, showing some basic user info for the current user. If no session is found, it will redirect to /.

Previously in src/pages/profile.js, this page code will now be in src/app/profile/page.js.

And that's it as far as page routes go.

Note that in Next 13, pages are Server Components by default, but can be set to Client Components via the 'use client' directive. More on this and how it impacts our code a bit later.

Root Layout

In the previous solution, we built our own Layout component, and used it as the top-level wrapper for each individual page, ie:

import Layout from 'src/components/Layout';

export default function Home() {
  return <Layout>{/** Page content */}</Layout>;
}

With Next 13 and the app directory, this can now be done using shared layouts ✨

Since we only have a single layout shared across the whole app, we can just create a single root layout.js file in src/app, which will be shared by all children routes and pages. We'll call this RootLayout.

Using the existing Layout component as our starting point, create src/app/layout.js and paste the following (feel free to adjust styling as needed):

// src/app/layout.js
import 'src/styles/globals.css';

export default async function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <div className="flex min-h-screen flex-col items-center justify-center py-2">
          <main className="flex w-full flex-1 shrink-0 flex-col items-center justify-center px-8 text-center sm:px-20">
            <h1 className="mb-12 text-5xl font-bold sm:text-6xl">
              Next.js with <span className="font-black text-green-400">Supabase</span>
            </h1>
            {children}
          </main>
        </div>
      </body>
    </html>
  );
}

Note how we need to include <html> and <body> tags here as well. If you'd like to think of it in terms of the old pages directory, the root layout.js essentially combines the concepts of _app.js and _document.js together into one.

One big benefit of a root layout is that state is preserved on route changes, and the layout doesn't unnecessarily rerender. Layouts can also be nested, though we won't be needing that in this project.

IMPORTANT: Root layout is a Server Component by default, and can NOT be set to a Client Component. Any parts of your layout that require interactivity will need to be moved into separate Client Components (which can be marked with the 'use client' directive).

Read more on this in "moving Client Components to the leaves" in Next.js docs for additional information.

Auth Provider

To handle our auth-related logic on the client side, we need an AuthProvider, which is essentially a React context provider.

This component is a top-level wrapper in our application, providing things like user and session objects, signOut method and a useAuth hook to its children components.

Previously found in the src/lib/auth.js file in the original implementation, we'll move this to src/components/AuthProvider.js to keep our folder and naming structure consistent. For now, keep all of the existing code - we'll update it as we go along.

In the original implementation, this component was used in the _app.js:

// src/pages/_app.js
function MyApp({ Component, pageProps }) {
  return (
    <AuthProvider supabase={supabase}>
      <Component {...pageProps} />
    </AuthProvider>
  );
}

With the move to app directory, we'll need to find it a new home. Considering that this will be shared by all pages, the best place for it is in the RootLayout.

Update src/app/layout.js with the following:

// src/app/layout.js
import { AuthProvider } from 'src/components/AuthProvider';

import 'src/styles/globals.css';

export default async function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {/* ... */}
        <AuthProvider>{children}</AuthProvider>
        {/* ... */}
      </body>
    </html>
  );
}

One important thing to note from Next.js beta docs:

In Next.js 13, context is fully supported within Client Components, but it cannot be created or consumed directly within Server Components. This is because Server Components have no React state (since they're not interactive), and context is primarily used for rerendering interactive components deep in the tree after some React state has been updated.

Given the above, we'll need to make AuthProvider a Client Component, since it uses React context.

To do this, add 'use client' at the very top of the src/components/AuthProvider.js file:

'use client';

import { createContext, useContext, useEffect, useMemo, useState } from 'react';

// ...

export const AuthProvider = (props) => {
  // ...
}

Note that even though AuthProvider is now a Client Component, it can still be imported and used in the RootLayout (which is a Server Component).

Middleware

Next.js middleware is used to run code before a request is completed, and can be configured to run that code only on specific routes. From Supabase docs we learn that:

Since we don't have access to set cookies or headers from Server Components, we need to create a Middleware Supabase client and refresh the user's session by calling getSession(). Any Server Component route that uses a Supabase client must be added to this middleware's matcher array. Without this, the Server Component may try to make a request to Supabase with an expired access_token.

So, we'll need to add Next.js middleware in our app. Create a middleware.js file at the root of our src folder, and add the following:

import { createMiddlewareSupabaseClient } from '@supabase/auth-helpers-nextjs';
import { NextResponse } from 'next/server';

export async function middleware(req) {
  const res = NextResponse.next();

  const supabase = createMiddlewareSupabaseClient({ req, res });

  const {
    data: { session },
  } = await supabase.auth.getSession();

  return res;
}

export const config = {
  matcher: ['/profile'],
};

Here we're using the createMiddlewareSupabaseClient() function from the Next.js Auth Helpers to create a middleware Supabase client, and we're also configuring the matcher array to run this code on the /profile route, as that's the only route using Server Components in our case. If you have additional routes utilizing Server Components, you'll need to specify them here as well.

Migrating to Supabase v2

With the core of our app code now in place, it's time to make some updates.

There were a few methods deprecated in Supabase v2, so we'll need to update how we use those in our AuthProvider.

Session Listener

If you recall, we have a useEffect inside our AuthProvider that retrieves the current session, as well as an event listener for any auth events fired by Supabase client.

The methods for these have changed in Supabase v2, so we'll need to update how they're used.

First, remove the deprecated session() method and use getSession() instead.

Because this new method returns a Promise, we need to call it from within an async function in our useEffect.

Create an async getActiveSession method, and invoke it from within the useEffect. In the AuthProvider component, update the useEffect from this:

useEffect(() => {
  const activeSession = supabase.auth.session();
  setSession(activeSession);
  setUser(activeSession?.user ?? null);
  // ...
}, []);

to this:

useEffect(() => {
  async function getActiveSession() {
    const {
      data: { session: activeSession },
    } = await supabase.auth.getSession();
    setSession(activeSession);
    setUser(activeSession?.user ?? null);
  }
  getActiveSession();
  // ...
}, []);

Next, we need to update the onAuthStateChange handler.

To get the authListener for our effect cleanup, we now need to read it from data.subscription in the returned object:

useEffect(() => {
  // ...
  const {
    data: { subscription: authListener },
  } = supabase.auth.onAuthStateChange((event, currentSession) => {
    setSession(currentSession);
    setUser(currentSession?.user ?? null);
  });
  // ...
  return () => {
    authListener?.unsubscribe();
  };
}, []);

Managing Cookies

The setAuthCookie and getUserByCookie methods have also been deprecated. Recommended solution for managing cookies in Next.js is now the Next.js Auth Helpers library, which we had installed earlier. We'll be using that alongside Next.js middleware (more on that below).

This means that we won't need to manually create or delete a cookie whenever auth state changes, and the /api/auth API routes are no longer required. We can delete pages/api/auth altogether, and remove the fetch call to /api/auth in our onAuthStateChange handler as well:

useEffect(() => {
  // ...
  const { data: authListener } = supabase.auth.onAuthStateChange(
    (event, currentSession) => {
      // fetch('/api/auth', {
      //   method: 'POST',
      //   headers: new Headers({ 'Content-Type': 'application/json' }),
      //   credentials: 'same-origin',
      //   body: JSON.stringify({ event, session: currentSession }),
      // }).then((res) => res.json());
    }
  );
  //...
}, []);

The useEffect in AuthProvider should now look like this:

//...
useEffect(() => {
    async function getActiveSession() {
      const {
        data: { session: activeSession },
      } = await supabase.auth.getSession();
      setSession(activeSession);
      setUser(activeSession?.user ?? null);
    }
    getActiveSession();

    const {
      data: { subscription: authListener },
    } = supabase.auth.onAuthStateChange((event, currentSession) => {
      setSession(currentSession);
      setUser(currentSession?.user ?? null);

      switch (event) {
        case EVENTS.PASSWORD_RECOVERY:
          setView(VIEWS.UPDATE_PASSWORD);
          break;
        case EVENTS.SIGNED_OUT:
        case EVENTS.USER_UPDATED:
          setView(VIEWS.SIGN_IN);
          break;
        default:
      }
    });

    return () => {
      authListener?.unsubscribe();
    };
  }, []);
// ...

Auth Component

With Supabase setup, and AuthProvider updated to use Supabase v2, it's time to build our authentications forms. This is what will replace the Auth component from the (now deprecated) Supabase UI library.

Let's make each form an individual component:

Sign In: SignIn.js
Sign Up: SignUp.js
Reset Password: ResetPassword.js
Update Password: UpdatePassword.js

Then, create a parent Auth component that will display the corresponding screen based on the current view:

'use client';

import { useAuth, VIEWS } from 'src/components/AuthProvider';

import ResetPassword from './ResetPassword';
import SignIn from './SignIn';
import SignUp from './SignUp';
import UpdatePassword from './UpdatePassword';

const Auth = ({ view: initialView }) => {
  let { view } = useAuth();

  if (initialView) {
    view = initialView;
  }

  switch (view) {
    case VIEWS.UPDATE_PASSWORD:
      return <UpdatePassword />;
    case VIEWS.FORGOTTEN_PASSWORD:
      return <ResetPassword />;
    case VIEWS.SIGN_UP:
      return <SignUp />;
    default:
      return <SignIn />;
  }
};

export default Auth;

Here, we're checking the value of view from our AuthProvider via the useAuth() hook, and display the corresponding component for the given auth flow. The Auth component also accepts an optional view prop, in case we need to manually override it (as is the case with "Update Password" flow, but more on that later).

The individual forms all follow the same basic structure, which looks like this for Sign In:

'use client';

import { useState } from 'react';
import cn from 'classnames';
import { Field, Form, Formik } from 'formik';
import * as Yup from 'yup';

import { useAuth, VIEWS } from 'src/components/AuthProvider';
import supabase from 'src/lib/supabase-browser';

const SignInSchema = Yup.object().shape({
  email: Yup.string().email('Invalid email').required('Required'),
  password: Yup.string().required('Required'),
});

const SignIn = () => {
  const { setView } = useAuth();
  const [errorMsg, setErrorMsg] = useState(null);

  async function signIn(formData) {
    const { error } = await supabase.auth.signInWithPassword({
      email: formData.email,
      password: formData.password,
    });

    if (error) {
      setErrorMsg(error.message);
    }
  }

  return (
    <div className="card">
      <h2 className="w-full text-center">Sign In</h2>
      <Formik
        initialValues={{
          email: '',
          password: '',
        }}
        validationSchema={SignInSchema}
        onSubmit={signIn}
      >
        {({ errors, touched }) => (
          <Form className="column w-full">
            <label htmlFor="email">Email</label>
            <Field
              className={cn('input', errors.email && touched.email && 'bg-red-50')}
              id="email"
              name="email"
              placeholder="jane@acme.com"
              type="email"
            />
            {errors.email && touched.email ? (
              <div className="text-red-600">{errors.email}</div>
            ) : null}

            <label htmlFor="email">Password</label>
            <Field
              className={cn('input', errors.password && touched.password && 'bg-red-50')}
              id="password"
              name="password"
              type="password"
            />
            {errors.password && touched.password ? (
              <div className="text-red-600">{errors.password}</div>
            ) : null}

            <button
              className="link w-full"
              type="button"
              onClick={() => setView(VIEWS.FORGOTTEN_PASSWORD)}
            >
              Forgot your password?
            </button>

            <button className="button-inverse w-full" type="submit">
              Submit
            </button>
          </Form>
        )}
      </Formik>
      {errorMsg && <div className="text-red-600">{errorMsg}</div>}
      <button
        className="link w-full"
        type="button"
        onClick={() => setView(VIEWS.SIGN_UP)}
      >
        Don&apos;t have an account? Sign Up.
      </button>
    </div>
  );
};

export default SignIn;

Here, we're using Formik to build out the form, and Yup for schema validation (as recommended by Formik). The same pattern is applied for all forms.

Check out the full Formik tutorial for more details on how it works.

Similarly, the remaining auth flows are also implemented:

Check out the linked files for reference.

We'll put all these in the src/components/Auth folder, where index.js is the parent Auth component, and then each individual form is a separate component file:

src/
└── components/
    └── Auth/
        ├── index.js
        ├── ResetPassword.js
        ├── SignIn.js
        ├── SignUp.js
        └── UpdatePassword.js

Code for the complete Auth component can be found in GitHub for your reference.

Updating Pages

With the new Auth component in place, it's time to update our page code.

Home

Our Home page will use the original code from src/pages/index.js as the starting point. And there really isn't much to change!

We're still using the useAuth hook, and reading view, user and signOut from it
Thanks to the new shared layout, we don't need the Layout wrapper anymore
The Auth component API is a bit simplified, as it doesn't require the Supabase client to be passed to it anymore (that's done internally in the component)
The imports for AuthProvider and Auth will also need to be updated

With all said, the Home page should look something like this:

import Link from 'next/link';

import Auth from 'src/components/Auth';
import { useAuth, VIEWS } from 'src/components/AuthProvider';

export default function Home() {
  const { user, view, signOut } = useAuth();

  if (view === VIEWS.UPDATE_PASSWORD) {
    return <Auth view={view} />;
  }

  if (user) {
    return (
      <div className="card">
        <h2>Welcome!</h2>
        <code className="highlight">{user.role}</code>
        <Link className="button" href="/profile">
          Go to Profile
        </Link>
        <button type="button" className="button-inverse" onClick={signOut}>
          Sign Out
        </button>
      </div>
    );
  }

  return <Auth view={view} />;
}

As before, we are showing the Auth component if no user is found in the current session, or a simple authenticated view with a link to /profile and a Sign Out button otherwise.

Note also that we are rendering the Auth component first if the view is UPDATE_PASSWORD, which means that a user has been redirected to here after clicking the link in Supabase Reset Password email.

NOTE: It's important that this is returned for the UPDATE_PASSWORD view regardless if there's an active user, as the email link passes an access_token along with the URL and Supabase client creates a session with this token. So we're basically in an "authenticated" state during the Update Password flow, and if we check for a user first, the home page will always show the authenticated view without giving our user ability to update their password.

This is essentially the same behaviour as we had in the original solution, but updated to use the new Auth component.

Now, if we try to run the app and go to the Home page in its current state, we'll get an error like this:

As mentioned earlier, in Next 13 pages are Server Components by default when using the app dir. This means that our AuthProvider, which is a Client Component, cannot be consumed within the Home page in its current state.

If we look at the error a bit closer we'll see that the useAuth hook is the culprit:

const { user, view, signOut } = useAuth();

To fix this, we need to make Home a Client Component. As before, add 'use client' at the very top of the src/app/page.js file:

'use client';

import Link from 'next/link';

import Auth from 'src/components/Auth';
import { useAuth, VIEWS } from 'src/components/AuthProvider';

export default function Home() {
  // ...
}

Now if we run the app again, we should see the Auth component rendered:

Clicking on "Forgot password" or "Sign Up" text will set view to the corresponding screen (this is implemented internally in the Auth component, by calling setView from the AuthProvider).

Let's go ahead and either Sign In or Sign Up. These flows behave the same as before, and if successful we should see the authenticated part of our Home page:

The view rerendered because Home page is a Client Component and is nested within the AuthProvider (also a Client Component). As we had previously done, the onAuthStateChange listener will listen for auth event changes, and update the view in the state, thereby triggering a rerender in relevant components (the Home page in this case).

Profile

For the Profile page, we'll be starting off with src/pages/index.js as our base.

We'll keep this page as a Server Component (default in Next 13), which means that we can call API's and server-side methods directly in the component. So any calls made within getServerSideProps before can now be done directly in the component.

This is also where we use the Supabase Server Component client we had created in src/lib/supabase-server.

Add the following to src/app/profile/page.js:

import Link from 'next/link';
import { redirect } from 'next/navigation';

import createClient from 'src/lib/supabase-server';

export default async function Profile() {
  const supabase = createClient();

  const {
    data: { user },
  } = await supabase.auth.getUser();

  if (!user) {
    redirect('/');
  }

  return (
    <div className="card">
      <h2>User Profile</h2>
      <code className="highlight">{user.email}</code>
      <div className="heading">Last Signed In:</div>
      <code className="highlight">{new Date(user.last_sign_in_at).toUTCString()}</code>
      <Link className="button" href="/">
        Go Home
      </Link>
    </div>
  );
}

Let's break this down a bit.

As noted earlier, the getUserByCookie method was deprecated. We can now get the current user with the getUser() method:

export default async function Profile() {
  const supabase = createClient();

  const {
    data: { user },
  } = await supabase.auth.getUser();
  // ...
}

Notice that because getUser() is an async method, we need to make Profile and asynchronous component as well. Keep this in mind as we continue.

Next, we check if there's a valid user, and if there isn't - redirect user back to Home using the redirect function from Next.js. This keeps the Profile page protected, and only allow authenticated users to access it.

NOTE: redirect() can only be called as part of rendering and not as part of event handlers (source). This means you can't use redirect within a button's onClick handler, for example.

Let's run our app, and make sure everything works as expected. If signed in, we should see our Profile page:

Everything works great!

But let's say we want to add a "Sign Out" button:

This button will need an onClick handler, which means that we can't use it directly in the Profile as that's a Server Component. We'll need to make this button into a separate Client Component, which can then be imported and used in the Profile.

Let's put this tiny component in src/components/SignOut.js. Upon clicking the button, it'll call the signOut() method from our AuthProvider:

'use client';

import { useAuth } from './AuthProvider';

export default function SignOut() {
  const { signOut } = useAuth();

  async function handleSignOut() {
    const { error } = await signOut();

    if (error) {
      console.error('ERROR signing out:', error);
    }
  }

  return (
    <button type="button" className="button-inverse" onClick={handleSignOut}>
      Sign Out
    </button>
  );
}

Then add it to the Profile page:

import SignOut from 'src/components/SignOut';

export default async function Profile() {
  // ...
  return (
    <div className="card">
      {/** ... */}
      <Link className="button" href="/">
        Go Home
      </Link>
      <SignOut />
    </div>
  );
}

Now when user presses the button, they'll be signed out and session cleared. But there's one problem.

You see, since Profile is a Server Component, any updates in the AuthProvider state don't cause it to rerender. This also means that any changes in Supabase auth state (ie. user signing out) don't trigger a rerender either, and so our UI doesn't reflect the change in the auth state. We need a different way of handling this, compared to Client Components.

Syncing-up Server and Client states

Our problem is that after a user signs out, our UI (ie. the rendered Server Component) and server state are no longer in sync. In order for them to be in sync, we need to rerender our page.

One way of doing that is to simply reload the page. In fact, if you reload the browser on /profile again, it should redirect you back to Home, as intended. Understandably, we shouldn't be relying solely on users manually refreshing their browser window to update our UI state.

Thanks to the new router in Next 13, we can use the useRouter hook and call the router.refresh() method to trigger a route refresh when there is no longer a valid user in the session.

But how do we know if the session is no longer valid on the server side? A-ha! For this, we'll need to check whether our client and server sessions match.

In the AuthProvider, add the following:

// ...
import { useRouter } from 'next/navigation';

export const AuthProvider = (props) => {
  // ...
  const router = useRouter();

  useEffect(() => {
    // ...
    const {
      data: { subscription: authListener },
    } = supabase.auth.onAuthStateChange((event, currentSession) => {
      if (currentSession?.access_token !== accessToken) {
        router.refresh();
      }
    });
    // ...
  });
  // ...
}

Now, whenever the auth state changes, we're checking if the current session's access_token (on the client) matches the one on the server. If it does not, we trigger a router.refresh() and our UI state will be updated. The server's access token will be passed as the accessToken prop.

So, where should this access token come from? Well, considering that we need to pass it to the AuthProvider and it needs to be done server-side, we need to fetch it in our RootLayout.

Add the following to src/app/layout.js:

import createClient from 'src/lib/supabase-server';

// ...

export default async function RootLayout({ children }) {
  const supabase = createClient();

  const {
    data: { session },
  } = await supabase.auth.getSession();

  const accessToken = session?.access_token || null;

  return (
    <html lang="en">
      {/** ... */}
      <AuthProvider accessToken={accessToken}>{children}</AuthProvider>
      {/** ... */}
    </html>
  );
}

This will read the current server-side session and pass its access_token as the accessToken prop to the AuthProvider. Now the auth listener will have something to compare the client-side session to.

We also don't want our RootLayout to get cached, so we'll need to change the default revalidation behaviour in Next 13 by setting the revalidate option to 0.

Add the following to src/app/layout.js:

// ...
export const revalidate = 0;

This will ensure that every time a new route is loaded, our session data in RootLayout will always be up-to-date.

Now if go back to the Profile page, and click "Sign Out", we should be redirected to Home page.

Adding loading state

You may have noticed that when going to Profile for the first time, it takes a little bit of time to load. Let's exaggerate it by adding a simple sleep util in our Profile and await it:

// ...
const sleep = (ms) =>
  new Promise((resolve) => {
    setTimeout(resolve, ms);
  });

export default async function Profile() {
  // ...
  await sleep(2000);

  const {
    data: { user },
  } = await supabase.auth.getUser();
  // ...
}

This will add a 2-second delay to the getUser() call. Now that is really noticeable. Let's make this better.

In Next 13, there is a new concept of a Loading UI, which adds an instant loading state with the help of React Suspense.

Using it couldn't be any simpler. Just add a loading.js file wherever you'd like to create an instant loading state, and specify the UI to show.

For our Profile, let's add the following to src/app/profile/loading.js:

export default function Loading() {
  return <div className="card h-72">Loading...</div>;
}

Now, when you reload the page (or go to /profile from the home page), you should see the loading UI almost immediately:

And now that we've verified it works as expected, let's not forget to remove that sleep call from our Profile page:

// ...
export default async function Profile() {
  const supabase = createClient();

  const {
    data: { user },
  } = await supabase.auth.getUser();

  if (!user) {
    redirect('/');
  }

  return (
    // ...
  );
}

Flash of unauthenticated state

Almost done! But before we wrap up, there is one other thing left to fix.

Right now, if we have a valid session and reload the Home page, we'll still see a brief flash of unauthenticated state:

This happens because on the very first render the Home page (which remember is a Client Component) doesn't yet have any session data from the AuthProvider, so it returns the <Auth> component:

export default function Home() {
  const { initial, user, view, signOut } = useAuth();
  // ...
  return <Auth view={view} />;
}

This, of course, is desired behaviour when there is no user data found. But we know that our session data has a valid user - it just so happens to not be available on the first render, since we fetch that data inside a useEffect in our AuthProvider.

To fix this, we need to be able to differentiate between an "initial" state of our app on the client side - before we check if there's a valid session - and after. This way we'll know whether a valid session truly doesn't exist, or just hasn't had a chance to load yet.

Now, if Home was a Server Component, then we could simply await the result of getSession() (like we do in the RootLayout) and place a Suspense boundary to show a loading state (like we did for the Profile above). But because Home is a Client Component, that won't work.

You see, root-level await is not supported in client-side components, and so we can't "suspend" our Home page until the session data is available like we do with Profile. React team is working on an RFC and a new use hook that will allow us to conditionally wait for data to load, but it's not quite ready yet. Its use (pardon the pun) is also not recommended by Next itself, as it may cause multiple re-renders in Client Components. Considering all that, we'll need to find an alternative way.

There are a few ways we could solve this. For example, we could move the "authenticated" portion of our Home page to a new route altogether (e.g. /home), thereby completely separating the "unathenticated" state. But that would involve a bunch of refactoring of the code we already wrote, and ideally would like to avoid that for this guide. So in the interest of time, we'll go with a bit more "old school" approach.

One simple way to fix this is to add another state variable in our AuthProvider that will simply tell us whether our app is loading for the first time or not. We can set its value to true initially, and once we do the first call to supabase.auth.getSession() we can set it to false, indicating that our app has loaded the data.

In the AuthProvider, create an initial state, and make sure its value is provided:

// ...
export const AuthProvider = (props) => {
  const [initial, setInitial] = useState(true);
  // ...
  useEffect(() => {
    async function getActiveSession() {
      const {
        data: { session: activeSession },
      } = await supabase.auth.getSession();
      // ...
      setInitial(false);
    }
    getActiveSession();
    // ...
  }, []);
  // ...
  const value = useMemo(() => {
    return {
      initial,
      session,
      user,
      view,
      setView,
      signOut: () => supabase.auth.signOut(),
    };
  }, [initial, session, user, view]);

  return <AuthContext.Provider value={value} {...rest} />;
}

Now we can read initial using the useAuth hook in our Home page, and while it's value is true, show our loading state instead of returning the <Auth> component:

// ...
export default function Home() {
  const { initial, user, view, signOut } = useAuth();

  if (initial) {
    return <div className="card h-72">Loading...</div>;
  }
  // ...
  return <Auth view={view} />;
}

And now if we reload our Home page, we should see the same kind of loading state that we have in Profile:

This is a quick and easy way of dealing with this problem, but by no means the only way. Ideally we'd like to use Suspense for this, but until React lands on a more established pattern for it in client-side components, we're not going to focus on it too much. For the time being, this solves our immediate problem in this scenario.

Wrap Up

Well, this about wraps it up. If you've made it this far - thank you for reading! Hopefully this guide gives you a good starting point for using Supabase in your Next 13 project, or at the very least points you in the right direction.

Make sure to give the new Next.js Beta Docs a read as well, as I've found them to be an invaluable resource for learning some of these new paradigms coming to the world of React.

EDIT: The new Next.js Docs have now been updated. Definitely give them a read if you haven't yet.

Happy coding!

Reference Materials

GitHub: github.com/mryechkin/nextjs-supabase-auth
Live Example: supabase-auth-next-13.vercel.app
Next.js Beta Docs: beta.nextjs.org
React Beta Docs: beta.reactjs.org

EDIT: Both React and Next.js docs have since been released.

Rollup Library Starter

Mykhaylo Ryechkin 🇺🇦 — Wed, 05 Oct 2022 16:47:31 +0000

Intro

In this post we'll take a look at how to package your JavaScript library code into a production-ready bundle using Rollup module bundler. By the end of this tutorial we will have a dual-module format bundle that is ready to be published to NPM, can be consumed in either server or browser environments, and is available in both ESM and CommonJS formats.

Want to learn more about the different module formats? Check out this post!

The base recipe assumes use of regular JavaScript and is meant for use with React projects, however the basic principles and patterns we'll cover here are not restricted to any one framework, and can be extended to a variety of different projects.

NOTE: If your project uses TypeScript, I would suggest using tsdx instead.

Let's get started!

Project Setup

First, init your project using npm init. You should have a package.json now that looks something like this:

// package.json
{
  "name": "rollup-library-starter",
  "version": "1.0.0",
  "description": "Starter template for building JS libraries using Rollup",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "Mykhaylo Ryechkin",
  "license": "MIT"
}

You'll also want to add a .gitignore file:

.DS_Store
dist
node_modules

Folder Structure

Our project files will live inside the src folder, and the example folder structure will look something like this:

src/
├── components/
│   ├── Button/
│   │   ├── Button.js
│   │   └── index.js
│   ├── Text/
│   │   ├── Text.js
│   │   └── index.js
│   └── index.js
├── utils/
│   └── index.js
└── index.js

This is just an example convention. Ultimately, you can structure it however you'd like. The main thing to remember is every folder will need an index.js file, including the top-level src:

// src/index.js
export * from './components';
export * from './utils';

Here we're simultaneously importing and re-exporting all modules from the components and utils folders (each having their own index.js file). This is where we control what's available from our library for external consumption - anything that's exported will be available to the library consumer.

Modules

Our library will expose each module as a named module, ie:

import { Button, Text } from 'rollup-library-starter';

To make things easier to maintain, we're putting each module and the related files in its own folder, using the same name as the module (ie. src/components/Button and src/components/Text).

We can then further group these modules by category and put all related modules in the same folder (ie. src/components). Each folder also needs to have its own index.js file as well:

// src/components/index.js
export { default as Button } from './Button';
export { default as Text } from './Text';

Here we're importing the default exports of the Button and Text modules, and re-exporting them as Button and Text.

Inside each of our Button and Text folders, we have the main index.js files, as well as separate component files (Button.js and Text.js):

// src/components/Button/Button.js
const Button = (props) => {
  const { children, onClick } = props;

  function handleOnClick() {
    console.log('Button onClick');
    return onClick;
  }

  return (
    <button type="button" onClick={handleOnClick} {...props}>
      {children}
    </button>
  );
};

export const VARIANT = {
  PRIMARY: 'primary',
  SECONDARY: 'secondary',
};

export default Button;

// src/components/Button/index.js
import Button, { VARIANT } from './Button';

export default Object.assign(Button, {
  VARIANT,
});

Notice the little trick we're doing inside the component index.js file above:

export default Object.assign(Button, {
  VARIANT,
});

Here we're assigning VARIANT as a property on the main Button component using Object.assign(), which will let us use VARIANT without having to import it explicitly:

import { Button } from 'rollup-library-starter';
// ...
<Button variant={Button.VARIANT.PRIMARY}>

This pattern allows us to group related code that normally would be imported together anyway, reducing some verbosity in the import statements.

The Text component is slightly simpler, with just one main default export, which is then re-exported inside index.js:

// src/components/Text/Text.js
export default function Text({ children }) {
  return <div style={{ fontSize: '2.5rem', fontFamily: 'monospace' }}>{children}</div>;
}

// src/components/Text/index.js
import Text from './Text';

export default Text;

And finally, in our utils folder, we have a single index.js file, with a sample function Greet exported as a named export:

// src/utils/index.js
export const Greet = (text) => console.log(`Hello ${text}.`);

To export all these modules at the root, make sure they're included in the index.js file at the top of the src folder, as we saw earlier:

// src/index.js
export * from './components';
export * from './utils';

The idea here is that our main index.js file will contain all the exported modules within our library, as named exports.

With that done, time to install our dependencies.

Tooling & Dependencies

Now that the base library setup, let's install all the necessary tooling. As mentioned earlier, we'll be using Rollup as our module bundler (v2 at the time of writing this post):

Rollup is a module bundler for JavaScript which compiles small pieces of code into something larger and more complex, such as a library or application. It uses the new standardized format for code modules included in the ES6 revision of JavaScript, instead of previous idiosyncratic solutions such as CommonJS and AMD. ES modules let you freely and seamlessly combine the most useful individual functions from your favorite libraries. This will eventually be possible natively everywhere, but Rollup lets you do it today.

Rollup has an extensive plugin ecosystem, which provides a lot of flexibility in adding specific functionality for a variety of use cases. Check out the awesome curated list here.

Now, it can be daunting to figure out which exact plugins to use - and the goal of this article is to provide guidance on what's needed for a majority of bundles that you'll be building. First, we will install all the required dependencies, and then go through what each of them does as we start to configure the steps.

We'll be using Babel to transpile our code into JavaScript that all current and older browsers and environments will understand. For this, install @babel/runtime as a dependency. This will be our only production dependency, and will let Rollup bundle some of the helper functions required for backwards compatibility:

npm i @babel/runtime

Next, we need to install a few Babel plugins, as well as Rollup itself and a number of Rollup plugins:

These should all be devDependencies, so make sure to add the -D flag:

npm i -D rollup rollup-plugin-analyzer @rollup/plugin-alias @rollup/plugin-babel @rollup/plugin-commonjs @rollup/plugin-node-resolve @rollup/plugin-terser @babel/plugin-transform-runtime @babel/preset-env @babel/preset-react

And lastly, since we're using React in our library, we'll also need to specify react and react-dom as peer dependencies in package.json:

// package.json
{
  "peerDependencies": {
    "react": "^16.14.0 || ^17.0.0 || ^18.2.0",
    "react-dom": "^16.14.0 || ^17.0.0 || ^18.2.0"
  }
}

This will ensure that our library doesn't try to include its own copy of React when it's installed, as that can cause all sorts of issues.

Rollup Configuration

To get started with Rollup, we'll need to create a configuration file at the root of our project, where we specify all the options for bundling, plugins, presets, etc. This file will be the bulk of our work.

Our library is written using the modern ESM module syntax, however we want our code to be executable in all JavaScript environments. In order to support this, we will ship two distinctly separate bundles as part of our library package: ESM and CommonJS (or CJS).

Rollup will handle all the transpilation of our code from ESM to CJS, and generate two separate bundles for each format. This will make our library package consumable in both server (Node) and browser environments. We will also need to modify our package.json to support this.

It's worthwhile to keep in mind the dual package hazard, which is explained in the official Node docs. With that said, this pattern has been working great for my team across multiple JS libraries for several years now, and has proven itself in many enterprise-grade production applications.

Base Config

First, let's create a file called rollup.config.js at the root of our project. We will import all the packages and plugins, and then break down what each of them does.

// rollup.config.js
import { fileURLToPath } from 'node:url';
import { createRequire } from 'node:module';

import alias from '@rollup/plugin-alias';
import babel from '@rollup/plugin-babel';
import commonjs from '@rollup/plugin-commonjs';
import nodeResolve from '@rollup/plugin-node-resolve';
import terser from '@rollup/plugin-terser';
import analyze from 'rollup-plugin-analyzer';

const require = createRequire(import.meta.url);
const pkg = require('./package.json');

const config = {
  // Rollup options go here
};

export default config;

The config is where we'll be setting all the different options, as well as plugins and Babel presets.

Output Options

We will be generating two bundles, and there are some common output options shared between the two. Let's put these in a variable:

// rollup.config.js
// ...
const outputOptions = {
  exports: 'named',
  preserveModules: true,
  banner: `/*
 * Rollup Library Starter
 * {@link https://github.com/mryechkin/rollup-library-starter}
 * @copyright Mykhaylo Ryechkin (@mryechkin)
 * @license MIT
 */`,
};

Here, we're setting the exports option to "named", because we're exporting everything as named exports. This is intentional, as there can be issues with mixing both default and named patterns of exports at the root of your package, when exporting to CommonJS format. Rollup will also throw a warning when you do that.

The preserveModules option will tell Rollup to create separate chunks for all modules, using the original module names as file names.

This is needed in order for tools like Webpack 5 to be able to successfully tree-shake unused imports when consuming our library. We ran into this issue with our component library when we originally moved to Rollup. Enabling this option eliminated issues with tree-shaking for our users, and this pattern has worked well for us since.

Lastly, and completely optional, we can add a banner to each of the generated files. This is a good way to provide some info about our library, and add author attribution.

For all other available options, check out the big list of options here.

With these options defined, let's now provide the entry point for our package. This will be the root-level index.js file, which if you recall containts all of our available modules exported as "named". We will also set our output options as well:

// rollup.config.js
// ...
const config = {
  input: 'src/index.js',
  output: [
    {
      dir: 'dist/esm',
      format: 'esm',
      ...outputOptions,
    },
    {
      dir: 'dist/cjs',
      format: 'cjs',
      ...outputOptions,
    },
  ],
};

Our output option is an array of objects, one for each of the bundles we'd like to build. Here we specify both esm and cjs formats, which output to dist/esm and dist/cjs folders respectively. All other shared outputOptions are provided for both.

External Modules

Next, we need to tell Rollup which of the modules used in our code are external to our library. Together with @rollup/plugin-node-resolve, this ensures that Rollup doesn't bundle those dependencies into our final bundle. The function makeExternalPredicate() generates the list of package names specified in dependencies and peerDependencies in package.json. All credit for this and a big thank you goes out to Mateusz Burzyński for providing it in this issue:

// rollup.config.js
// ...
const makeExternalPredicate = (externalArr) => {
  if (externalArr.length === 0) {
    return () => false;
  }
  const pattern = new RegExp(`^(${externalArr.join('|')})($|/)`);
  return (id) => pattern.test(id);
};

const config = [
  {
    // ...
    external: makeExternalPredicate([
      ...Object.keys(pkg.dependencies || {}),
      ...Object.keys(pkg.peerDependencies || {}),
    ]),
  },
];

Plugins

Next up, we have the plugins array, and it specifies which Rollup plugins to run. The order in which plugins are specified is very important, as the input for each plugin is the previous one's output, so make sure to follow the order they're listed in here.

Plugin: Alias

The first plugin we're using is @rollup/plugin-alias, which enables us to use absolute import paths for src (or any other path you want to configure):

// rollup.config.js
import alias from '@rollup/plugin-alias';
// ...
const config = [
  {
    // ...
    plugins: [
      alias({
        entries: {
          src: fileURLToPath(new URL('src', import.meta.url)),
        },
      }),
    ],
  },
];

Plugin: Resolve Node Modules

Next, we have @rollup/plugin-node-resolve, which allows Rollup to resolve external modules from node_modules:

// rollup.config.js
import nodeResolve from '@rollup/plugin-node-resolve';
// ...
const config = [
  {
    // ...
    plugins: [
      // ...
      nodeResolve(),
    ],
  },
];

Plugin: CommonsJS

The @rollup/plugin-commonjs plugin converts 3rd-party CommonJS modules into ES6 code, so that they can be included in our Rollup bundle:

// rollup.config.js
import commonjs from '@rollup/plugin-commonjs';
// ...
const config = [
  {
    // ...
    plugins: [
      // ...
      commonjs({ include: ['node_modules/**'] }),
    ],
  },
];

Plugin: Babel

Next, we need to enable Babel for code transpilation. We do that by passing @rollup/plugin-babel as a plugin, and then specifying the @babel/plugin-transform-runtime Babel plugin:

// rollup.config.js
import babel from '@rollup/plugin-babel';
// ...
const babelRuntimeVersion = pkg.dependencies['@babel/runtime'].replace(/^[^0-9]*/, '');

const config = [
  // ...
  plugins: [
    // ...
    babel({
      plugins: [['@babel/plugin-transform-runtime', { version: babelRuntimeVersion }]]
    })
  ],
];

The @babel/plugin-transform-runtime plugin enables re-use of Babel's injected helper code, to help reduce the final bundle size.

From the plugin's docs:

Babel uses very small helpers for common functions such as _extend. By default this will be added to every file that requires it. This duplication is sometimes unnecessary, especially when your application is spread out over multiple files.

The version of Babel runtime is pulled from package.json by reading the dependencies:

// rollup.config.js
const babelRuntimeVersion = pkg.dependencies['@babel/runtime'].replace(/^[^0-9]*/, '');

We're also telling the Babel plugin how to handle Babel helper code via babelHelpers (it is recommended to use the "runtime" option for bundling libraries with Rollup), as well as not to touch anything imported from node_modules by setting the exclude option:

// rollup.config.js
import babel from '@rollup/plugin-babel';
// ...
const config = [
  plugins: [
    // ...
    babel({
      babelHelpers: 'runtime',
      exclude: /node_modules/,
      plugins: [
        // ...
      ],
    })
  ],
];

We also need to specify a few presets so that we can use latest JavaScript features, as well as enable React support. These are @babel/preset-env and @babel/preset-react, respectively:

// rollup.config.js
import babel from '@rollup/plugin-babel';
// ...
const config = [
  plugins: [
    // ...
    babel({
      babelHelpers: 'runtime',
      exclude: /node_modules/,
      presets: [
        ['@babel/preset-env', { targets: 'defaults' }],
        ['@babel/preset-react', { runtime: 'automatic' }],
      ],
    })
  ],
];

Plugin: Terser

With Babel configuration out of the way, we only have a few plugins left.

This next one will help us reduce final bundle size by minifying the generated code. It's called @rollup/plugin-terser and uses terser under the hood to minify the code.

We'll be sticking with the defaults it provides, so no need to specify any options:

// rollup.config.js
import terser from '@rollup/plugin-terser';
// ...
const config = [
  plugins: [
    // ...
    terser(),
  ],
];

NOTE: You may want to comment out this plugin if you're trying to debug your generated code, but you'll definitely want to have it enabled for your production bundle.

Plugin: Bundle Analyzer

Lastly, we have rollup-plugin-analyzer. This plugin will print out some useful info about our generated bundle upon successful builds:

// rollup.config.js
import analyze from 'rollup-plugin-analyzer';
// ...
const config = [
  plugins: [
    // ...
    analyze({
      hideDeps: true,
      limit: 0,
      summaryOnly: true,
    }),
  ],
];

export default config;

Config Summary

And with that, we're done configuring Rollup! Here's what your rollup.config.js should look like in the end:

// rollup.config.js
import { fileURLToPath } from 'node:url';
import { createRequire } from 'node:module';

import alias from '@rollup/plugin-alias';
import babel from '@rollup/plugin-babel';
import commonjs from '@rollup/plugin-commonjs';
import nodeResolve from '@rollup/plugin-node-resolve';
import terser from '@rollup/plugin-terser';
import analyze from 'rollup-plugin-analyzer';

const require = createRequire(import.meta.url);
const pkg = require('./package.json');

const makeExternalPredicate = (externalArr) => {
  if (externalArr.length === 0) {
    return () => false;
  }
  const pattern = new RegExp(`^(${externalArr.join('|')})($|/)`);
  return (id) => pattern.test(id);
};

const babelRuntimeVersion = pkg.dependencies['@babel/runtime'].replace(/^[^0-9]*/, '');

const outputOptions = {
  exports: 'named',
  preserveModules: true,
  banner: `/*
 * Rollup Library Starter
 * {@link https://github.com/mryechkin/rollup-library-starter}
 * @copyright Mykhaylo Ryechkin (@mryechkin)
 * @license MIT
 */`,
};

const config = {
  input: 'src/index.js',
  output: [
    {
      dir: 'dist/esm',
      format: 'esm',
      ...outputOptions,
    },
    {
      dir: 'dist/cjs',
      format: 'cjs',
      ...outputOptions,
    },
  ],
  external: makeExternalPredicate([
    ...Object.keys(pkg.dependencies || {}),
    ...Object.keys(pkg.peerDependencies || {}),
  ]),
  plugins: [
    alias({
      entries: {
        src: fileURLToPath(new URL('src', import.meta.url)),
      },
    }),
    nodeResolve(),
    commonjs({ include: ['node_modules/**'] }),
    babel({
      babelHelpers: 'runtime',
      exclude: /node_modules/,
      plugins: [['@babel/plugin-transform-runtime', { version: babelRuntimeVersion }]],
      presets: [
        ['@babel/preset-env', { targets: 'defaults' }],
        ['@babel/preset-react', { runtime: 'automatic' }],
      ],
    }),
    terser(),
    analyze({
      hideDeps: true,
      limit: 0,
      summaryOnly: true,
    }),
  ],
};

export default config;

The example configuration file can be found here for your reference as well.

Keep in mind, this configuration is meant to be the foundation for your library. It serves as a starting point, but there's lots more you can do here with all the plugins available in the Rollup ecosystem. Make sure to explore the awesome curated selection, and see if there's anything else that is applicable to your project.

Package Setup

With Rollup configuration done, let's now configure our package file package.json so that it can be properly packaged and published to NPM.

Scripts

First, let's add a build script, so that we can actually run Rollup:

// package.json
{
  "scripts": {
    "prebuild": "rm -rf dist",
    "build": "rollup -c"
  }
}

This will run Rollup CLI using the configuration we defined in rollup.config.js. Since this file is at the root level, we don't need to specify it explicitly (the -c flag takes care of that).

ESM

As of Rollup v3, we need to ensure that our configuration file is loaded as an ES module by Node.

There are a few ways to do this. One is by using the .mjs extension, and another is by specifying our library package to be ESM, which is done by setting the type to "module" in the package file:

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

Entry Points

We've configured Rollup to output the bundle to the dist folder. And since we've configured our library to have a root-level index.js, we can use this file as the entry point of our package. Since we're publishing a dual-module package, we will need to specify these entry points separately for each of the formats (ESM and CommonJS).

For CommonJS, set the main field to point to the cjs bundle:

// package.json
{
  "main": "./dist/cjs/index.js"
}

Then do the same for ES Modules, by pointing the module field to the esm bundle:

// package.json
{
  "module": "./dist/esm/index.js"
}

Exports

In order to ensure maximum interoperability with tools like Webpack (and others), we should also specify the subpath exports separtely for each module format.

To do this, add an exports field and specify the main entry point's import and require to point to the esm and cjs bundles, respectively:

// package.json
{
  "exports": {
    ".": {
      "import": "./dist/esm/index.js",
      "require": "./dist/cjs/index.js"
    }
  },
}

This is to ensure that we can do both:

// ESM
import { Button } from 'rollup-library-starter';

// CommonJS
const { Button } = require('rollup-library-starter');

Package Files

Lastly, we need to tell NPM which files and folders to include in our package. For this we'll use the files field, which describes the entries to be included when the package is installed as a dependency. In addition to the default includes (package.json itself, README, LICENSE, etc.) we need to specify the folder with output from Rollup.

Add the dist folder to the files array:

// package.json
{
  "files": ["dist"]
}

The full list of package.json configuration options is available here

Running the Build

With package.json setup, let's now run our build and check it out. In the terminal at the root of our project type in npm run build. This will run the Rollup CLI and generate its output in the dist folder. You'll notice that there are also two folders in there: esm and cjs, each containing code in the corresponding module format.

Thanks to the rollup-plugin-analyzer plugin, we also get a summary of our package build:

Wrap Up

And that about does it! Hopefully this recipe gives you a good starting point for your next JavaScript library, and remember to experiment and adjust it as needed.

The full example project is available in GitHub for your reference:

https://github.com/mryechkin/rollup-library-starter

If you've made it this far - thanks for reading, and until next time!

Using NPM Programatically

Mykhaylo Ryechkin 🇺🇦 — Sun, 21 Aug 2022 00:37:29 +0000

Intro

Did you know that you can run npm commands programatically, giving you access to their output? For example, if you wanted to get the exact version of a 3rd-party package installed in your node_modules and display it somewhere in your app?

In this post, I'll show you how to do just that, and how I've recently utilized this in a project.

Background

In my day job, as part of our design system library ecosystem, we're building an internal code sandbox (think of it as a mix between Seek OSS Playroom and QuickPaste). It allows our users try the components from our component library (let's call it @wtf-ds/core) and any other supplementary React code right there in the browser, without having to create a new project in their own environment.

The Requirements

One of the features we were looking to add was a way to display the currently installed versions of the dependencies that users have access to, somewhere in the UI. The sandbox automatically includes react, styled-components and several component library packages in the browser editor, and users should have a way to know what specific versions of those packages they're working with.

It may be tempting to just pull this information from package.json at first:

import package from 'package.json';

const sc = package.dependencies['styled-components'];

However, we quickly run into a problem.

Most of the time, the version specified in package.json won't be exact. It can be either the caret notation (ie. ^5.3.3), or the tilda (~5.3.3), or perhaps just latest. This doesn't exactly give us what we want. An approximate version number is better than nothing - of course - but it's also not as useful as the exact one would be.

For example, whenever there's a new version of styled-components released (eg. 5.3.5), and you do a fresh npm install, the ^5.3.3 notation won't accurately reflect the actual, currently installed version.

We can't rely on the value inside package.json. So how do we solve this?

Well, if we were looking for this info ad-hoc, we could simply run the npm list command in the terminal:

npm list styled-components

which gives us all instances of this package in our node_modules, including any nested dependencies:

wtf-ds@ ~/Projects/wtf-ds
└─┬ @wtf-ds/core@1.0.0 -> ./packages/core
  ├─┬ babel-plugin-styled-components@2.0.7
  │ └── styled-components@5.3.5 deduped
  └── styled-components@5.3.5

We could reduce this down by adding the --depth=0 flag:

npm list --depth=0 styled-components

which now gives us just the top-level instances, ie. what we need:

wtf-ds@ ~/Projects/wtf-ds
└─┬ @wtf-ds/core@1.0.0 -> ./packages/core
  └── styled-components@5.3.5

As you can see above, our package.json has styled-components set to ^5.3.3 but the actual installed version is 5.3.5 (latest at the time of writing this). This is the version we'd like our users to see, so we can't use the caret notation - we need a way to show this version instead.

The Solution

Turns out, you can run npm commands programatically! 🤯

This means that we can now run those npm list commands from within a Node script, and store the output in a simple JSON file - which can then be accessed in our React code.

To do this, you will need a promisified version of the exec method from child_process, which then lets you run whatever command, and have access to its output (in our case it's npm list).

So, I've created a seperate script (called dependencies.js) which parses the output of those commands for each package, and saves that information in a dependencies.json file. This file is then imported in our Next.js app, and the values displayed in the sandbox UI.

To ensure that this file is always up-to-date, it can be run as a postinstall script in package.json:

{
  "scripts": {
    "postinstall": "node scripts/dependencies.js"
  }
}

The script itself is as follows:

// scripts/dependencies.js
const fs = require('fs');
const util = require('util');
const exec = util.promisify(require('child_process').exec);

const package = require('../package.json');

const dependencies = Object.keys(packageData.dependencies).map((dep) => dep);

let promises = [];

if (dependencies && dependencies.length) {
  const filteredList = ['@wtf-ds/core', 'react', 'styled-components'];

  promises = filteredList.map(async (name) => {
    const { stdout } = await exec(`npm list --depth=0 ${name} | grep ${name}`);

    const idx = stdout.indexOf(name);
    const version = stdout.substring(idx + name.length + 1).replace('\n', '');

    return { name, version };
  });
}

Promise.all(promises).then((result) => {
  const data = JSON.stringify(result, null, 2);
  fs.writeFileSync('dependencies.json', data);
});

So, what's happening here?

First, we create a "promisified" version of exec by wrapping it with util.promisify():

const fs = require('fs');
const util = require('util');
const exec = util.promisify(require('child_process').exec);

Then we read our package info from package.json, and create an array of our dependency names:

const package = require('../package.json');

const dependencies = Object.keys(packageData.dependencies).map((dep) => dep);

Then, we filter out only the packages we're interested in:

const filteredList = ['@wtf-ds/core', 'react', 'styled-components'];

This will ensure that we're only showing the relevant packages to our users. Because our "promisified" exec method returns a Promise object, and we need one for each of the packages (above), we will need to store these promises in an array that can be resolved later:

promises = filteredList.map(async (name) => {
  // ... each of the relevant dependencies
});

And now for the ✨magic✨

For each of the packages in the above array, we run the npm list command:

const { stdout } = await exec(`npm list --depth=0 ${name} | grep ${name}`);

This gives us the currently installed version, and the output can be accessed via the stdout variable:

  └── styled-components@5.3.5

Since we only care about the version number, and not everything else in the output, we can parse it and get just the version number itself:

promises = filteredList.map(async (name) => {
  const { stdout } = await exec(`npm list --depth=0 ${name} | grep ${name}`);

  const idx = stdout.indexOf(name);
  const version = stdout.substring(idx + name.length + 1).replace('\n', '');

  return { name, version };
});

There's probably a more elegant way to do this with regex, but I will leave that for you to optimize 😉

With our array of promises ready, all that's left is to resolve them. We do this by using Promise.all():

Promise.all(promises).then((result) => {
  const data = JSON.stringify(result, null, 2);
  fs.writeFileSync('dependencies.json', data);
});

This gives us the result, which is the data that we'd like to store in our JSON file. The resulting output will look something like this:

[
  {
    "name": "@wtf-ds/core",
    "version": "1.0.0"
  },
  {
    "name": "react",
    "version": "18.2.0"
  },
  {
    "name": "styled-components",
    "version": "5.3.5"
  }
]

We can now import this in our React code, and display the relevant data on the UI

Note that you'll need to specify the json import assertion here to import this as a JSON module

import dependencies from 'dependencies.json' assert { type: 'json' };

export default function Dependencies() {
  return (
    <ul>
      {dependencies.map((dep) => (
        <li>
          <b>{dep.name}</b>: {dep.version}
        </li>
      ))}
    </ul>
  );
}

And that's it! 🎉 This is a fairly simple use case, but as you can see we've only scratched the surface here, and hopefully this gives you an idea of what's possible.

The full script is also available as a gist here.

Streamlining your Tailwind CSS workflow with ESLint + Prettier

Mykhaylo Ryechkin 🇺🇦 — Wed, 13 Jul 2022 18:09:20 +0000

Overview

If you're working with Tailwind CSS on a regular basis, there are a few tools at your disposal that can help streamline some of the code authoring workflow.

The Problem

One argument you often hear from opponents of Tailwind CSS is how unreadable it makes your page markup, and in particular the class attribute.

With long strings of numerous Tailwind classes and all sorts of possible combinations, it's understandable how that can become a bit daunting.

But, I'm here to tell you that it doesn't have to be!

The Solution

In this article we'll take a look at how tools like ESLint and Prettier can help us never have to think about class names again, and provide some helpful guidance along the way.

ESLint is a code linter. Linters helps identify issues in our code, ensure consistency and reduce possibilities of bugs. They generally concern themselves with code logic.

Then we have Prettier, which is an opinionated code formatter. It concerns itself more with code style - things like line length, indentation, syntax, etc. Prettier's main job is to ensure consistency in code, no matter the development enviornment or the number of people working on the same file.

Regardless of whether a project is using Tailwind or not, ESLint and Prettier are both tools that should be part of our workflow. A lot of what we do as part of code authoring process can be automated away with these tools, and help reduce the cognitive load while writing code. With Tailwind, this is particularly noticeable.

Both ESLint and Prettier have an extensive 3rd party plugins ecosystem. There are plugins and shared configurations available for all sorts of use cases, enabling us to extend the base functionality of these tools. Frameworks and libraries often provide plugins that are meant to work seamlessly alongside them, whether official or developed by the open-source community, and Tailwind is no exception.

Setup

Installation

First, let's install the necessary libraries.

In addition to core ESLint and Prettier packages themselves, there are two main plugins that we'll need:

eslint-plugin-tailwindcss for ESLint
prettier-plugin-tailwindcss for Prettier

Install these as dev dependencies:

npm install -D eslint eslint-plugin-tailwindcss prettier prettier-plugin-tailwindcss

Configuration

Next, we need to create config files for both ESLint and Prettier.

ESLint

First, let's do ESLint. Create an .eslintrc file at the root of your project:

// .eslintrc
{
  "extends": [
    "eslint:recommended",
    "plugin:prettier/recommended",
    "plugin:tailwindcss/recommended"
  ],
  "env": {
    "browser": true,
    "es2021": true
  },
  "parserOptions": {
    "ecmaVersion": 2021,
    "sourceType": "module",
    "ecmaFeatures": {
      "jsx": true
    }
  },
  "plugins": ["tailwindcss"]
}

Here we're extending the recommended rule sets from ESLint, Prettier, and the Tailwind CSS plugin, as well as specifying eslint-plugin-tailwindcss itself to be used as a plugin. We're also setting some defaults for our project environment and parser options.

NOTE: This is the most basic setup. It's highly recommended to look into the advanced configuration options for ESLint, and take the time to setup additional plugins and options appropriate for your project environment.

Prettier

For Prettier, we'll stick with most of the defaults, overriding just a couple of options. Create a .prettierrc file:

// .prettierrc
{
  "printWidth": 90,
  "singleQuote": true
}

These are personal preferences - see the complete list of options and adjust as needed.

One neat thing with Prettier is that you don't need to explicitly list the plugins that you'd like to use. So long as they're in the same node_modules folder as Prettier itself, they're loaded automatically. Since we installed everything in our project already, we're all set in that regard.

Setting Up Scripts

Let's now create some scripts to help automate the linting process. In package.json, add a lint and format scripts. For demo purposes, let's assume all of our code is in src folder:

// package.json
{
  "scripts": {
    "lint": "eslint --fix src",
    "format": "prettier --write src"
  }
}

The lint script will run ESLint on everything inside our src folder, and the --fix flag tells it to fix any automatically-fixable issues at the same time as well. This will use the config specified in the .eslintrc file we created earlier, including the plugins.

Similarly, the format script will run Prettier and format it using the options specified in .prettierrc. As mentioned earlier, Prettier loads its plugins automatically, so the Tailwind plugin will be loaded for us already.

For complete list of available CLI options, see Prettier docs.

Using Scripts

With our scripts defined, we can now run these as part of our workflow to lint and format our code.

To test it out, run npm run lint. Here's a real example from my personal site that I ran into recently:

As you can see, eslint-plugin-tailwindcss helped identify some deprecated classes that I was still using. Neat! I'd been using Tailwind v3 for some time now, without realizing there were deprecated class names in my code. Without this plugin, there's a good chance I still wouldn't have noticed this.

Similarly, prettier-plugin-tailwindcss tells me that a number of Tailwind classes aren't sorted properly in a few places. Little while back, Tailwind team introduced official class sorting, which with the help of this plugin sorts classes in a specific order. This order essentially follows how Tailwind structures the classes in the final CSS output. Having them sorted the same way in the code helps to visualize the cascade, which IMO is extremely helpful.

Pre-commit Hook

Running these scripts manually every time is not great. Let's fix that!

To help automate the process, we can use husky to create a pre-commit hook that will run lint-staged, which in turn will run these linting scripts on staged files, before committing them.

To do this, run the following command:

npx mrm@2 lint-staged

This does a few things:

Installs lint-staged and husky
Creates a pre-commit hook in the .husky directory which runs lint-staged
Updates package.json with config for lint-staged

Notice the new entry in package.json:

// package.json
"lint-staged": {
  "*.js": "eslint --cache --fix",
  "*.{js,css,md}": "prettier --write"
}

Let's update this to use our scripts instead:

// package.json
"lint-staged": {
  "*.js": "npm run lint",
  "*.{js,css,md*}": "npm run format"
}

This will tell lint-staged to run our lint script on all staged JS files, and format on JS, CSS and MD(X) ones (as always, adjust this as needed). Now, before any code is committed, it's guaranteed to be linted and properly formatted. If either of those scripts fails, a commit will not proceed and we'll see what the issues are in the output:

Integrating with VSCode

Now this is where it gets even better. If you're using Visual Studio Code, there are extensions that can help automate things further.

Extensions

Install the following VSCode extensions:

ESLint (dbaeumer.vscode-eslint)
Prettier - Code Formatter(esbenp.prettier-vscode)
Tailwind CSS IntelliSense(bradlc.vscode-tailwindcss)

The first two integrate ESLint and Prettier into VSCode, which will let VSCode underline any problematic code that is identified:

Hovering over the issue will show more details:

The Tailwind CSS IntelliSense extension adds intellisense for Tailwind classes. This will let VSCode show suggestions for Tailwind classes, and what CSS they output. It even works with any custom classes you have defined in your Tailwind config. Very handy!

Now, as long as you have the .eslintrc and .prettierrc configuration files in your root, VSCode will highlight any applicable issues in your code, using the provided configurations.

If you'd like to take it a step further, you can also create a .vscode/extensions.json file in your repo to provide a list of recommended extensions for anyone cloning it:

// .vscode/extensions.json
{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "bradlc.vscode-tailwindcss",
  ]
}

Enabling auto-format on save

The last thing we want to do is enable automatic code formatting whenever we save a file in VSCode. This way, you let the tools worry about style and formatting, and can just focus on writing code.

First, open up your VSCode settings.json file: Preferences: Open Settings (JSON). Make sure that the default formatter is set to the Prettier extension:

"editor.defaultFormatter": "esbenp.prettier-vscode"

Then, enable format on save:

"editor.formatOnSave": true

Note that these settings can also be specified separately for specific languages:

"[html, javascript]": {
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true
}

Now, whenever you save a file, Prettier will format it using the VSCode extension. This means that not only do you get all the nice formatting from Prettier config, but your Tailwind classes will also be in the same consistent order thanks to the Tailwind CSS IntelliSense plugin.

Shared Config

If you like this setup (and are using React and Next.js) - all of the plugins mentioned here (and a few others) are included in my personal shared config:

✨ ACME ESLint Config ✨

These days Next.js and Tailwind are my default go-to's when building a new project, and I'll generally want the same rules applied throughout, including the same set of plugins. This shareable config makes it easy to use my preferred configuration, and not have to worry about setting up everything from scratch every time. Just install, extend, and you're good to go!

This particular config is based on the popular Airbnb Javascript Style Guide and extends the corresponding eslint-config-airbnb, as well as few others that I always find myself using. Feel free to use it in your project as well!

Build Your Own

If you're interested in making one of these on your own, check out my video tutorial on how to do just that.

Thanks for reading!

JavaScript Module Ecosystem

Mykhaylo Ryechkin 🇺🇦 — Wed, 06 Apr 2022 15:44:00 +0000

Intro

If you've done web development for any amount of time, there's a good chance you've had to work with tools like Webpack, Rollup, Browserify and other front-end tooling systems. But do you know why we started using them in the first place, and why they are still part of our everyday workflow?

In this post, we'll take a look at one of the core areas of JavaScript - the module ecosystem - and why tools like the ones mentioned above are required (🥁).

Overview

Before we talk about what modules are, let's take a brief look at some JavaScript history, and why modules and their different formats came to be.

For most of its early life, "the web" (ie. browsers) had only one way to load script files, via plain <script> tags:

<head>
  <script src="a.js"></script>
  <script src="b.js"></script>
  <script src="c.js"></script>
</head>

This is now what we refer to as "classic" scripts. In classic scripts, all scope is shared (via the global window object). There is also no explicit way to specify dependency between files, so order of <script> tags matters. You need to be careful about the order in which files are imported, and be mindful of subsequent changes in them.

This may not be such a big deal for simple scripts and adding some interactivity to a static page, but nowadays we run entire applications comprised of complex JavaScript - and as you can imagine, with the classic scripts approach things can get really messy, really quickly. There had to be another - better - way of loading JavaScript.

With the advent of Node in 2009, we also needed a way to load and run JavaScript on the server as well. With one key difference, however. In high-latency client environments like the browser, it's faster to send one large file, rather than many small ones. By contrast, in a server environment files are co-located on the same filesystem, and as such can be accessed virtually instantly. Node can load as many individual files as necessary, without any performance implications due to latency.

And this is where the module system and JavaScript tooling come into play.

So what are modules anyway?

Modules are a mechanism for splitting up JavaScript into smaller, manageable logical chunks of code. They are essentially a way to organize, and ship code in JavaScript. Modules let us write code in one file that explicitly depends on (or is a dependency of) code in another file.

When browsers and Node load a JavaScript program, they build a map of all the modules that are used in the project. This process is called module resolution, and the map of these modules and their relationship to each other is often referred to as a module graph. The resolution algorithm itself is different depending on the runtime environment.

Module Formats

There are several different module formats: ES6 Modules (or ESM), CommonJS (or CJS), AMD and UMD are among the ones you're likely to come across.

Why so many?

As mentioned earlier, there are different JavaScript runtime environments to consider. We have the browser with its various implementations (Chrome, Firefox, Safari, etc), and then the server, with runtimes like Node and Deno. Each has its own different set of concerns, as we saw earlier as well.

That made it tricky to land on a specification. For a long time, there wasn't a single, agreed-upon standard between those environments in terms of how to deal with modules. There were concurrent attempts at solving the problem (even JavaScript standards themselves are async 🥁), and what resulted was an emergence of the module formats mentioned above.

Eventually, module format spec was standardized by the TC39 committee, with ESM becoming the de-facto "future-proof" standard going forward. Along with CommonJS, it is the format you are most likely to come across and work with today.

Module Specifiers

Modules are loaded using keywords like import:

import user from './module.js';

and require:

const user = require('./module');

These are called module specifiers. They can be either full or relative URL's:

// Full URL
import { greet } from 'https://some.cdn.com/module.js';

// Relative URL
import { greet } from './module.js';

They can also be "bare" (ie. without specifying file extensions):

import { greet } from './module';

NOTE: the bare specifier is not yet supported in browsers as of the writing of this post, and requires tools to interpret the syntax.

Module Scope

The way modules are loaded is different between browsers and server environments (ie. Node).

Browser loads modules as stateful singletons - meaning that the same module will share its state anywhere it's imported in the application, for the duration of that session. A good mental model to help understand this better is:

When you import a module, you're not getting a piece of code that you're running, you get a reference to an object in memory

(shoutout to Sam Selikoff and Ryan Toronto from Frontend First Podcast whose discussion in Episode #100 helped a great deal in understanding these concepts)

In a Node environment, however, modules are loaded as instances. This means that each imported module instance in your app has its own state, not shared with any of the other instances of the same module - so you no longer have a global module state.

Module Exports

By default, everything that is declared inside a module is scoped locally to that module. If you want to make something accessible outside the module (and really, that's the whole point), you need to export it. There are several ways of exporting, and which one to use will depend on the target module format (ie. ESM vs CommonJS), as well as what kind of export you are doing.

In general, ES modules have two types of exports: default and named. You can export any top-level function, class or variable.

When to use which?

That really depends on the intended use and structure of the module. One approach is to export default the main functionality of a module, to denote its main intent. Then any supplemental functionality or data are treated as named exports.

Format: ES6 Modules (ESM)

ESM is the standard established and governed by TC39 committee. It is the modern standard for JavaScript modules going forward, and is supported natively in all major browsers, as well as newer versions of Node (15 and above). For Node 14 and below, ESM can be enabled with the help of 3rd party libraries (eg. esm).

ESM uses .js and .mjs extensions (browser and Node, respectively), and utilizes import keyword for importing, and export for exporting.

When exporting from ESM, you can do either default or named exports:

// module.esm.js

const user = { name: 'Human', location: 'Planet Earth' };

// named exports
export const GREETING = 'Hello';

export function greet(greeting, user) {
  return `${greeting}, ${user.name} from ${user.location}`;
}

// default export
export default user;

Importing can be done using default imports:

import user from './module.js';

or using named imports, where the name of the thing you're importing goes inside curly braces:

import { greet } from './module.js';

You can also import both default and named at the same time, as well as multiple named imports, using this one-line convention:

// index.js

import user, { greet, GREETING } from './foo.js';

console.log(greet(GREETING, user)); // "Hello, Human from Planet Earth"

console.log(GREETING); // "Hello"
console.log(user); // { name: 'Human', location: 'Planet Earth' }

Some characteristics and rules of ESM:

import's are static and asynchronous (browsers are async in their nature, after all)
import's must live at the root level
import's also get hoisted, so can be written anywhere in the code
import specifier can only accept a string literal (ie. it can't be dynamically generated)

Due to this nature of ESM, code written in it can also be statically analyzed and tree-shaken by tools like Rollup , so that no extra unused JavaScript is included in the bundle.

"Tree-shaking" or what is also known as "dead code elimination" is a process through which tools like Webpack and Rollup do static analysis of your code, and try to determine which modules aren't utilized. Doing this allows these tools to drastically cut down on the overall bundle size, and only include what's actually needed to run your application or library code. ESM is much more compatible with this process.

To load an ESM module in a browser, we need to specify type as "module" in the script tag:

<script type="module" src="/some-module.js"></script>

When loading in Node, there are several ways to target ESM:

Set type field to "module" in the package.json of the project
Use the .mjs file extension
Using --input-type=module flag via Node CLI

Format: CommonJS (CJS)

CommonJS (or CJS) is a module system that originated in Node. It has been the prevalent format in the Node ecosystem for many years, and is still used in many libraries and tools today.

CJS modules are exported via module.exports, and use the require keyword for importing:

// module.cjs.js

const user = { name: 'Human', location: 'Planet Earth' };

const GREETING = 'Hello';

const greet = (greeting, user) => `${greeting}, ${user.name} from ${user.location}`;

module.exports = { greet, GREETING };

module.exports.default = user;

Note that the above can also be written this way:

module.exports.greet = greet;
module.exports.GREETING = GREETING;
module.exports.default = user;

To import CommonJS, use the require keyword :

// index.js

const { default: user, greet, GREETING } = require('./module.js');
console.log(greet(GREETING, user)); // "Hello, Human from Planet Earth"
console.log(GREETING); // "Hello"
console.log(user); // { name: 'Human', location: 'Planet Earth' }

CommonJS uses .js and .cjs file extensions, and it cannot be loaded directly in a browser. For that exist specific tools that allow us to run CommonJS code in a browser environment, such as Browserify, Rollup and others.

Unlike ES6 Modules which are loaded asynchronously, CommonJS module resolution is synchronous. Remember how we talked about server environments having virtually no latency for module loading? This is why.

Due to this low latency, CJS modules are loaded dynamically, at runtime. The module specifier is a function, which can accept JS expressions, making require dynamic. This allows us to do things like conditional imports:

const { thing } = require(isTrue ? './a.js' : './b.js');

However, this has certain tradeoffs. For instance, JavaScript tools can't know what's going to be loaded ahead of time. This unfortunately makes CommonJS modules not compatible with tree-shaking. It's much less of a concern on the server - since you're not sending code to the client - and if we remember that the CJS module format originated in Node, then it make sense why this format wouldn't concern itself with that.

Interoperability

With all the differences between the module formats we've seen so far, and the different runtime environment gotchas, it's evident why there is such a strong need for a single, standard module specification going into the future.

Now let us ask a question:

"What happens if you want to use a CommonJS module inside an ES6 module? Or the other way around?"

The short answer is, it depends. Browsers don't support this natively - so we have to yet again rely on our tooling to support this functionality.

Bundlers and transpilers such as Babel, Webpack, Rollup etc. have been doing a decent job of ensuring compatibility between the different module formats and runtimes, however some edge cases and issues still exist today.

We'll take a closer look at some of these interoperability concerns in a future post.

Closing Thoughts

Before wrapping this up, let's consider something for a second. If there are so many issues with interoperability, then why are we still using CommonJS?

The answer to that is not a simple one, unfortunately. First, CommonJS is everywhere. It's still the main format used in Node, and has been for many years (Node only recently started supporting ESM). The NPM ecosystem is huge. And though many popular library authors have been shipping both ESM and CJS compatible code, there are still many packages out there that are exclusively CommonJS. This is especially true for legacy systems, and enterprise code, which may not have the luxury of moving its entire codebase to an entirely different module system.

Second, it's a lengthy process. Lots of large (and popular) codebases and tools still use and heavily rely on it. So while the goal may be to move to a single unified format down the road (ESM), it is not an overnight change, and will take some time for the entire ecosystem to migrate to it.

There are some folks who are eager to help move it forward, though others are against the idea altogether. Both sides present valuable arguments, and the discussions are worth checking out if you're interested in the topic.

In a future post, we'll take a look at how to ship your library code in both ESM and CommonJS using Rollup.

Until next time!

User Authentication in Next.js with Supabase

Mykhaylo Ryechkin 🇺🇦 — Wed, 24 Nov 2021 04:16:34 +0000

IMPORTANT NOTE: This article was written for Supabase v1, which is now outdated. Though everything still works (to the best of my knowledge), please be aware that the libraries and versions mentioned here are now outdated. See the ✨NEW✨ updated guide on using Supabase v2 and Next.js 13 instead.

Intro

Supabase has been getting a lot of attention in the tech community, and for good reason. This open source platform makes it super easy to get started building complex full-stack applications, and in this post we will take a look at how to utilize one of its core offerings: User Authentication.

Overview

One of the things that stands out about Supabase almost immediately is just how easy it is to get started. You can be up and running in quite literally minutes, and Authentication is no exception. It provides a fully integrated solution, including user management and email notifications, with no reliance on any external authentication services. And with Supabase being open source, you have complete control and ownership of your user data, as it's all stored in the same PostgreSQL database.

Supabase provides several different authentication mechanisms out of the box:

Basic Email authentication
Magic Link or a one-time login with email
Social logins: Google, Facebook, GitHub, Azure, Gitlab, Twitter, Discord, and Bitbucket
Phone / SMS login using Twilio integration

In this tutorial we'll be using Email authentication, with ability to reset forgotten password.

Just want the code? GitHub repo available here. Live version is available as well.

Supabase Client

Supabase provides a client library that makes it supa easy to get started in your project. It is a modular library, comprised of several different sub-libraries, each enabling integration with the specific sub-system:

@supabase/postgrest-js for PostgREST (REST API for PostgreSQL)
@supabase/realtime-js for Realtime (realtime connection to PostgreSQL via websockets)
@supabase/gotrue-js for GoTrue (fork of Netlify's authentication and user management API)

The single @supabase/supabase-js bundle combines the three libraries into one, and adds some ease-of-use enhancements, making it the perfect Supabase companion for your projects.

It's worthwhile to note that the client library is also available in several other different languages as well - including C#, Python, Rust and Dart.

Supabase UI

Supabase also provides an open source component library called Supabase UI, which is a collection of common UI components and utilities that are used across the range of Supabase products. Its styling is heavily inspired by Tailwind CSS, so you know it will look good out of the box.

We will be using the Auth component, which provides all the necessary screens and integrations for the various authentication flows. In particular, we'll need to be able to perform the following:

Sign Up (Email)
Sign In (Email)
Sign Out
Reset Password
Update Password

As you can see, that's quite a bit of UI and state logic that we would need to implement ourselves from scratch. Using a component that provides all of that already wired up out of the box will be a big time saver.

In this tutorial, we'll take a look at everything you need to use this component in your own application, as well as some ways to customize it to your needs.

NOTE: At the time of writing this post, Supabase UI is in early development stages, so the API and some features may still change in the full release. For example, theming is not currently supported, and is the reason we'll need to perform some workarounds later on.

Supabase Setup

You will need to create a Supabase account if you haven't already done so. Supabase provides a generous free tier for their cloud solution, so it's easy to get started. Alternatively, since it's open-source, you can also host your own as well.

Once signed up, go to Supabase Dashboard and create a new project.

API Keys

In order to be able to access the Supabase API via our JS client, we will need to have API keys available in the app.

In the dashboard, go to Settings > API. As you'll see, by default an anonymous public API key is already available. This will be enough for our needs. Take note of this value, as well as the URL:

Make sure to keep these on hand, as we'll need them later on.

Next.js Project Setup

For this tutorial, we'll be using Next.js and the Tailwind CSS starter template 🚀

To do that, run:

npx create-next-app --example with-tailwindcss next-with-supabase-auth

Then, install both Supabase Client, and Supabase UI dependencies:

npm install @supabase/supabase-js @supabase/ui

That's all we need to get started. Let's code!

Application Structure

Our application will be pretty simple. The main Home page will show the different authentication screens - Sign In, Sign Up, Forgot Password, etc. It wil also show the authentication status, a button linking to a Profile page, and a button to sign out.

The Profile page will display the currently logged-in user's data, and a button to go back to Home page. It also needs to be a "protected" page, meaning that only authenticated users can access it. We'll take a look at how to accomplish this both on client and server-side in later steps.

First, let's scaffold out the base pages.

Home Page

Let's go ahead and put some placeholder content on the main page to start with:

// src/pages/index.js;
import Layout from '@/components/Layout';

export default function Home() {
  return (
    <Layout>
      <h2>Welcome!</h2>
      <code className="highlight">You are logged out</code>
    </Layout>
  );
}

Profile Page

Similarly, let's put some placeholder content on the Profile page:

// src/pages/profile.js
import Link from 'next/link';

import Layout from '@/components/Layout';

export default function Profile() {
  return (
    <Layout>
      <h2>User Profile</h2>
      <div className="heading">Last Signed In:</div>
      <code className="highlight">N/A</code>
      <Link href="/">
        <a className="button">Go Home</a>
      </Link>
    </Layout>
  );
}

Where Layout is our main layout container, abstracted into a component in components/Layout.js:

// src/components/Layout.js
import Head from 'next/head';

export default function Layout({ children }) {
  return (
    <div className="flex min-h-screen flex-col items-center justify-center py-2">
      <Head>
        <title>Next.js with Supabase Auth</title>
        <link rel="icon" href="/favicon.ico" />
      </Head>

      <main className="flex w-full flex-1 flex-col items-center justify-center px-8 text-center sm:px-20">
        <h1 className="text-5xl font-bold sm:text-6xl">
          Next.js with <span className="font-black text-green-400">Supabase</span>
        </h1>
        <div className="mt-8 inline-flex w-full max-w-sm flex-col space-y-8">
          {children}
        </div>
      </main>
    </div>
  );
}

TIP: Enable absolute import paths and module aliases in Next.js for shorter imports, like @/components etc.

We've also abstracted some CSS classes that will be used throughout the app in the styles/globals.css file (using Tailwind):

/* src/styles/globals.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  h2 {
    @apply py-4 text-4xl font-black text-gray-800;
  }

  .button {
    @apply custom-focus rounded-full border-2 border-green-400 bg-white px-8 py-2 font-bold text-green-400 hover:bg-green-400 hover:text-white focus:bg-green-400 focus:text-white;
  }

  .button-inverse {
    @apply custom-focus rounded-full border-2 border-white bg-green-400 px-8 py-2 font-bold text-white hover:border-green-400 hover:bg-white hover:text-green-400 focus:border-green-400 focus:bg-white focus:text-green-400;
  }

  .custom-focus {
    @apply focus:border-green-400 focus:outline-none focus:ring-2 focus:ring-green-400 focus:ring-offset-2;
  }

  .heading {
    @apply text-lg font-semibold text-gray-700;
  }

  .highlight {
    @apply ml-1 rounded-lg bg-gray-100 p-2 font-mono;
  }
}

Adding Authentication

With the base of our project scaffolded out, we can start working on the authentication layer.

Initializing Supabase

Supabase Client lets us easily work with the Supabase API, and manages our authentication and user data on the front-end. In order to initialize it, we will need to specify the URL and the public API key from the previous step.

We can do this by setting those values as environment variables in Next.js. Create a .env.local file in the root of the project, and set the values to the ones from the dashboard earlier:

// .env.local
NEXT_PUBLIC_SUPABASE_URL=<value>
NEXT_PUBLIC_SUPABASE_ANON_KEY=<value>

Next, let's create a separate file for our Supabase Client instance. Name this file client.js and put it in lib folder at the root of the project:

// src/lib/client.js
import { createClient } from '@supabase/supabase-js';

export const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY
);

Now whenever we need to use Supabase Client, we can simply import it and access the available functionality.

Authentication Provider

In order to handle all the authentication logic in our app, we're going to use the concept of an authenticaion provider. This pattern was heavily inspired by Kent C. Dodds blog post on this topic, and follows a lot of the same basic principles.

We'll call this AuthProvider and use it as the top-level component in our app, thereby providing user data and authentication functionality throughout. It will utilize React Context, and provide the session and user objects from Supabase Client, as well as the signOut function. The rest of the authentication flows will be handled by the Auth component from Supabase UI, which we'll get to in later steps.

Inside the lib folder, create a file auth.js, and add the following:

// src/lib/auth.js
import { createContext, useContext, useEffect, useState } from 'react';

export const AuthContext = createContext();

export const AuthProvider = ({ supabase, ...props }) => {
  const [session, setSession] = useState(null);
  const [user, setUser] = useState(null);

  return (
    <AuthContext.Provider
      value={{
        session,
        user,
        signOut: () => supabase.auth.signOut(),
      }}
      {...props}
    />
  );
};

export const useAuth = () => {
  const context = useContext(AuthContext);
  if (context === undefined) {
    throw new Error('useAuth must be used within an AuthProvider');
  }
  return context;
};

Here, we have the main AuthProvider, which we'll need to wrap our application in. It provides the user and session values, as well as exposes the signOut function from Supabase Client. To access these values in our app pages, we've also created the useAuth hook, which simply pulls the values from the AuthContext.

Now before we can use it, we need to make AuthProvider the top-level component of our application. We'll do this by adding the following to pages/_app.js:

// src/pages/_app.js
import { AuthProvider } from '@/lib/auth';
import { supabase } from '@/lib/client';

// ...

function MyApp({ Component, pageProps }) {
  return (
    <AuthProvider supabase={supabase}>
      <Component {...pageProps} />
    </AuthProvider>
  );
}

Where supabase is our Supabase Client instance. Now we can freely use the useAuth hook in our app and access the session and user objects.

Getting User Data

Let's update the Home page to utilize some of the user data, and add a few more UI elements for the authenticated state. We'll add a link to the Profile page, and a button to log out the current user (by calling the signOut function). We'll also display the user's role as a badge. Feel free to get more creative here 😄

// src/pages/index.js
import { useAuth } from '@/lib/auth';

export default function Home() {
  const { user, signOut } = useAuth();

  // ...

  return (
    <Layout>
      {user && (
        <>
          <h2>Welcome!</h2>
          <code className="highlight">{user.role}</code>
          <Link href="/profile">
            <a className="button">Go to Profile</a>
          </Link>
          <button type="button" className="button-inverse" onClick={signOut}>
            Sign Out
          </button>
        </>
      )}
    </Layout>
  );
}

Adding Supabase UI

As mentioned earlier, we will need to support the following auth flows: Sign Up, Sign In, Sign Out, Reset Password, Update Password.

Normally this would take quite a bit of time to build from scratch - we'd need to create several different forms, add input validation, error handling, state and UI logic, etc. As you can see, the list gets rather long rather quickly.

Supabase makes this easy for us to do as well. Using the Auth component from Supabase UI, we can add all of these required screens to our app with fairly minimal effort, with the aforementioned functionality already included.

To do this, we'll use the Auth component on the main landing page, and pass it our Supabase Client instance. In pages/index.js, add:

// src/pages/index.js
import { Auth } from '@supabase/ui';

import { supabase } from '@/lib/client';

// ...

return (
  // ...
  {!user && <Auth supabaseClient={supabase} />}
  // ...
);

We pass our Supabase Client instance to it via the supabaseClient prop, and voila! 🎉 Now we have a shiny new UI, with all of the required forms to handle the login flows. However, before we can fully test this, we'll need to setup a few more things.

Handling Auth State Change

What happens if the authenticated state changes in Supabase Client? For example, when a user successfully logs in, or the current user signs out? Our application will need to know about these changes in the state. Which means that we also need a way to update our user and session data whenever this happens. We can do this by adding an event listener on the onAuthStateChange method in Supabase Client.

Back in our lib/auth.js file, create authListener for the onAuthStateChange event inside a useEffect hook (on initial load):

// src/lib/auth.js
// ...
useEffect(() => {
  const activeSession = supabase.auth.session();
  setSession(activeSession);
  setUser(activeSession?.user ?? null);

  const { data: authListener } = supabase.auth.onAuthStateChange(
    (event, currentSession) => {
      setSession(currentSession);
      setUser(currentSession?.user ?? null);
    }
  );

  return () => {
    authListener?.unsubscribe();
  };
}, []);
// ...

Now whenever auth state in Supabase Client changes, our user and session state objects will be updated as well, and this data will be in sync with Supabase Client.

Switching Auth Views

We need a way to tell the Auth component which screen to show as a result of the auth state change. For example - when a user signs out, we want our Auth component to show the Sign In screen again. We can do this by passing view prop to the Auth component, which tells it which authentication flow to show. The event received by onAuthStateChanged will dictate which view we should be showing. We'll see how this gets utilized for updating a user's password in a later step.

First, let's store all the possible values for both the VIEWS and EVENTS in lib/auth.js:

// src/lib/auth.js
// ...
export const EVENTS = {
  PASSWORD_RECOVERY: 'PASSWORD_RECOVERY',
  SIGNED_OUT: 'SIGNED_OUT',
  USER_UPDATED: 'USER_UPDATED',
};

export const VIEWS = {
  SIGN_IN: 'sign_in',
  SIGN_UP: 'sign_up',
  FORGOTTEN_PASSWORD: 'forgotten_password',
  MAGIC_LINK: 'magic_link',
  UPDATE_PASSWORD: 'update_password',
};
// ...

We'll need to keep track of the current view in our AuthProvider, so let's add it as view to the context as well:

// src/lib/auth.js
export const AuthProvider = ({ supabase, ...props }) => {
  const [view, setView] = useState(VIEWS.SIGN_IN);
  // ...
  useEffect(() => {
    // ...
    const { data: authListener } = supabase.auth.onAuthStateChange(
      (event, currentSession) => {
        setSession(currentSession);
        setUser(currentSession?.user ?? null);

        switch (event) {
          case EVENTS.PASSWORD_RECOVERY:
            setView(VIEWS.UPDATE_PASSWORD);
            break;
          case EVENTS.SIGNED_OUT:
          case EVENTS.USER_UPDATED:
            setView(VIEWS.SIGN_IN);
            break;
          default:
        }
      }
    );
    // ...
  }, []);

  return (
    <AuthContext.Provider
      value={{
        session,
        user,
        view,
        signOut: () => supabase.auth.signOut(),
      }}
      {...props}
    />
  );
};

Here we're setting the view to UPDATE_PASSWORD when PASSWORD_RECOVERY event is dispatched, and to SIGN_IN when user logs out, or user is updated in session. Now all that's left is to pass this value to the Auth component. In our main page pages/index.js, update the following:

// src/pages/index.js
export default function Home() {
  const { user, view, signOut } = useAuth();
  // ...
  return (
    // ...
    {!user && <Auth view={view} supabaseClient={supabase} />}
    // ...
  );
}

Authentication Flows

With everything in place, we're now ready to try out the authentication flows. Make sure that you have the environment variables setup as outlined earlier, and then run the app with npm run dev and load localhost:3000.

Sign Up

First, let's register our user. On the landing page, click on "Sign up" link, which will take you to the Sign Up form.

Enter your email and password, and press the "Sign up" button. This will send a confirmation email to the address provided, with a link to complete the registration process. It uses the default email template, which can be updated on the Templates page in Supabase Dashboard settings:

Note as well that the default URL in the link is set to http://localhost:3000:

This works for development, but will need to be updated to the corresponding URL when running in production environments. See this GitHub discussion for more details.

Clicking the confirmation link will redirect you to the site URL (http://localhost:3000), along with an access_token and type, which is verified by the Supabase Client. It then sets the local session, and broadcasts the SIGNED_IN event.

Sign In

After a user signs in (either via Sign In form, or after clicking confirmation link, as above), Supabase Client sets the user session in localStorage under the supabase.auth.token key:

{
  currentSession: {
    provider_token: null,
    access_token: '<access_token>',
    expires_in: 3600,
    expires_at: 1635127600,
    refresh_token: '<refresh_token>',
    token_type: 'bearer',
    user: {
      id: '43cf36c1-9940-46e7-980a-fe1243b0e43c',
      aud: 'authenticated',
      role: 'authenticated',
      email: 'darth@empire.com',
      email_confirmed_at: '2021-10-25T01:06:38.040501Z',
      phone: '',
      confirmation_sent_at: '2021-10-25T01:06:09.418358Z',
      confirmed_at: '2021-10-25T01:06:38.040501Z',
      email_change_confirm_status: 0,
      last_sign_in_at: '2021-10-25T01:06:38.041156Z',
      app_metadata: { provider: 'email' },
      user_metadata: {},
      created_at: '2021-10-25T01:06:09.41273Z',
      updated_at: '2021-10-25T01:06:09.41273Z',
    },
  },
  expiresAt: 1635127600,
}

This also broadcasts the SIGNED_IN event, which gets picked up by our onAuthStateChanged listener we had setup earlier. The session, user and view are also updated as a result.

Sign Out

Signing out a user is as easy as calling the signOut function:

// src/pages/index.js
// ...
const { user, view, signOut } = useAuth();
// ...
<button type="button" className="button-inverse" onClick={signOut}>
  Sign Out
</button>;
// ...

This will remove the signed in user from the browser session, clear any associated items from localStorage, and fire the SIGNED_OUT event. Since our onAuthStateChange event handler is already setup, it will set the Auth view to SIGN_IN, so that our users are presented with the Sign In form again:

// src/lib/auth.js
// ...

switch (event) {
  // ...
  case EVENTS.SIGNED_OUT:
  case EVENTS.USER_UPDATED:
    setView(VIEWS.SIGN_IN);
    break;
  // ...
}
// ...

The Auth component will detect this change, and render the sign-in form.

Reset Password

If a user had forgotten their password, they can request a password reset. From the sign in screen, click on "Forgot your password?" and enter the email used to register:

After submitting the form, Supabase will send a password reset email with a link. Remember that you can update this email template via Supabase Dashboard as well if you'd like.

When a user clicks the link in the email, they'll be redirected to:

<SITE_URL>#access_token=x&refresh_token=y&expires_in=z&token_type=bearer&type=recovery

where type=recovery indicates that this is a Reset Password flow. Normally, our app would need to detect this and present the user with a password reset form. However, since we are using Supabase Client and Supabase UI, all of that is made much easier.

Earlier we had setup the onAuthStateChange listener to wait for specific auth events and update the view accordingly. When the above request comes in, Supabase Client dispatches the PASSWORD_RECOVERY event, which sets the view to update_password. We're not quite done, however.

You see, as part of the reset password flow in GoTrue, user is temporarily logged in with the verification token, before actually updating the password. This is by design, however it means that we need to add some additional checks for this in our app.

Since we're relying on user to determine whether to show the auth forms, we need to check for the UPDATE_PASSWORD view explicitly, and render the corresponding form then. Luckily for us, Auth from Supabase UI also exports the UpdatePassword component, which we can use on its own.

Add this conditional to check for the view on the Home page:

// src/pages/index.js
export default function Home() {
  const { user, view, signOut } = useAuth();

  if (view === VIEWS.UPDATE_PASSWORD) {
    return (
      <Layout>
        <Auth.UpdatePassword supabaseClient={supabase} />
      </Layout>
    );
  }
  // ...
}

Now when a user clicks on the link, they'll be presented with this screen:

Behind the scenes, when a user submits the new password, Supabase UI will call the update method in Supabase Client, which updates the user on the backend and sets the new password. If successful, Supabase Client then dispatches the USER_UPDATED event, which (once again) gets picked up by onAuthStateChange listener, and updates our user and session data.

Go ahead and give that a try. You should now see the logged-in state of the app.

Server-Side Rendering (SSR)

All of the above examples are doing authentication on the client-side. Let's also take a look at how do this on the server, using Next.js API routes and server-side rendered pages.

This will allow us to do protected routes to limit access only to authenticated users, and redirect otherwise. It will also help eliminate a flash of unauthenticated state on initial page load, which can happen with the client-side only approach.

Let's add this to the existing Profile page.

First, we need to create a new API route. Create a new auth.js file in the pages/api folder:

// src/pages/api/auth.js
import { supabase } from '@/lib/client';

export default function handler(req, res) {
  supabase.auth.api.setAuthCookie(req, res);
}

Calling the setAuthCookie method will set the current session in a cookie, allowing us to persist it to the server.

Next, we need to ensure that whenver authentication state changes, that change gets propagated down (via the above API). To do this, update AuthProvider in lib/auth.js to call the /api/auth API with the current session in the onAuthStateChange handler:

// src/lib/auth.js
export const AuthProvider = ({ supabase, ...props }) => {
  // ...
  useEffect(() => {
    // ...
    const { data: authListener } = supabase.auth.onAuthStateChange(
      (event, currentSession) => {
        // ...
        fetch('/api/auth', {
          method: 'POST',
          headers: new Headers({ 'Content-Type': 'application/json' }),
          credentials: 'same-origin',
          body: JSON.stringify({ event, session: currentSession }),
        }).then((res) => res.json());
      }
    );
    // ...
  }, []);
  // ...
};

We also need to enable server-side rendering on the Profile page, and check for user prior to rendering the page on the client. To do this, we'll need to get the user from the cookie above. If no valid session exists, we can redirect user back to the Sign In form.

In pages/profile.js, add getServerSideProps and call the getUserByCookie method from Supabase Client:

// src/pages/profile.js

export default function Profile({ user }) {
  // ...
}

export async function getServerSideProps({ req, res }) {
  const { user } = await supabase.auth.api.getUserByCookie(req);

  if (!user) {
    console.log('Please login.');
    return { props: {}, redirect: { destination: '/', permanent: false } };
  }

  return { props: { user } };
}

If there is a valid logged-in user in the session stored in the cookie, we can use it to protect our pages in Next.js. If user exists, pass it as a prop to our client-side. Otherwise, we can redirect users back to Home page by setting the redirect to /. This way we can ensure that Profile is only accessible to logged-in users.

Next, let's update the Profile page to display some of the user data. Update pages/profile.js to display the user id and the last_sign_in_at date:

// src/pages/profile.js
// ...
export default function Profile({ user }) {
  return (
    <Layout>
      <h3 className="py-8 text-4xl font-black">{user.id}</h3>
      <p className="my-4 text-lg">
        Last Signed In:
        <code className="highlight">
          {new Date(user.last_sign_in_at).toLocaleString()}
        </code>
      </p>
      <div className="inline-flex flex-col">
        <Link href="/">
          <a className="button mt-8">Go Home</a>
        </Link>
      </div>
    </Layout>
  );
}

Theming

While the default styling of Supabase UI is a good start, more than likely you will want it to match the rest of your app's look and feel. Unfortunately, as of the writing of this article (@supabase/ui version 0.36.0), theming support is not available just yet (though it is coming).

But don't fret! It's quite easy to work around this limitation in the meantime. We can set styling of UI elements in Supabase UI by targeting their CSS classes, and extend them in our src/styles/globals.css file with Tailwind, and our existing custom classes:

/* src/styles/globals.css */
/* ... */
.sbui-input {
  @apply custom-focus rounded-full focus:shadow-none !important;
}

.sbui-checkbox {
  @apply custom-focus rounded-full focus:shadow-none !important;
}

.sbui-btn-primary {
  @apply custom-focus button-inverse rounded-full !important;
}

.sbui-typography-link {
  @apply custom-focus rounded-full font-bold text-green-400 !important;
}

Note the use of !important here, as we need these styles to be the top-most specificity.

This will ensure that the input fields, buttons and text links in the Auth component us the same styling as the rest of our application. We're also making it a bit more accessible by adding more pronounced focus and hover outlines.

Now our authentication forms match as well! 🎉 Play around with it and change more as you see fit. Though not the ideal solution, it still beats setting everything up from scratch, and I'm confident that the folks over at Supabase will have this capability delivered in the near future.

You may want to keep an eye on their GitHub repo as well for future updates.

Wrap Up

And this about wraps it up. If you've followed along this far, by now you should have a fully working authentication layer in your app, with all of the required forms and flows hooked in, and a pretty decent-looking UI to go along with it.

All of the code in this article is available for reference in GitHub. Live version is available as well:

next-supabase-ui-auth.vercel.app

If you'd like to learn more about Supabase and Supabase UI, make sure to check out the official docs:

DEV Community: Mykhaylo Ryechkin 🇺🇦

All about React Server Components

Intro

Background

Server-Side Rendering (SSR) and RSC

Client Components

Next.js and RSC

Server Component Characteristics

Note on Client Components

Why should you care?

How to get started?

Further Reading

Authentication in Next.js with Supabase Auth and PKCE

Background

Overview

Page Structure

Auth Forms

Supabase Client

Client Components

Server Components

Auth Provider

Handling auth state changes

Protected Routes and Redirecting

Authenticated Pages

Unauthenticated Pages

Middleware and Refreshing Session

Setting up Code Exchange for PKCE flow

Setting up Auth Flows

Sign In

Sign Up

Reset Password

Update Password

Wrapping Up

React Server Components and Client Components with Rollup

Background

The Problem

Possible Solution

Better Solution

Disabling the warning

Starter Template

Authentication in Next.js with Supabase and Next 13

Intro

What's New?

Next 13

Supabase v2

Supabase Auth Helpers

Supabase UI (Deprecated)

Project Setup

Updating Dependencies

Updating Tailwind Config

Supabase API keys

Supabase Client

Browser Client

Server Component Client

Application Structure

Pages and Routes

Home: /

Profile: /profile

Root Layout

Auth Provider

Middleware

Migrating to Supabase v2

Session Listener

Managing Cookies

Auth Component

Updating Pages

Home

Profile

Syncing-up Server and Client states

Adding loading state

Flash of unauthenticated state

Wrap Up

Reference Materials

Rollup Library Starter

Intro

Project Setup

Folder Structure

Modules

Tooling & Dependencies

Rollup Configuration

Home: `/`

Profile: `/profile`