Next.js Quickstart

Follow the directions below to add Hellō (opens in a new tab) to your Next.js (opens in a new tab) application in a couple of minutes.

You will get the user's name, verified email, and profile picture.
Users can use their preferred login provider including Apple, Facebook, Google, GitHub, GitLab, and Microsoft.
Hellō has done all the work to get a verified email and profile picture.

If you want to explore a sample app, check out our Hellō Next.js Sample (opens in a new tab).

Add Hellō to Your Server

Don't have a project? Start with the Next.js basic blog app (opens in a new tab).

We use JavaScript in this Quickstart as it works everywhere. Don't worry, TypeScript is supported.

Install the Package

In your project directory:

npm i @hellocoop/nextjs

Run Quickstart

npx @hellocoop/quickstart@latest --nextjs

Quickstart will prompt you to:

download the @hellocoop/quickstart package
log in to Quickstart with Hellō
create an application, or select an existing one

Quickstart will then:

create a hello.config.js file containing your app's client_id
mount the Hellō endpoint by creating the ./pages/api/hellocoop.js file
generate a random HELLO_COOKIE_SECRET and add it to .env.local

If you created a new application, no more configuration is needed for local development. You can add a light and dark themed logo, and URLs for terms of service and your privacy policy when you are ready at the Hellō Developer Console (opens in a new tab)

Your server should now be fully configured to work with Hellõ locally.

Test Your Server

Start your application locally:

npm run dev

Assuming the server started on port 3000:

Check your logged in status in a new tab with:
http://localhost:3000/api/hellocoop?op=auth (opens in a new tab)

You should get {"isLoggedIn": false} in your browser window.

Log in to Hellō with in a new tab with:
http://localhost:3000/api/hellocoop?op=login (opens in a new tab)
See your logged in status and profile by reloading /api/hellocoop?op=auth

You should see something similar to this:

{
  "isLoggedIn": true,
  "sub": "66752aed-9cc2-4d17-875f-379b1a578f9a",
  "iat": 1699234659,
  "name": "Dick Hardt",
  "picture": "https://pictures.hello.coop/r/7a160eed-46bf-48e2-a909-161745535895.png",
  "email": "dick.hardt@hello.coop"
}

Log out in a new tab with:
http://localhost:3000/api/hellocoop?op=logout&target_uri=%2Fapi%2Fhellocoop%3Fauth%3Dtrue (opens in a new tab)

After being logged out, you will be redirected back to /api/hellocoop?op=auth to confirm you are logged out.

You have configured your server to use Hellō!

Add Hellō to Your Client

Add Hellō Test Page

Copy the following code and save it to hello-test.jsx in your pages folder:

./pages/hello-test.jsx

import Head from 'next/head'
import Link from 'next/link'
import { 
    LoggedOut, 
    LoggedIn, 
    ContinueButton, 
    useAuth, 
    getLogOutRoute 
} from '@hellocoop/nextjs/react'
 
export default function HelloTest() {
  const status = useAuth(); 
  const { auth: {name, picture, email} } = status;
 
  return (
    <>
      <Head>
        <title>Hellō Test Page</title>
        <link rel="stylesheet" href="https://cdn.hello.coop/css/hello-btn.css"/>      
      </Head>
      <main>
        <div className="profile">
          <LoggedOut>
              <ContinueButton targetURI="/hello-test"/>
          </LoggedOut>
          <LoggedIn>
              <div className="user-details">
                <img src={picture} alt={name} />
                <h3>{name}</h3>
                <p>{email}</p>
              </div>
              <div className="logout-link">
                <Link href={getLogOutRoute({target_uri:'/hello-test'})}>
                    log out
                </Link>
              </div>
          </LoggedIn>        
        </div> 
        <hr className="separator" />
        <pre>
            {JSON.stringify(status, null, 4)}
        </pre>
      </main>
      <style global jsx>{`
        @media (prefers-color-scheme: light) {
            body {
                color: #303030;
                background: white;
            }
        }
        @media (prefers-color-scheme: dark) {
            body {
                color: #d4d4d4;
                background: #151515;
                color-scheme: dark;
            }
        }
      `}</style>
      <style jsx>{`
        main {
            min-height: 100vh;
            display: flex;
            flex-direction: column;
            justify-content: center;
            align-items: center;
            font-family: sans-serif;
        }
        .profile, .logout-link {
            margin: 10px 0;
            text-align: center; /* Centering content */
        }
        .user-details {
            margin-bottom: 20px;
        }
        .user-details img {
            max-width: 100px;
            border-radius: 50%;
            margin-bottom: 10px;
        }
        .user-details h3, .user-details p {
            margin: 5px 0;
        }
        .separator {
            width: 80%;
            border: 1px solid #ccc;
            margin: 10px 0;
        }
        pre {
            alignSelf: 'center',
            width: '80%' // Adjust as needed
        }
      `}</style>
    </>
  )
}

Test Your Client

Load the test page:

http://localhost:3000/hello-test (opens in a new tab)

Clink on the [ ō Continue with Hellō ] button

This will log you in and display your profile information as JSON.

Click on the log out link to log out

You now have added Hellō to your Client!

Add a Callback Stub

We will now add a stub function that you can modify later to integrate with your user database.

Create Callback Stub

Copy the following code and save it to hello-callback.js in your src folder (create the src folder if needed):

./src/hello-callback.js

// hello-callback.js
module.exports = async ({ 
    payload,    // parsed ID Token payload
    token,      // ID Token in compact, unparsed format
    req,        // NextApiRequest
    res         // NextApiResponse
}) => {
 
    console.log('Callback received:',JSON.stringify(payload,null,4))
    // TODO
    // lookup user from your DB wth payload.sub user identifier
    // create a user in DB if not found if open registration
    return({
        // accessDenied = true, // will set auth.isLoggedIn = false
        // isProcessed = true,  // response has been sent by callback()
        // updatedAuth = {},    // auth object stored in cookie
    })
}

Configure Callback

Add the highlighted lines to your hello.config.js file:

import loggedIn from './src/hello-callback'
 
const config = {
    client_id: 'YOUR_CLIENT_ID',
    callbacks: {
        loggedIn
    }
}
export default config

Test the Callback

Restart your server for it to load the updated configuration
Load the test page and click on the [ ō Continue with Hellō ] button

http://localhost:3000/hello-test (opens in a new tab)

You should see the contents of the ID Token payload logged to your terminal. See OpenID Connect | ID Token for details.

You now have a stub you can extend to integrate your user database!

Next Steps

Explore the Hellō Next.js Sample (opens in a new tab)
Change the claims received or providers recommended by updating your hello.config.js file.
Review the SDK Reference | Next.js documentation.
Replace the ./hello-callback.js file with your own code that integrates with your user DB.

Fastify WordPress