Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
createLiteAuth
✓ import { createLiteAuth } from 'next-lite-auth';
✗ const { createLiteAuth } = require('next-lite-auth');
Primary factory function for core auth setup. Used in a server-side file like `auth.ts`.
usersFromEnv
✓ import { usersFromEnv } from 'next-lite-auth';
✗ const { usersFromEnv } = require('next-lite-auth');
Helper function to parse user data from the LITE_AUTH_USERS environment variable, typically used with `createLiteAuth`.
LiteAuthProvider
✓ import { LiteAuthProvider } from 'next-lite-auth/client';
✗ import { LiteAuthProvider } from 'next-lite-auth';
Client component context provider. Must be imported from 'next-lite-auth/client' and used in a client component due to 'use client' directive.
useLiteAuth
✓ import { useLiteAuth } from 'next-lite-auth/client';
✗ import { useLiteAuth } from 'next-lite-auth';
React hook for accessing authentication state and actions (e.g., user data, logout) within client components. Also imported from 'next-lite-auth/client'.
handlers
✓ import { handlers } from '@/auth';
✗ import { handlers } from 'next-lite-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
✓ import { middleware } from '@/auth';
✗ import { middleware } from 'next-lite-auth';
Refers to the middleware function exported from your `auth.ts` file, not directly from the library. Used in `middleware.ts` for route protection.
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();
Errors
Common errors & fixes
Error: `createLiteAuth` must be called with a `jwtSecret`.
The `jwtSecret` property was missing or undefined when calling `createLiteAuth`.
fixEnsure `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'.
Attempting to import `LiteAuthProvider` directly from `next-lite-auth` into a Server Component or not wrapping it in a client component.
fixImport `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.
The `user` object returned by `useLiteAuth` or `getUserFromCookies` is `null` or `undefined`, indicating no user is logged in.
fixAlways 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.
The `LITE_AUTH_USERS` environment variable contains malformed JSON, preventing `usersFromEnv()` from parsing it correctly.
fixVerify 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"}]`. Audit
Dependencies
nextrequiredPeer dependency for Next.js framework integration.
reactrequiredPeer dependency for React components and hooks.