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.
setupEmailAuth
✓ import { setupEmailAuth } from 'naystack/auth';
✗ const { setupEmailAuth } = require('naystack/auth');
Used for defining server-side authentication API routes within Next.js App Router. This module is ESM-only.
AuthWrapper
✓ import { AuthWrapper } from 'naystack/auth/client';
✗ import { AuthWrapper } from 'naystack/auth';
A client-side React component to wrap your application, providing authentication context to hooks. Requires specific subpath import.
useToken
✓ import { useToken } from 'naystack/auth/client';
✗ import { useToken } from 'naystack/auth';
A client-side React hook to access the current JWT access token. Must be used within an `AuthWrapper`.
useSignUp
✓ import { useSignUp } from 'naystack/auth/client';
A client-side React hook to trigger the user sign-up process. Must be used within an `AuthWrapper`.
ApolloWrapper
✓ import { ApolloWrapper } from 'naystack/graphql/client';
A client-side React component to wrap your application for GraphQL client setup. Requires specific subpath import.
This quickstart demonstrates the core Naystack setup for authentication, combining server-side route handlers with client-side context providers and hooks. It simulates a basic Drizzle ORM integration for the server logic and shows how to wrap a Next.js application with `AuthWrapper` and `ApolloWrapper`, then conditionally render UI based on authentication state using `useToken()`.
import { setupEmailAuth } from 'naystack/auth';
import { AuthWrapper, useToken } from 'naystack/auth/client';
import { ApolloWrapper } from 'naystack/graphql/client';
import React from 'react';
// --- Simulate a Drizzle ORM setup for the server-side ---
// In a real app, this would be your database connection and schema
const db = {
select: () => ({ from: () => ({ where: () => ([{ id: 'user-id-123', password: 'hashed-password' }]) }) }),
insert: () => ({ values: () => ({ returning: () => ([{ id: 'new-user-id', password: 'new-hashed-password' }]) }) })
};
const UserTable = { id: 'id', email: 'email', password: 'password' };
const eq = (a: any, b: any) => ({}); // Dummy eq function
// --- Server-side (app/api/(auth)/email/route.ts) ---
// Ensure process.env.SIGNING_KEY and process.env.REFRESH_KEY are set
export const { GET, POST, PUT, DELETE } = setupEmailAuth({
getUser: async ({ email }) => {
// Replace with your actual database query
const [user] = await db.select({ id: UserTable.id, password: UserTable.password }).from(UserTable).where(eq(UserTable.email, email));
return user;
},
createUser: async (data) => {
// Replace with your actual database insertion
const [user] = await db.insert(UserTable).values(data).returning({ id: UserTable.id, password: UserTable.password });
return user;
},
onSignUp: async (userId, body) => {
console.log(`User ${userId} signed up.`);
}
});
// --- Client-side (app/layout.tsx) ---
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<AuthWrapper>
<ApolloWrapper>
{children}
</ApolloWrapper>
</AuthWrapper>
</body>
</html>
);
}
// --- Client-side (app/page.tsx or any client component) ---
'use client';
function DashboardButton() {
const token = useToken();
return (
<div>
{token ? (
<button>Go to Dashboard (Logged In)</button>
) : (
<button>Sign Up / Login (Logged Out)</button>
)}
<p>Current Token: {token ? 'Present' : 'Not Present'}</p>
</div>
);
}
// To make the client component render within the quickstart context
export { DashboardButton };
Errors
Common errors & fixes
Error: SIGNING_KEY and REFRESH_KEY must be set in environment variables.
The required environment variables for JWT signing and refreshing are missing or undefined.
fixDefine `SIGNING_KEY` and `REFRESH_KEY` in your `.env.local` file for local development, or in your deployment environment variables for production. Example: `SIGNING_KEY="super-secret-signing-key"`.
Error: You must wrap your application with AuthWrapper to use auth hooks.
A client-side authentication hook (e.g., `useToken`, `useSignUp`) was called outside the React context provided by `AuthWrapper`.
fixEnsure that the `AuthWrapper` component is placed high enough in your React component tree, typically in `app/layout.tsx`, to encompass all components that utilize Naystack's authentication hooks.
Module not found: Can't resolve 'naystack/auth' in '...' OR Module not found: Can't resolve 'naystack/auth/client'
The `naystack` package is not installed, or the import path for a specific module is incorrect (e.g., missing `/client` subpath for client-side components).
fixFirst, ensure `naystack` is installed (`pnpm add naystack`). Then, verify the import paths. Client-side modules typically require `/client` or `/graphql/client` subpaths, e.g., `import { AuthWrapper } from 'naystack/auth/client';`. TypeError: Cannot read properties of undefined (reading 'select') at setupEmailAuth
The `db` object or `UserTable` schema passed to `setupEmailAuth` is not correctly configured or is undefined, likely due to a database setup issue.
fixVerify that your `db` connection and `UserTable` (or equivalent) schema are correctly initialized and imported into your `route.ts` file, and that the `getUser` and `createUser` functions access them properly.
Audit
Dependencies
nextrequiredRequired peer dependency for Next.js application development.
reactrequiredRequired peer dependency for client-side React components and hooks.
react-domrequiredRequired peer dependency for rendering React components.