Next.js

Overview

The Timeback SDK provides a Next.js adapter for the App Router with route handlers. If you are using coding agents, pair this page with timeback-server from the AI Skills catalog.

Installation

npm install @timeback/sdk

pnpm add @timeback/sdk

yarn add @timeback/sdk

bun add @timeback/sdk

Server Setup

Create a Timeback instance:

lib/timeback.ts

import { createTimeback } from '@timeback/sdk'

export const timeback = await createTimeback({
	env: 'staging',
	api: {
		clientId: process.env.TIMEBACK_API_CLIENT_ID!,
		clientSecret: process.env.TIMEBACK_API_CLIENT_SECRET!,
	},
	identity: {
		mode: 'sso',
		clientId: process.env.AWS_COGNITO_CLIENT_ID!,
		clientSecret: process.env.AWS_COGNITO_CLIENT_SECRET!,
		redirectUri: 'http://localhost:3000/api/timeback/identity/callback',
		onCallbackSuccess: async ({ user, state, redirect }) => {
			await setSession({ id: user.id, email: user.email })
			return redirect(state?.returnTo ?? '/')
		},
		onCallbackError: ({ error, redirect }) => {
			return redirect('/?error=sso_failed')
		},
		getUser: () => getSession(),
	},
})

Route Handler

Create a catch-all route handler:

app/api/timeback/[...timeback]/route.ts

import { toNextjsHandler } from '@timeback/sdk/nextjs'

import { timeback } from '@/lib/timeback'

export const { GET, POST, PUT, DELETE, PATCH } = toNextjsHandler(timeback)

This handles all Timeback routes:

Route	Method	Purpose
`/api/timeback/identity/signin`	GET	Initiates SSO flow
`/api/timeback/identity/callback`	GET	Handles SSO callback
`/api/timeback/identity/signout`	GET/POST	Signs out user
`/api/timeback/user/verify`	GET	Verifies user session
`/api/timeback/user/me`	GET	Fetches user profile
`/api/timeback/activity/heartbeat`	POST	Time-spent heartbeat
`/api/timeback/activity/submit`	POST	Activity completion submit

Client Provider

Wrap your app with the TimebackProvider:

app/providers.tsx

'use client'

import { TimebackProvider } from '@timeback/sdk/react'

export function Providers({ children }: { children: React.ReactNode }) {
	return <TimebackProvider>{children}</TimebackProvider>
}

app/layout.tsx

import { Providers } from './providers'

export default function RootLayout({ children }) {
	return (
		<html>
			<body>
				<Providers>{children}</Providers>
			</body>
		</html>
	)
}

Usage

For the full client-side API, see the React client adapter.

Use hooks in client components:

components/UserStatus.tsx

'use client'

import { SignInButton, useTimeback } from '@timeback/sdk/react'

export function UserStatus() {
	const timeback = useTimeback()

	if (!timeback) {
		return <SignInButton>Sign In</SignInButton>
	}

	return <div>Welcome!</div>
}

Next Steps

React Client

Client-side React integration

Identity

Authentication options

Custom Activities

Track learning sessions

Getting Started

CLI

SDK

Reference

Overview

Installation

Server Setup

Route Handler

Client Provider

Usage

Next Steps

React Client

Identity

Custom Activities

​Overview

​Installation

​Server Setup

​Route Handler

​Client Provider

​Usage

​Next Steps

React Client

Identity

Custom Activities

Overview

Installation

Server Setup

Route Handler

Client Provider

Usage

Next Steps