Package Exports

@hellocoop/better-auth
@hellocoop/better-auth/client

Readme

@hellocoop/better-auth

A Better Auth plugin for seamless integration with Hellō - the fastest way to add identity to your application.

Installation

npm install @hellocoop/better-auth

Setup

1. Get your Hellō Client ID

Option 1: Quick CLI Setup

npx @hellocoop/quickstart

This will open your browser, log you into Hellō, prompt you for your app name, and output your client_id. Set clientId to this value in the third step.

Option 2: Web Console Setup

Visit console.hello.coop, log into Hellō and create your application and obtain your Client ID which is the clientId in the third step.

2. Redirect URI

The http://localhost* redirect URI is enabled by default, allowing you to immediately start development on your machine.

When you are ready to deploy to staging or production environments, you can configure both development and production redirect URIs at console.hello.coop.

3. Add the plugin to your auth config

To use the Hellō Better Auth plugin, add it to your auth config.

// auth.ts
import { betterAuth } from 'better-auth'
import { hellocoop } from '@hellocoop/better-auth'

export const auth = betterAuth({
    plugins: [
        hellocoop({
            config: {
                // Your Hellō Client ID from previous step
                clientId: 'app_0123456789abcdefghijklmn_xyz', // REQUIRED

                // Default values (can be overridden in signInWithHello calls)
                scopes: ['openid', 'profile'], // OPTIONAL = defaults to openid profile
                callbackURL: '/dashboard', // OPTIONAL - default callback URL
                errorCallbackURL: '/auth-error', // OPTIONAL - default error callback URL
                providerHint: 'email-- github', // OPTIONAL - default provider hint
                // ... See Configuration Options for other settings
            },
        }),
    ],
})

4. Add the client plugin

Include the Hellō Better Auth client plugin in your authentication client setup:

// auth-client.ts
import { createAuthClient } from 'better-auth/client'
import { hellocoopClient } from '@hellocoop/better-auth'

export const authClient = createAuthClient({
    plugins: [hellocoopClient()],
})

Provider Hints

Users can choose from over 17 ways to login at Hellō. The default choices are the popular options on a platform. You can control the default providers Hellō offers your users with the providerHint parameter. For example if you target developers and don't want email to be an option, you can use set providerHint=email-- github gitlab.

See the [documentation] (https://www.hello.dev/docs/apis/wallet/#provider_hint) for details.

To sign in the user, use the Hellō signInWithHello() function:

authClient.signInWithHello({
    // ... See Configuration Options section
})

To sign out the user, use the standard Better Auth signOut() function:

authClient.signOut({
    // Better Auth options:
    fetchOptions: {
        onSuccess: () => {
            window.location.href = "/login" // redirect to login page
        },
    }
}

Hellō Button

Similar to other login providers, Hellō has a standard button layout to provide users a common experience.

Hellō CSS

Include the Hellō button style in the <head> of your HTML document:

<head>
    <!-- ... -->
    <link rel="stylesheet" href="https://cdn.hello.coop/css/hello-btn.css" />
    <head></head>
</head>

Button Styling

You can style the button to fit your application

// Apply custom CSS classes
<ContinueButton className="hello-btn-white-on-light hello-btn-hover-flare" />

You can explore all the different styles in the Button Explorer.

Examples

Next.js

// layout.tsx
// ...
<head>
    // ...
    <link rel="stylesheet" href="https://cdn.hello.coop/css/hello-btn.css" />
</head>

// login/page.tsx
import { authClient } from './auth-client'
import { ContinueButton } from '@hellocoop/better-auth'

function LoginPage() {
    return (
        {/* ... Content ... */}
        <ContinueButton
            className="hello-btn-hover-flare"
            onClick={() => {
                authClient.signInWithHello()
            }}
        />
    )
}

// dashboard/page.tsx
import { authClient } from './auth-client'

function DashboardPage() {
    return (
        {/* ... Content ... */}
        <button onPress={() => {
            authClient.signOut({
                fetchOptions: {
                    onSuccess: () => {
                        window.location.href = "/login" // redirect to login page
                    },
                },
            });
        }}>
            Sign out
        </button>
    )
}

Astro

// src/layouts/Layout.astro
// ...
;<head>
    // ...
    <link rel="stylesheet" href="https://cdn.hello.coop/css/hello-btn.css" />
</head>

// src/pages/login.astro
import { authClient } from '../lib/auth-client'
import { ContinueButton } from '@hellocoop/better-auth'

{
    /* ... Content ... */
}
;<ContinueButton
    className="hello-btn-hover-flare"
    onClick={() => {
        authClient.signInWithHello()
    }}
/>

// src/pages/dashboard.astro
import { authClient } from '../lib/auth-client'

{
    /* ... Content ... */
}
;<button
    onClick={() => {
        authClient.signOut({
            fetchOptions: {
                onSuccess: () => {
                    window.location.href = '/login' // redirect to login page
                },
            },
        })
    }}
>
    Sign out
</button>

Configuration Options

You can explore the many scopes and authorization request parameters at:
Hellō Playground.

Parameter	Description	Default
`scope?`	The user claims you are requesting. See Hellō Scopes	`openid profile`
`callbackURL?`	URL to redirect after successful sign-in	`/`
`errorCallbackURL?`	URL to redirect if an error occurs	`/error`
`loginHint?`	A hint for which user account to use. Provides better B2B SSO experience See login_hint docs	-
`prompt?`	- `login` forces login at preferred provider - `consent` prompts user to review what is released	-
`providerHint?`	- Overrides default providers shown to user. See preferred providers.	platform dependent
`domainHint?`	The domain or type of account: `domain.example` `managed` or `personal`	-

Error Handling

Errors handling is done by the Better Auth Error Handling unless you provide a errorCallback URL.

Resources

Support

Issues: GitHub Issues
Community: Hellō Slack