npm - @insforge/nextjs - Versions diffs - 0.4.0 - Mend

@insforge/nextjs 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (25) hide show

package/README.md +759 -0
package/dist/Manrope-VariableFont_wght-OKHRIJEM.ttf +0 -0
package/dist/api.d.mts +39 -0
package/dist/api.d.ts +39 -0
package/dist/api.js +267 -0
package/dist/api.js.map +1 -0
package/dist/api.mjs +240 -0
package/dist/api.mjs.map +1 -0
package/dist/index.css +468 -0
package/dist/index.css.map +1 -0
package/dist/index.d.mts +146 -0
package/dist/index.d.ts +146 -0
package/dist/index.js +1086 -0
package/dist/index.js.map +1 -0
package/dist/index.mjs +1037 -0
package/dist/index.mjs.map +1 -0
package/dist/middleware.d.mts +14 -0
package/dist/middleware.d.ts +14 -0
package/dist/middleware.js +99 -0
package/dist/middleware.js.map +1 -0
package/dist/middleware.mjs +70 -0
package/dist/middleware.mjs.map +1 -0
package/package.json +65 -0
package/src/fonts/Manrope-VariableFont_wght.ttf +0 -0
package/src/styles.css +551 -0

package/README.md ADDED Viewed

@@ -0,0 +1,759 @@
+# @insforge/nextjs
+Pre-built authentication UI components for Next.js applications using Insforge backend. This package provides a Clerk-like experience with drop-in components that connect directly to your Insforge backend, reducing token usage for AI agents.
+## Features
+- **Drop-in UI Components**: Pre-styled SignIn, SignUp, and UserButton components
+- **React Hooks**: Easy access to auth state with `useAuth()`, `useUser()`, `useSession()`
+- **Control Components**: `<SignedIn>`, `<SignedOut>`, `<Protect>` for conditional rendering
+- **Next.js Middleware**: Server-side route protection
+- **OAuth Support**: Built-in Google and GitHub authentication
+- **TypeScript**: Full type safety out of the box
+- **Customizable**: Override styles with the `appearance` prop
+## Installation
+```bash
+npm install @insforge/nextjs lucide-react
+# or
+yarn add @insforge/nextjs lucide-react
+```
+**Required peer dependencies:**
+- `lucide-react` - Icon library (used for icons in components)
+## Quick Start
+### 1. Check Your Backend OAuth Configuration
+First, query your Insforge backend to see what OAuth providers are configured:
+```bash
+# Using curl (requires admin authentication)
+curl -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
+  https://your-backend.insforge.app/api/metadata/auth
+```
+**Response example:**
+```json
+{
+  "oauths": [
+    { "provider": "github", "clientId": "...", ... },
+    { "provider": "google", "clientId": "...", ... }
+  ]
+}
+```
+**For AI Agents:** Use the Insforge MCP tool `get-backend-metadata` to automatically retrieve this configuration.
+### 2. Wrap your app with AuthProvider
+```tsx
+// app/layout.tsx
+import { AuthProvider } from '@insforge/nextjs';
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  const baseUrl = process.env.NEXT_PUBLIC_INSFORGE_BASE_URL!;
+  return (
+    <html lang="en">
+      <body>
+        <AuthProvider baseUrl={baseUrl}>
+          {children}
+        </AuthProvider>
+      </body>
+    </html>
+  );
+}
+```
+**Note:** Import the component styles:
+```tsx
+// In your layout.tsx or _app.tsx
+import '@insforge/nextjs/styles.css';
+```
+**That's it!** No Tailwind configuration needed. The package now uses standalone CSS.
+### 3. Add OAuth callback page (Required for OAuth)
+If you're using OAuth providers, you **must** create a callback page:
+```tsx
+// app/auth/callback/page.tsx
+'use client';
+import { useEffect, Suspense } from 'react';
+import { useRouter, useSearchParams } from 'next/navigation';
+function CallbackContent() {
+  const router = useRouter();
+  const searchParams = useSearchParams();
+  useEffect(() => {
+    const processOAuthCallback = () => {
+      const accessToken = searchParams.get('access_token');
+      const error = searchParams.get('error');
+      if (error) {
+        router.push('/sign-in?error=' + encodeURIComponent(error));
+        return;
+      }
+      if (accessToken) {
+        // Store token in localStorage (where SDK expects it)
+        localStorage.setItem('insforge-auth-token', accessToken);
+        // Get final destination
+        const finalDestination = sessionStorage.getItem('oauth_final_destination') || '/dashboard';
+        sessionStorage.removeItem('oauth_final_destination');
+        router.push(finalDestination);
+      } else {
+        router.push('/sign-in?error=no_token');
+      }
+    };
+    processOAuthCallback();
+  }, [searchParams, router]);
+  return (
+    <div className="flex items-center justify-center min-h-screen">
+      <div className="text-center">
+        <h2 className="text-2xl font-semibold mb-4">Completing authentication...</h2>
+        <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-blue-600 mx-auto"></div>
+      </div>
+    </div>
+  );
+}
+export default function OAuthCallbackPage() {
+  return (
+    <Suspense fallback={<div>Loading...</div>}>
+      <CallbackContent />
+    </Suspense>
+  );
+}
+```
+### 4. Add sign-in page with OAuth providers
+```tsx
+// app/sign-in/page.tsx
+import { SignIn } from '@insforge/nextjs';
+export default function SignInPage() {
+  return (
+    <SignIn
+      baseUrl={process.env.NEXT_PUBLIC_INSFORGE_BASE_URL!}
+      providers={['github', 'google']}  // Based on your backend config
+      afterSignInUrl="/dashboard"
+      title="Welcome to MyApp"
+      subtitle="Sign in to continue"
+    />
+  );
+}
+```
+**Note:** The `providers` prop should match what you've configured in your Insforge backend. OAuth buttons will only render for providers specified in this array.
+### 5. Add sign-up page
+```tsx
+// app/sign-up/page.tsx
+import { SignUp } from '@insforge/nextjs';
+export default function SignUpPage() {
+  return (
+    <SignUp
+      baseUrl={process.env.NEXT_PUBLIC_INSFORGE_BASE_URL!}
+      providers={['github', 'google']}  // Based on your backend config
+      afterSignUpUrl="/dashboard"
+    />
+  );
+}
+```
+### 6. Use conditional components
+```tsx
+// app/page.tsx
+import { SignedIn, SignedOut, UserButton } from '@insforge/nextjs';
+export default function Home() {
+  return (
+    <div>
+      <nav>
+        <SignedOut>
+          <a href="/sign-in">Sign In</a>
+        </SignedOut>
+        <SignedIn>
+          <UserButton afterSignOutUrl="/" />
+        </SignedIn>
+      </nav>
+      <SignedIn>
+        <h1>Welcome back!</h1>
+      </SignedIn>
+      <SignedOut>
+        <h1>Please sign in</h1>
+      </SignedOut>
+    </div>
+  );
+}
+```
+### 7. Protect routes with middleware
+```ts
+// middleware.ts
+import { withAuth } from '@insforge/nextjs/middleware';
+export default withAuth({
+  baseUrl: process.env.INSFORGE_BASE_URL!,
+  publicRoutes: ['/sign-in', '/sign-up', '/'],
+  signInUrl: '/sign-in',
+});
+export const config = {
+  matcher: ['/((?!_next|api|.*\\..*).*)'],
+};
+```
+## API Reference
+### Components
+#### `<AuthProvider>`
+Wraps your application and provides auth context.
+```tsx
+<AuthProvider
+  baseUrl="https://your-backend.insforge.app"
+  onAuthChange={(user) => console.log('Auth changed:', user)}
+>
+  {children}
+</AuthProvider>
+```
+**Props:**
+- `baseUrl` (required): Your Insforge backend URL
+- `onAuthChange`: Optional callback when auth state changes
+---
+#### `<SignIn>`
+Pre-built sign-in form with email/password and OAuth.
+```tsx
+<SignIn
+  baseUrl="https://your-backend.insforge.app"
+  providers={['github', 'google']}
+  afterSignInUrl="/dashboard"
+  appearance={{
+    container: { background: '#f5f5f5' },
+    button: { background: 'blue' }
+  }}
+  onSuccess={(user) => console.log('Signed in:', user)}
+  onError={(error) => console.error('Error:', error)}
+/>
+```
+**Props:**
+- `baseUrl` (required): Your Insforge backend URL
+- `providers`: Array of OAuth providers to display (e.g., `['github', 'google']`). Omit or pass empty array for email/password only
+- `afterSignInUrl`: Redirect URL after successful sign-in (default: `/`)
+- `appearance`: Custom styles for container, form, and button
+- `onSuccess`: Callback on successful sign-in
+- `onError`: Callback on error
+---
+#### `<SignUp>`
+Pre-built sign-up form with email/password and OAuth.
+```tsx
+<SignUp
+  baseUrl="https://your-backend.insforge.app"
+  providers={['github', 'google']}
+  afterSignUpUrl="/onboarding"
+  appearance={{
+    container: { background: '#f5f5f5' }
+  }}
+/>
+```
+**Props:**
+- `baseUrl` (required): Your Insforge backend URL
+- `providers`: Array of OAuth providers to display (e.g., `['github', 'google']`). Omit or pass empty array for email/password only
+- `afterSignUpUrl`: Redirect URL after successful sign-up (default: `/`)
+- `appearance`: Custom styles for container, form, and button
+- `onSuccess`: Callback on successful sign-up
+- `onError`: Callback on error
+---
+#### `<UserButton>`
+User profile dropdown with sign-out functionality.
+```tsx
+<UserButton
+  afterSignOutUrl="/"
+  showEmail={true}
+  appearance={{
+    button: { borderRadius: '50%' },
+    dropdown: { minWidth: '250px' }
+  }}
+/>
+```
+**Props:**
+- `afterSignOutUrl`: Redirect URL after sign-out (default: `/`)
+- `showEmail`: Show user email in dropdown (default: `true`)
+- `appearance`: Custom styles for button and dropdown
+---
+#### `<SignedIn>`
+Renders children only when user is authenticated.
+```tsx
+<SignedIn>
+  <Dashboard />
+</SignedIn>
+```
+---
+#### `<SignedOut>`
+Renders children only when user is NOT authenticated.
+```tsx
+<SignedOut>
+  <LandingPage />
+</SignedOut>
+```
+---
+#### `<Protect>`
+Protects content and optionally redirects unauthenticated users.
+```tsx
+<Protect
+  fallback={<Loading />}
+  redirectTo="/sign-in"
+  condition={(user) => user.role === 'admin'}
+>
+  <AdminPanel />
+</Protect>
+```
+**Props:**
+- `fallback`: Component to show while loading or if unauthorized
+- `redirectTo`: URL to redirect to if not authorized (default: `/sign-in`)
+- `condition`: Optional function for custom authorization logic (e.g., role-based access)
+---
+### Hooks
+#### `useAuth()`
+Access complete auth state and methods.
+```tsx
+import { useAuth } from '@insforge/nextjs';
+function Component() {
+  const {
+    user,
+    session,
+    isLoaded,
+    isSignedIn,
+    signIn,
+    signUp,
+    signOut,
+    updateUser
+  } = useAuth();
+  if (!isLoaded) return <div>Loading...</div>;
+  if (!isSignedIn) return <div>Please sign in</div>;
+  return <div>Hello {user.email}</div>;
+}
+```
+**Returns:**
+- `user`: Current user object or `null`
+- `session`: Current session object or `null`
+- `isLoaded`: Whether auth state has loaded
+- `isSignedIn`: Whether user is authenticated
+- `signIn(email, password)`: Sign in method
+- `signUp(email, password)`: Sign up method
+- `signOut()`: Sign out method
+- `updateUser(data)`: Update user data
+---
+#### `useUser()`
+Access current user data.
+```tsx
+import { useUser } from '@insforge/nextjs';
+function Component() {
+  const { user, isLoaded } = useUser();
+  if (!isLoaded) return <div>Loading...</div>;
+  if (!user) return <div>Not signed in</div>;
+  return <div>{user.email}</div>;
+}
+```
+---
+#### `useSession()`
+Access current session data.
+```tsx
+import { useSession } from '@insforge/nextjs';
+function Component() {
+  const { session, isLoaded, isSignedIn } = useSession();
+  return <div>Signed in: {isSignedIn ? 'Yes' : 'No'}</div>;
+}
+```
+---
+### Middleware
+#### `withAuth(config)`
+Create Next.js middleware for route protection.
+```ts
+import { withAuth } from '@insforge/nextjs/middleware';
+export default withAuth({
+  baseUrl: process.env.INSFORGE_BASE_URL!,
+  publicRoutes: ['/sign-in', '/sign-up', '/', '/about'],
+  signInUrl: '/sign-in',
+  cookieName: 'insforge_token',
+});
+```
+**Config:**
+- `baseUrl` (required): Your Insforge backend URL
+- `publicRoutes`: Array of routes that don't require auth (supports wildcards: `/blog/*`)
+- `signInUrl`: URL to redirect to when not authenticated (default: `/sign-in`)
+- `cookieName`: Cookie name for auth token (default: `insforge_token`)
+---
+#### `getAuthUser(headers)` and `getAuthToken(headers)`
+Get authenticated user ID or token in server components.
+```tsx
+import { headers } from 'next/headers';
+import { getAuthUser, getAuthToken } from '@insforge/nextjs/middleware';
+export default async function ServerComponent() {
+  const userId = getAuthUser(headers());
+  const token = getAuthToken(headers());
+  // Fetch user-specific data
+  const data = await fetchUserData(userId, token);
+  return <div>User ID: {userId}</div>;
+}
+```
+---
+## Styling
+This package uses **standalone CSS** for styling - no Tailwind CSS dependency required! All components come pre-styled and ready to use.
+### Setup
+Simply import the CSS file once in your root layout:
+```tsx
+// app/layout.tsx
+import '@insforge/nextjs/styles.css';
+```
+That's it! No configuration needed.
+### Typography
+The package includes the **Manrope variable font** for a modern, professional look. The font is automatically loaded and available as a CSS variable:
+```css
+/* Use the font in your own CSS */
+.my-component {
+  font-family: var(--font-manrope);
+}
+```
+The font family includes fallbacks to system fonts for optimal loading:
+- `--font-manrope`: 'Manrope', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif
+### Customization
+**Option 1: Text Customization** (Easiest)
+All text elements in the components can be customized via props:
+```tsx
+<SignIn
+  baseUrl="..."
+  // Customize all text
+  title="Welcome Back to MyApp"
+  subtitle="We're happy to see you again"
+  emailLabel="Your Email"
+  emailPlaceholder="you@company.com"
+  passwordLabel="Your Password"
+  forgotPasswordText="Forgot it?"
+  submitButtonText="Log In"
+  loadingButtonText="Logging in..."
+  signUpText="New user?"
+  signUpLinkText="Create an account"
+  signUpUrl="/register"
+  dividerText="or continue with"
+/>
+<SignUp
+  baseUrl="..."
+  // Customize signup text
+  title="Join MyApp Today"
+  subtitle="Create your account in seconds"
+  submitButtonText="Create Account"
+  signInText="Existing user?"
+  signInLinkText="Log in here"
+/>
+```
+**Option 2: Style Customization**
+Override inline styles for specific components:
+```tsx
+<SignIn
+  appearance={{
+    container: {
+      background: 'linear-gradient(to right, #4f46e5, #7c3aed)'
+    },
+    form: {
+      padding: '3rem',
+      borderRadius: '16px'
+    },
+    button: {
+      background: '#4f46e5',
+      color: 'white'
+    }
+  }}
+/>
+```
+**Option 3: Override CSS Classes**
+All components use semantic CSS class names prefixed with `insforge-`:
+```css
+/* In your global CSS file */
+/* Customize the primary button */
+.insforge-btn-primary {
+  background: #8b5cf6;
+  border-radius: 12px;
+}
+/* Customize form inputs */
+.insforge-input {
+  border-color: #e0e0e0;
+  border-radius: 8px;
+}
+/* Customize the auth card */
+.insforge-auth-card {
+  box-shadow: 0 20px 50px rgba(0, 0, 0, 0.15);
+}
+```
+**Available CSS Classes:**
+- `.insforge-auth-container` - Main container
+- `.insforge-auth-card` - Form card
+- `.insforge-input` - Input fields
+- `.insforge-btn-primary` - Primary buttons
+- `.insforge-oauth-btn` - OAuth buttons
+- `.insforge-user-button` - User menu button
+- `.insforge-error-banner` - Error messages
+---
+## Advanced Usage
+### Role-Based Access Control
+```tsx
+<Protect condition={(user) => user.role === 'admin'}>
+  <AdminDashboard />
+</Protect>
+```
+### Custom Auth Callbacks
+```tsx
+<AuthProvider
+  baseUrl={baseUrl}
+  onAuthChange={(user) => {
+    if (user) {
+      analytics.identify(user.id);
+    } else {
+      analytics.reset();
+    }
+  }}
+>
+  {children}
+</AuthProvider>
+```
+### Server-Side User Data
+```tsx
+// app/dashboard/page.tsx
+import { headers } from 'next/headers';
+import { getAuthUser } from '@insforge/nextjs/middleware';
+import { createClient } from '@insforge/sdk';
+export default async function Dashboard() {
+  const userId = getAuthUser(headers());
+  const insforge = createClient({
+    baseUrl: process.env.INSFORGE_BASE_URL!
+  });
+  const user = await insforge.auth.getUserById(userId);
+  return <div>Welcome {user.email}</div>;
+}
+```
+---
+## Environment Variables
+Create a `.env.local` file:
+```env
+# Public (accessible in browser)
+NEXT_PUBLIC_INSFORGE_BASE_URL=https://your-backend.insforge.app
+# Server-only (middleware)
+INSFORGE_BASE_URL=https://your-backend.insforge.app
+```
+---
+## Why @insforge/nextjs?
+### For Developers
+- **Faster Development**: Drop-in components save hours of auth implementation
+- **Best Practices**: Built-in security, session management, and error handling
+- **Flexible**: Fully customizable while providing sensible defaults
+- **Explicit Configuration**: OAuth providers passed as props - no hidden API calls or magic
+### For AI Agents
+- **Reduced Token Usage**: Pre-built components mean agents don't rebuild UI each time
+- **Consistent UX**: Standard patterns across projects
+- **Less Context**: Import and use instead of implementing from scratch
+- **Discoverable**: Query `/api/metadata/auth` via MCP to get OAuth config, then generate code with correct `providers` prop
+### AI Agent Workflow with Insforge MCP
+When building Next.js apps with authentication:
+1. **Connect to Insforge MCP** - Access the user's Insforge backend
+2. **Query metadata** - Call `get-backend-metadata` to get OAuth configuration
+3. **Generate code** - Write auth pages with explicit `providers={['github', 'google']}` based on backend config
+4. **User sees OAuth buttons** - Components render buttons for configured providers
+**Example MCP Response:**
+```json
+{
+  "auth": {
+    "oauths": [
+      { "provider": "github", "clientId": "..." },
+      { "provider": "google", "clientId": "..." }
+    ]
+  }
+}
+```
+**Agent generates:**
+```tsx
+<SignIn
+  baseUrl={process.env.NEXT_PUBLIC_INSFORGE_BASE_URL!}
+  providers={['github', 'google']}  // From metadata
+  afterSignInUrl="/dashboard"
+/>
+```
+---
+## TypeScript
+Full TypeScript support with exported types:
+```tsx
+import type {
+  InsforgeUser,
+  InsforgeSession,
+  AuthContextValue,
+  SignInProps,
+  ProtectProps
+} from '@insforge/nextjs';
+```
+---
+## Examples
+Check out the `/examples` directory for:
+- Basic Next.js App Router setup
+- Role-based access control
+- Custom styling
+- Server-side data fetching
+---
+## License
+MIT
+---
+## Support
+- Documentation: https://docs.insforge.app
+- Issues: https://github.com/insforge/nextjs/issues
+- Discord: https://discord.gg/insforge