Next.js Usersau Starter Kit

A modern Next.js starter kit with Usersau OAuth integration, built with TypeScript and Tailwind CSS.

Features

🔐 Usersau OAuth Authentication - Complete OAuth integration with Usersau
⚡ Next.js 15 - Latest Next.js with App Router
🎨 Modern UI - Built with Tailwind CSS
📱 Responsive Design - Mobile-first responsive design
🔒 NextAuth.js - Secure authentication handling
🛡️ Middleware Protection - Server-side route protection with middleware
🚀 Vercel Ready - Optimized for Vercel deployment
📄 TypeScript - Full TypeScript support
🚀 Fast Development - Hot reload and fast refresh

Requirements

Node.js 18+
npm or yarn
A Usersau OAuth application

Installation

Clone the repository

git clone https://github.com/Users-au/nextjs-starter-kit.git
cd nextjs-starter-kit

Install dependencies
```
npm install
# or
yarn install
```
Environment setup
```
cp .env.example .env.local
```

Configure environment variables

Edit .env.local with your Usersau OAuth credentials:

NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your-secret-key-here

USERSAU_CLIENT_ID=your_client_id_here
USERSAU_CLIENT_SECRET=your_client_secret_here
USERSAU_HOST=https://your-subdomain.users.au

NEXT_PUBLIC_APP_NAME="Next.js Usersau Starter Kit"

Start the development server
```
npm run dev
# or
yarn dev
```
Open your browser

Visit http://localhost:3000 to see your application.

Usersau OAuth Setup

1. Register Your Application

Go to Usersau Developer Console
Go to / Create a new Project and go to Integration > OAuth Management
Create a new OAuth application
Set the redirect URI as: http://localhost:3000/api/auth/callback/usersau
Copy the Client ID and Client Secret

2. Configure Environment Variables

Update your .env.local file with the credentials from step 1.

Usage

Available Routes

/ - Home page (redirects to login or dashboard)
/auth/login - Login page with Usersau OAuth
/dashboard - Protected dashboard page
/api/auth/* - NextAuth.js API routes

Authentication Flow

Users visit the home page and are redirected to login
They click "Continue" to authenticate with Usersau
After successful authentication, they are redirected to the dashboard
User data is automatically managed by NextAuth.js

Session Management

The application uses NextAuth.js for session management:

Sessions are stored as JWTs
User data includes Usersau ID, name, email, and avatar
Access and refresh tokens are stored in the session

Customization

Styling

The application uses Tailwind CSS. You can customize the design by:

Editing the Tailwind configuration in tailwind.config.ts
Modifying component styles in the page files
Adding custom CSS in src/app/globals.css

Adding New Pages

Create new pages in the src/app directory following Next.js App Router conventions:

// src/app/new-page/page.tsx
export default function NewPage() {
  return <div>New Page Content</div>
}

Protected Routes

Routes are protected using Next.js middleware for better performance and security. The middleware automatically:

Redirects unauthenticated users to the login page
Redirects authenticated users away from auth pages
Handles session validation at the server level
Provides automatic callback URL handling

Adding New Protected Routes:

Add the route pattern to the protectedRoutes array in src/middleware.ts:

const protectedRoutes = ['/dashboard', '/profile', '/settings']

Create your page component normally - no authentication checks needed:

// src/app/profile/page.tsx
'use client'

import { useSession } from 'next-auth/react'

export default function ProfilePage() {
  const { data: session } = useSession()
  
  // No need for authentication checks - middleware handles it
  return <div>Welcome {session?.user?.name}!</div>
}

Alternative: Using ProtectedRoute Component

For additional client-side protection, you can use the ProtectedRoute component:

import ProtectedRoute from '@/components/ProtectedRoute'

export default function MyProtectedPage() {
  return (
    <ProtectedRoute>
      <div>This content is protected</div>
    </ProtectedRoute>
  )
}

File Structure

nextjs-starter-kit/
├── src/
│   ├── app/
│   │   ├── api/
│   │   │   └── auth/
│   │   │       └── [...nextauth]/
│   │   │           └── route.ts          # NextAuth.js API routes
│   │   ├── auth/
│   │   │   └── login/
│   │   │       └── page.tsx              # Login page
│   │   ├── dashboard/
│   │   │   └── page.tsx                  # Dashboard page
│   │   ├── globals.css                   # Global styles
│   │   ├── layout.tsx                    # Root layout
│   │   ├── page.tsx                      # Home page
│   │   └── providers.tsx                 # Session provider
│   ├── components/
│   │   └── ProtectedRoute.tsx            # Protected route wrapper
│   ├── lib/
│   │   └── auth.ts                       # NextAuth.js configuration
│   └── middleware.ts                     # Authentication middleware
├── vercel.json                           # Vercel configuration
├── VERCEL_DEPLOYMENT.md                  # Deployment guide
├── env.example                           # Environment variables example
├── package.json                          # Dependencies and scripts
├── tailwind.config.ts                    # Tailwind CSS configuration
└── tsconfig.json                         # TypeScript configuration

Technology Stack

Frontend: Next.js 15, React 18, TypeScript
Styling: Tailwind CSS
Authentication: NextAuth.js, Usersau OAuth 2.0
Development: ESLint, PostCSS

Scripts

npm run dev - Start development server
npm run build - Build for production
npm run start - Start production server
npm run lint - Run ESLint

Deployment

Vercel (Recommended)

This project is optimized for Vercel deployment. See VERCEL_DEPLOYMENT.md for detailed instructions.

Quick Deploy:

Fork this repository
Push your code to GitHub
Connect your repository to Vercel
Set environment variables (see VERCEL_DEPLOYMENT.md)
Update OAuth redirect URI in Usersau console
Deploy!

Other Platforms

The application can be deployed to any platform that supports Node.js:

Netlify
Railway
Heroku
DigitalOcean App Platform

Make sure to:

Set all environment variables
Update NEXTAUTH_URL to your production domain
Update OAuth redirect URI in Usersau console

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is open-sourced software licensed under the MIT license.

Support

For support, please contact opensource@users.au or create an issue in the repository.

sicaboy/nextjs-starter-kit