Lightweight JWT Auth for Next.js

Common errors

• Error: `createLiteAuth` must be called with a `jwtSecret`.

  cause The `jwtSecret` property was missing or undefined when calling `createLiteAuth`.
  fix Ensure `process.env.LITE_AUTH_SECRET` is set in your `.env.local` file and accessible in the environment where `createLiteAuth` is called. For development, a fallback might be acceptable, but avoid in production.

• Error: `LiteAuthProvider` is a client component and cannot be rendered directly in a Server Component without 'use client'.

  cause Attempting to import `LiteAuthProvider` directly from `next-lite-auth` into a Server Component or not wrapping it in a client component.
  fix Import `LiteAuthProvider` from `next-lite-auth/client` and ensure it is used within a component marked with `'use client'`, as shown in the quickstart example of `components/auth-provider.tsx`.

• TypeError: Cannot read properties of undefined (reading 'email') when accessing user data.

  cause The `user` object returned by `useLiteAuth` or `getUserFromCookies` is `null` or `undefined`, indicating no user is logged in.
  fix Always check if `user` is truthy before attempting to access its properties (e.g., `if (user) { console.log(user.email); }`). Handle the case where no user is logged in gracefully.

• Error: Invalid JSON in LITE_AUTH_USERS environment variable.

  cause The `LITE_AUTH_USERS` environment variable contains malformed JSON, preventing `usersFromEnv()` from parsing it correctly.
  fix Verify that the `LITE_AUTH_USERS` environment variable is a valid JSON string representing an array of user objects, for example: `[{"email":"test@example.com","password":"pass"}]`.

Warnings

• gotcha next-lite-auth is explicitly stated as 'Not for production'. It is designed for demos, OSS projects, internal tools, and quick Vercel deployments. It may lack the robust security, scalability, and feature set required for public-facing production applications.
  Fix: For production applications, consider more established authentication solutions with database integration, multi-factor authentication, and comprehensive security audits.
• breaking The `LiteAuthProvider` component and `useLiteAuth` hook must be imported from `next-lite-auth/client`. Importing directly from `next-lite-auth` will cause errors in client components due to missing 'use client' directive.
  Fix: Ensure client-side imports correctly reference `next-lite-auth/client`: `import { LiteAuthProvider } from 'next-lite-auth/client';`
• gotcha User data is stored directly in environment variables (LITE_AUTH_USERS) as a JSON string. This approach is not suitable for large numbers of users or dynamic user management and could pose security risks if `.env.local` files are not properly secured.
  Fix: For applications with many users or needing dynamic user management, switch to a solution that integrates with a database. Ensure `.env.local` files containing `LITE_AUTH_USERS` are never committed to version control and are only accessible by authorized personnel.
• gotcha The `jwtSecret` is a critical security component. Using a hardcoded or easily guessable secret, or allowing a fallback like `fallback-secret-for-dev` in a non-development environment, significantly compromises the security of the JWTs.
  Fix: Always use a strong, randomly generated secret for `process.env.LITE_AUTH_SECRET` and ensure it is managed securely (e.g., via environment variables in deployment platforms) without exposing it in code.

Install

• npm install next-lite-auth npm
• yarn add next-lite-auth yarn
• pnpm add next-lite-auth pnpm

Imports

• createLiteAuth
  wrong:

  const { createLiteAuth } = require('next-lite-auth');

  correct:

  import { createLiteAuth } from 'next-lite-auth';

  Primary factory function for core auth setup. Used in a server-side file like `auth.ts`.
• usersFromEnv
  wrong:

  const { usersFromEnv } = require('next-lite-auth');

  correct:

  import { usersFromEnv } from 'next-lite-auth';

  Helper function to parse user data from the LITE_AUTH_USERS environment variable, typically used with `createLiteAuth`.
• LiteAuthProvider
  wrong:

  import { LiteAuthProvider } from 'next-lite-auth';

  correct:

  import { LiteAuthProvider } from 'next-lite-auth/client';

  Client component context provider. Must be imported from 'next-lite-auth/client' and used in a client component due to 'use client' directive.
• useLiteAuth
  wrong:

  import { useLiteAuth } from 'next-lite-auth';

  correct:

  import { useLiteAuth } from 'next-lite-auth/client';

  React hook for accessing authentication state and actions (e.g., user data, logout) within client components. Also imported from 'next-lite-auth/client'.
• handlers
  wrong:

  import { handlers } from 'next-lite-auth';

  correct:

  import { handlers } from '@/auth';

  Refers to the handlers object (GET, POST) exported from your `auth.ts` file, not directly from the library. Handles API routes for authentication.
• middleware
  wrong:

  import { middleware } from 'next-lite-auth';

  correct:

  import { middleware } from '@/auth';

  Refers to the middleware function exported from your `auth.ts` file, not directly from the library. Used in `middleware.ts` for route protection.

Quickstart

This quickstart demonstrates the core 3-step setup: initializing auth utilities with environment variables, exposing API handlers, wrapping the application with the client-side provider, and an example of server-side user retrieval.

import { createLiteAuth, usersFromEnv } from "next-lite-auth";
import { LiteAuthProvider } from "next-lite-auth/client";
import { cookies } from 'next/headers';

// --- 1. Create auth.ts at your project root ---
// auth.ts (server-side)
export const { handlers, middleware, getUserFromCookies } = createLiteAuth({
  users: usersFromEnv(),
  jwtSecret: process.env.LITE_AUTH_SECRET ?? 'fallback-secret-for-dev',
  enabled: process.env.LITE_AUTH_ENABLED !== "false",
});

// .env.local example
// LITE_AUTH_SECRET=your-random-secret-here
// LITE_AUTH_ENABLED=true
// LITE_AUTH_USERS=[{"email":"admin@example.com","password":"secret","role":"admin","name":"Admin"}]

// --- 2. Add one route file ---
// app/api/auth/[...liteauth]/route.ts (API Route)
// import { handlers } from "@/auth"; // Assuming '@/auth' resolves to the auth.ts file
// export const { GET, POST } = handlers;

// --- 3. Wrap root layout ---
// components/auth-provider-wrapper.tsx (Client Component)
"use client";
export function AuthProvider({ children }: { children: React.ReactNode }) {
  return (
    <LiteAuthProvider protect={["/dashboard", "/settings"]} appName="My Next App">
      {children}
    </LiteAuthProvider>
  );
}

// app/layout.tsx (Server Component)
// import { AuthProvider } from "@/components/auth-provider-wrapper";
// export default function RootLayout({ children }: { children: React.ReactNode }) {
//   return (
//     <html>
//       <body>
//         <AuthProvider>{children}</AuthProvider>
//       </body>
//     </html>
//   );
// }

// Example of server-side usage outside middleware/API routes
async function getServerSideUser() {
  const user = await getUserFromCookies(cookies());
  console.log('Server-side user:', user?.email);
}

// Call the function (e.g., in a Server Component or route handler)
getServerSideUser();