npm - @propelauth/nextjs - Versions diffs - 0.3.10-withjs.0 → 0.3.11 - Mend

@propelauth/nextjs 0.3.10-withjs.0 → 0.3.11

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

package/README.md +117 -246
package/dist/client/index.js +1 -1
package/dist/client/index.js.map +1 -1
package/dist/client/index.mjs +1 -1
package/dist/client/index.mjs.map +1 -1
package/dist/server/app-router/index.d.ts +7 -8
package/dist/server/app-router/index.js +3 -3
package/dist/server/app-router/index.js.map +1 -1
package/dist/server/app-router/index.mjs +3 -3
package/dist/server/app-router/index.mjs.map +1 -1
package/dist/server/index.d.ts +2 -1
package/dist/server/index.js +3 -3
package/dist/server/index.js.map +1 -1
package/dist/server/index.mjs +3 -3
package/dist/server/index.mjs.map +1 -1
package/package.json +2 -2

package/README.md CHANGED Viewed

@@ -1,10 +1,15 @@
+<p align="center">
+  <a href="https://www.propelauth.com?ref=github" target="_blank" align="center">
+    <img src="https://www.propelauth.com/imgs/lockup.svg" width="200">
+  </a>
+</p>
 # PropelAuth Next.js (v13+) 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 (either AppRouter or Pages) with PropelAuth.
-Next.js SSR/AppRouter support is currently in beta.
+This library provides a simple way to integrate your Next.js application (either App Router or Pages) with PropelAuth.
 ## Installation
@@ -12,297 +17,163 @@ Next.js SSR/AppRouter support is currently in beta.
 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).
-You'll need to set the following .env variables in your Next.js application:
-- NEXT_PUBLIC_AUTH_URL
-- PROPELAUTH_API_KEY
-- PROPELAUTH_VERIFIER_KEY
-- PROPELAUTH_REDIRECT_URI
-You can find the NEXT_PUBLIC_AUTH_URL, PROPELAUTH_API_KEY, and PROPELAUTH_VERIFIER_KEY variables for your application in the PropelAuth Dashboard under Backend Integration.
-When you copy the PROPELAUTH_VERIFIER_KEY from the PropelAuth dashboard, it will automatically paste into your .env file with line breaks. However, due to the way some systems interpret multiline environment variables, you will need to edit the verifier key value to include ‘\n’ instead of newline characters. For example:
-```
-PROPELAUTH_VERIFIER_KEY=-----BEGIN PUBLIC KEY-----\nMIIBIjANBgk...
-```
+## Automatic Installation
-If authentication URL needs to be set at runtime, use `PROPELAUTH_AUTH_URL`. Otherwise, it falls back to `NEXT_PUBLIC_AUTH_URL`, which is set at build time.
+If you would prefer a manual installation process instead of an automatic one, check out the installation guides for [App Router](https://docs.propelauth.com/reference/fullstack-apis/nextjsapp/installation-and-setup) and [Pages Router](https://docs.propelauth.com/reference/fullstack-apis/nextjspages/installation-and-setup).
-For the PROPELAUTH_REDIRECT_URI variable, you need to add /api/auth/callback to the end of one of your allowed frontend locations. So, for example, if you are developing in the test environment and using http://localhost:3000, you would use http://localhost:3000/api/auth/callback
+Begin by installing the PropelAuth CLI:
-### 1. Set up routes
-In your `src/app/api/auth/[slug]` directory, create a file called `route.ts` with the following content:
-```typescript
-import { getRouteHandlers } from '@propelauth/nextjs/server/app-router'
-import { NextRequest } from 'next/server'
-// postLoginRedirectPathFn is optional, but if you want to redirect the user to a different page after login, you can do so here.
-const routeHandlers = getRouteHandlers({
-    postLoginRedirectPathFn: (req: NextRequest) => {
-        return '/'
-    },
-})
-export const GET = routeHandlers.getRouteHandler
-export const POST = routeHandlers.postRouteHandler
+```bash
+npm i -g @propelauth/cli
 ```
-### 2. Set up AuthProvider
+## Logging into the PropelAuth CLI
-#### App Router
+Before we install PropelAuth in your Next.js project we first have to log into the CLI. If you haven't already created an account in PropelAuth, navigate to [auth.propelauth.com](https://auth.propelauth.com/en/signup) to get started.
-In your root layout, `src/app/layout.tsx`, add the `AuthProvider`:
+Once you have an account with PropelAuth, run this command to login to the CLI:
-```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>
-    )
-}
+```bash
+propelauth login
 ```
-#### Pages Router
-In your `_app.tsx` file, add the `AuthProvider`:
+To login you'll be prompted to create and copy/paste a Personal API Key into your terminal.
-```typescript jsx
-export default function MyApp({Component, pageProps}: AppProps) {
-    return (
-        <AuthProvider authUrl={process.env.NEXT_PUBLIC_AUTH_URL}>
-            <Component {...pageProps} />
-        </AuthProvider>
-    )
-}
 ```
-### 3. Set up middleware (App Router only - skip if using Pages)
-In your `src/middleware.ts` file, add the following:
-```typescript
-import { authMiddleware } from '@propelauth/nextjs/server/app-router'
-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).*)',
-    ],
-}
+┌  ⚡ PropelAuth Login
+│
+●
+│  Please visit the following URL to create a personal API key:
+│
+●  https://auth.propelauth.com/api_keys/personal
+│
+│
+◆  Enter your API key
+│  # enter your API key here
+└
 ```
-## Usage
+You can create a Personal API Key by navigating to https://auth.propelauth.com/api_keys/personal and clicking **+ New API Key**.
-### Get the user in Server Components (App Router example)
-```tsx
-import { getUser } from '@propelauth/nextjs/server/app-router'
+### Selecting a Default Project
-const WelcomeMessage = async () => {
-    const user = await getUser()
+Once your API Key is validated the CLI will prompt you to select a default project, if desired. If you select a default project, the CLI will not prompt you to select a project again until you repeat the login process or run the `set-default-project` command.
-    if (user) {
-        return <div>Hello {user.firstName}!</div>
-    } else {
-        return <div>Please log in to be welcomed</div>
-    }
-}
 ```
-```tsx
-import { getUserOrRedirect } from '@propelauth/nextjs/server/app-router'
-const WelcomeMessage = async () => {
-    // If the user is not logged in, they will be redirected to the login page
-    const user = await getUserOrRedirect()
-    return <div>Hello {user.firstName}!</div>
-}
+┌
+◇  ✓ Projects fetched successfully
+│
+◆  Select a project to use
+│  ● Always ask which project to use (You will be prompted for each command)
+│  ○ Acme Inc / New Project
+└
 ```
-### Get the user in getServerSideProps (Pages example)
+## Installing and Setting up PropelAuth in Next.js
-```tsx
-import { GetServerSideProps, InferGetServerSidePropsType } from 'next'
-import { getUserFromServerSideProps } from '@propelauth/nextjs/server/pages'
-import { User } from '@propelauth/nextjs/client'
+Once you have logged into the CLI it's time to install PropelAuth within your Next.js app! Navigate to your Next.js project directory and run the following command:
-export default function WelcomeMessage({ userJson }: InferGetServerSidePropsType<typeof getServerSideProps>) {
-    // Deserialize the user from the JSON string so you can call functions like user.getOrg()
-    const user = User.fromJSON(userJson)
-    return <div>Hello, {user.firstName}</div>
-}
+```bash
+propelauth setup
+```
+During installation you'll see the following prompts:
+```
+┌  ⚡ PropelAuth Setup
+│
+◆  Select your project framework:
+│  ○ Next.js (App Router)
+│  ● Next.js (Pages Router) (Uses pages/ directory structure)
+│
+◆  Select a project to use for this command
+│  ● Acme Inc / New Project
+│
+◆  Enter the URL your Next.js app runs on:
+│  ↳ http://localhost:3000
+│
+●  No API key found in environment file
+│
+◆  Would you like to generate a new Backend Integration API Key for this project?
+│  ● yes / ○ no
+│
+│  Enter a name for the new Backend Integration API Key:
+│  ↳ Next.js Integration
+│
+●  Updates needed for the Frontend Integration settings for your test environment
+│  - Login redirect path: / → /api/auth/callback
+│  - Logout redirect path: / → /api/auth/logout
+│  - Development URL: none → http://localhost:3000
+│
+◆  Your test environment config needs to be updated, would you like to apply these changes now?
+│  ● yes / ○ no
+│
+◆  Install @propelauth/nextjs now?
+│  ● npm install @propelauth/nextjs (detected)
+│  ○ yarn add @propelauth/nextjs
+│  ○ pnpm install @propelauth/nextjs
+│  ○ bun install @propelauth/nextjs
+│  ○ Skip installation
+│
+●  _app.tsx with AuthProvider at /src/pages/_app.tsx differs from what we expected.
+│
+◆  Overwrite _app.tsx with AuthProvider?
+│  ● Yes / ○ No
+│
+└  PropelAuth has been successfully set up in your Next.js project!
+```
+Once the CLI has successfully installed PropelAuth within your Next.js project it will also include some example components to help you get started.
+### App Router Server Component
+```jsx {{ title: "Server Component" }}
+import { getUserOrRedirect } from "@propelauth/nextjs/server/app-router";
-export const getServerSideProps: GetServerSideProps = async (context) => {
-    const user = await getUserFromServerSideProps(context)
-    if (!user) {
-        return { redirect: { destination: '/api/auth/login', permanent: false } }
-    }
-    return { props: { userJson: JSON.stringify(user) } }
+const WelcomeMessage = async () => {
+    const user = await getUserOrRedirect()
+    return <div>Welcome, {user.email}!</div>
 }
-```
-### Get the user in API Routes (Pages example)
-```ts
-import { NextApiRequest, NextApiResponse } from 'next'
-import { getUserFromApiRouteRequest } from '@propelauth/nextjs/server/pages'
-export default async function handler(req: NextApiRequest, res: NextApiResponse) {
-    const user = await getUserFromApiRouteRequest(req, res)
-    if (user) {
-        res.status(200).json({ email: user.email })
-    } else {
-        res.status(401).json({ error: 'unauthorized' })
-    }
-}
+export default WelcomeMessage;
 ```
-### Get the user in Client Components
+### App Router Client Component
-```tsx
-'use client'
+```jsx
+"use client";
-import { useUser } from '@propelauth/nextjs/client'
+import { useUser } from "@propelauth/nextjs/client";
 const WelcomeMessage = () => {
-    const { loading, user } = useUser()
+    const {loading, user} = useUser()
     if (loading) {
         return <div>Loading...</div>
     } else if (user) {
-        return <div>Hello {user.firstName}!</div>
+        return <div>Welcome, {user.email}!</div>
     } else {
         return <div>Please log in to be welcomed</div>
     }
 }
-```
-### Checking organization membership / RBAC
-Note that this works on both the client's `User` object or the client/server `UserFromToken` 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 '@propelauth/nextjs/server/app-router'
-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>
-        </>
-    )
-}
+export default WelcomeMessage;
 ```
-### 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:
+## Calling Backend APIs
-```tsx
-'use client'
+You can also use the library to call the PropelAuth APIs directly, allowing you to fetch users, create orgs, and a lot more.
+See the [API Reference](https://docs.propelauth.com/reference) for more information.
-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>
-        </>
-    )
-}
-```
-### Using APIs
-You can use our [APIs](https://docs.propelauth.com/reference/backend-apis/node) like so:
-```ts
-import { getPropelAuthApis } from '@propelauth/nextjs/server'
+```typescript
+import { getPropelAuthApis } from "@propelauth/nextjs/server";
+// Can be done in an API route or getServerSideProps
 const apis = getPropelAuthApis()
 await apis.disableUser(userId)
 ```
-### Making a call to an external API
+## Questions?
-PropelAuth also supports backend that are not Next.js. To make an [authenticated request](https://docs.propelauth.com/getting-started/making-authenticated-requests)
-to an external API, you'll need an access token. You can get an access token on the frontend from the `useUser` hook:
-```tsx
-import { useUser } from '@propelauth/nextjs/client'
-const MyComponent = () => {
-    const { loading, accessToken } = useUser()
-    // Make a request to an external API with useEffect, useQuery, etc.
-}
-```
+Feel free to reach out at support@propelauth.com
-Within the App Router, you can also call `getAccessToken` to get the access token.

package/dist/client/index.js CHANGED Viewed

@@ -300,7 +300,7 @@ function toOrgIdToOrgMemberInfo(snake_case) {
 // src/client/AuthProvider.tsx
 var import_react2 = __toESM(require("react"));
-var import_navigation = require("next/navigation.js");
+var import_navigation = require("next/navigation");
 // src/client/utils.ts
 function hasWindow() {