npm - @propelauth/nextjs - Versions diffs - 0.0.60 - Mend

@propelauth/nextjs 0.0.60

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 (12) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,215 @@
+# PropelAuth Next.js (v13 / AppRouter) Library
+[PropelAuth](https://www.propelauth.com?utm_source=github&utm_medium=library&utm_campaign=nextjs) is a user management and authentication service for your B2B/multi-tenant applications.
+This library provides a simple way to integrate your Next.js application with PropelAuth.
+## Installation
+```bash
+npm install @propelauth/nextjs
+```
+## Setup
+Before you start, make sure you have a PropelAuth account. You can sign up for free at [here](https://auth.propelauth.com).
+Create a file called `propelauth.ts` in the `src` directory (or your project's root if you prefer) with the following content:
+```typescript
+import {initializeAuth} from "@propelauth/nextjs/server";
+const auth = initializeAuth({
+    authUrl: process.env.NEXT_PUBLIC_AUTH_URL,
+    redirectUri: process.env.REDIRECT_URI,
+    integrationApiKey: process.env.INTEGRATION_API_KEY,
+    verifierKey: process.env.VERIFIER_KEY,
+})
+export const {
+    getRouteHandler,
+    postRouteHandler,
+    getUser,
+    getUserOrRedirect,
+    validateAccessToken,
+    validateAccessTokenOrUndefined,
+    authMiddleware,
+} = auth
+```
+This file exports all of our server-side functions that you will need to use in your application.
+You can find all the env variables for your application in the PropelAuth Dashboard under **Backend Integration**.
+### 1. Set up middleware
+In your `src/middleware.ts` file, add the following:
+```typescript
+import {authMiddleware} from "@/auth";
+export const middleware = authMiddleware
+// The middleware is responsible for keeping the user session up to date.
+// It should be called on every request that requires authentication AND /api/auth/.* routes.
+export const config = {
+    matcher: [
+        // REQUIRED: Match all request paths that start with /api/auth/
+        '/api/auth/(.*)',
+        // OPTIONAL: Don't match any static assets
+        '/((?!_next/static|_next/image|favicon.ico).*)',
+    ],
+}
+```
+### 2. Set up routes (AppRouter)
+In your `src/app/api/auth/[slug]` directory, create a file called `route.ts` with the following content:
+```typescript
+import {getRouteHandler, postRouteHandler} from "@/auth";
+export const GET = getRouteHandler
+export const POST = postRouteHandler
+```
+### 3. Set up AuthProvider (AppRouter)
+In your root layout, `src/app/layout.tsx`, add the `AuthProvider`:
+```typescript jsx
+export default async function RootLayout({children}: {children: React.ReactNode}) {
+    return (
+        <html lang="en">
+        <AuthProvider authUrl={process.env.NEXT_PUBLIC_AUTH_URL}>
+            <body className={inter.className}>{children}</body>
+        </AuthProvider>
+        </html>
+    )
+}
+```
+## Usage
+### Get the user in Server Components
+```tsx
+import {getUser} from "@/auth";
+const WelcomeMessage = () => {
+    const user = getUser()
+    if (user) {
+        return <div>Hello {user.firstName}!</div>
+    } else {
+        return <div>Please log in to be welcomed</div>
+    }
+}
+```
+```tsx
+import {getUserOrRedirect} from "@/auth";
+const WelcomeMessage = () => {
+    // If the user is not logged in, they will be redirected to the login page
+    const user = getUserOrRedirect()
+    return <div>Hello {user.firstName}!</div>
+}
+```
+### Get the user in Client Components
+```tsx
+"use client";
+import {useUser} from "@propelauth/nextjs/client";
+const WelcomeMessage = () => {
+    const {loading, user} = useUser()
+    if (loading) {
+        return <div>Loading...</div>
+    } else if (user) {
+        return <div>Hello {user.firstName}!</div>
+    } else {
+        return <div>Please log in to be welcomed</div>
+    }
+}
+```
+### Checking organization membership / RBAC
+Note that this works on both the client and server's `User` object, but the below example is on the server.
+If you are curious where the organization information comes from, check out our documentation on [organizations](https://docs.propelauth.com/overview/organizations?utm_source=github&utm_medium=library&utm_campaign=nextjs).
+The quick answer is:
+- PropelAuth provides UI for users to create organizations and invite other users to join them.
+- Your users can also create Enterprise SSO/SAML connections to their own Identity Providers (IdPs) so their organization members can log in with their existing work credentials.
+- You can create organizations and add users to them via our APIs or our Dashboard.
+```tsx
+// src/app/org/[slug]/page.tsx
+import {getUserOrRedirect} from "@/auth";
+export default async function AdminOnlyPage({ params }: { params: { slug: string } }) {
+    const user = await getUserOrRedirect()
+    const org = user.getOrgByName(params.slug);
+    const isAdmin = org?.isRole("Admin")
+    if (!isAdmin) {
+        return <div>Not found</div>
+    } else {
+        return <div>Welcome {user.firstName}, Admin of {org?.orgName}</div>
+    }
+}
+```
+### Logging out
+```tsx
+"use client"
+import {useLogoutFunction} from "@propelauth/nextjs/client";
+export default function LogoutButton() {
+    const logoutFn = useLogoutFunction()
+    return <button onClick={logoutFn}>Logout</button>
+}
+```
+### Logging in / Signing up
+If you don't want to use redirect functions, you can also use `useHostedPageUrls` which will return the URLs instead of redirecting.
+```tsx
+"use client"
+import {useRedirectFunctions} from "@propelauth/nextjs/client";
+export default function SignupAndLoginButtons() {
+    const {redirectToSignupPage, redirectToLoginPage} = useRedirectFunctions()
+    return <>
+        <button onClick={redirectToSignupPage}>Sign up</button>
+        <button onClick={redirectToLoginPage}>Log in</button>
+    </>
+}
+```
+### Redirecting to Account / Org pages
+PropelAuth also provides you with pre-built account and organization management UIs.
+You can redirect your users to these pages by using the following functions:
+```tsx
+"use client"
+import {useRedirectFunctions} from "@propelauth/nextjs/client";
+export default function AccountAndOrgButtons() {
+    const {redirectToAccountPage, redirectToOrgPage} = useRedirectFunctions()
+    return <>
+        <button onClick={redirectToAccountPage}>Account</button>
+        <button onClick={redirectToOrgPage}>Organization</button>
+    </>
+}
+```

package/dist/client/index.d.ts ADDED Viewed

@@ -0,0 +1,95 @@
+import React from 'react';
+declare class User {
+    userId: string;
+    orgIdToOrgMemberInfo?: OrgIdToOrgMemberInfo;
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    username?: string;
+    legacyUserId?: string;
+    impersonatorUserId?: string;
+    constructor(userId: string, email: string, orgIdToOrgMemberInfo?: OrgIdToOrgMemberInfo, firstName?: string, lastName?: string, username?: string, legacyUserId?: string, impersonatorUserId?: string);
+    getOrg(orgId: string): OrgMemberInfo | undefined;
+    getOrgByName(orgName: string): OrgMemberInfo | undefined;
+    getOrgs(): OrgMemberInfo[];
+    isImpersonating(): boolean;
+    static fromJSON(json: string): User;
+}
+type OrgIdToOrgMemberInfo = {
+    [orgId: string]: OrgMemberInfo;
+};
+declare class OrgMemberInfo {
+    orgId: string;
+    orgName: string;
+    orgMetadata: {
+        [key: string]: any;
+    };
+    urlSafeOrgName: string;
+    private userAssignedRole;
+    private userInheritedRolesPlusCurrentRole;
+    private userPermissions;
+    constructor(orgId: string, orgName: string, orgMetadata: {
+        [key: string]: any;
+    }, urlSafeOrgName: string, userAssignedRole: string, userInheritedRolesPlusCurrentRole: string[], userPermissions: string[]);
+    isRole(role: string): boolean;
+    isAtLeastRole(role: string): boolean;
+    hasPermission(permission: string): boolean;
+    hasAllPermissions(permissions: string[]): boolean;
+    static fromJSON(json: string): OrgMemberInfo;
+    get assignedRole(): string;
+    get inheritedRolesPlusCurrentRole(): string[];
+    get permissions(): string[];
+}
+type AuthProviderProps = {
+    authUrl: string;
+    children?: React.ReactNode;
+};
+declare const AuthProvider: (props: AuthProviderProps) => React.JSX.Element;
+type UseUserLoading = {
+    loading: true;
+    isLoggedIn: never;
+    user: never;
+};
+type UseUserLoggedIn = {
+    loading: false;
+    isLoggedIn: true;
+    user: User;
+};
+type UseUserNotLoggedIn = {
+    loading: false;
+    isLoggedIn: false;
+    user: undefined;
+};
+type UseUser = UseUserLoading | UseUserLoggedIn | UseUserNotLoggedIn;
+declare function useUser(): UseUser;
+declare function useHostedPageUrls(): {
+    getLoginPageUrl: () => string;
+    getSignupPageUrl: () => string;
+    getAccountPageUrl: () => string;
+    getOrgPageUrl: (orgId?: string | undefined) => string;
+    getCreateOrgPageUrl: () => string;
+    getSetupSAMLPageUrl: (orgId: string) => string;
+};
+declare function useLogoutFunction(): () => Promise<void>;
+declare function useRedirectFunctions(): {
+    redirectToSignupPage: () => void;
+    redirectToLoginPage: () => void;
+    redirectToAccountPage: () => void;
+    redirectToOrgPage: (orgId?: string | undefined) => void;
+    redirectToCreateOrgPage: () => void;
+};
+interface RedirectProps {
+    children?: React.ReactNode;
+}
+declare function RedirectToSignup({ children }: RedirectProps): React.JSX.Element;
+declare function RedirectToLogin({ children }: RedirectProps): React.JSX.Element;
+declare function useRefreshAuth(): () => Promise<User | undefined>;
+export { AuthProvider, AuthProviderProps, OrgIdToOrgMemberInfo, OrgMemberInfo, RedirectProps, RedirectToLogin, RedirectToSignup, UseUser, UseUserLoading, UseUserLoggedIn, UseUserNotLoggedIn, User, useHostedPageUrls, useLogoutFunction, useRedirectFunctions, useRefreshAuth, useUser };