@hellocoop/better-auth
v1.0.14
Published
Better Auth plugin for Hellō - https://hello.dev
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-authSetup
1. Get your Hellō Client ID
Option 1: Quick CLI Setup
npx @hellocoop/quickstartThis 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.
Sign In and Sign Out
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.examplemanagedor personal | - |
Error Handling
Errors handling is done by the Better Auth Error Handling unless you provide a errorCallback URL.
Resources
- Hellō Better Auth Demo
- Hellō Developer Console
- Provider Hints
- Hellō Button Customization Guide
- Hellō Scopes Reference
- Better Auth Documentation
Support
- Issues: GitHub Issues
- Community: Hellō Slack