Auth integration

Self-hosted Plasmic Auth

This guide is only for self-hosted projects that use Plasmic Auth.

Installation

Install the @plasmicapp/auth-react package.

Copy
npm install @plasmicapp/auth-react
# or yarn add @plasmicapp/auth-react

Usage

The package exports a hook usePlasmicAuth hook for getting the current user and managing Plasmic’s auth flow.

Copy
import * as React from 'react';
import { PlasmicComponent, PlasmicRootProvider } from '@plasmicapp/loader-nextjs';
import { PLASMIC } from '../plasmic-init';
import { usePlasmicAuth } from '@plasmicapp/auth-react';

export default function PlasmicLoaderPage() {
  const { isUserLoading, user, token } = usePlasmicAuth({
    appId: 'YOUR_APP_ID'
  });

  return (
    <PlasmicRootProvider
      loader={PLASMIC}
      prefetchedData={plasmicData}
      prefetchedQueryData={queryCache}
      pageParams={pageMeta.params}
      isUserLoading={isUserLoading}
      userAuthToken={token}
      user={user}
      authRedirectUri={'YOUR_REDIRECT_URI'}
    >
      <PlasmicComponent component={pageMeta.displayName} />
    </PlasmicRootProvider>
  );
}

Since PlasmicRootProvider requires user data, you’ll need to call usePlasmicAuth wherever you mount PlasmicRootProvider.

The REDIRECT_URI field must match one of the “Redirect URIs” in the “Settings” tab of the auth configuration dialog in Plasmic Studio. You’ll likely want to add both your production and local servers.

Custom auth provider

This guide is for projects that use a custom auth provider. Note that if you use a custom auth provider, you must self-host.

Configuration

In Plasmic Studio, make sure you have auth enabled first. Then find the “Provider” field in the “Settings” tab, and choose “Custom Auth”.

The “Token” field shows your application secret token. This token should only be used on the server and never be exposed to the client.

Installation

Install the @plasmicapp/auth-api package.

Copy
npm install @plasmicapp/auth-api
# or yarn add @plasmicapp/auth-api

@plasmicapp/auth-api provides a simple API that your server should use to communicate with Plasmic about the user’s authentication status:

• createPlasmicAppUser should be called when a user logs in to your application. This function will create a Plasmic user for the user and return a user token that you can use to authenticate the user in Plasmic.
• getPlasmicAppUserFromToken should be called when a user visits your application. This function will verify the user token and return the Plasmic user associated with the token.

createPlasmicAppUser

createPlasmicAppUser creates a Plasmic user that’s going to be associated with your application. If the user already exists, it will return the existing user. You should call createPlasmicAppUser after your user successfully logs in.

The following snippet shows how this function could be used in an auth callback handler:

authCallback.ts
Copy
import { createPlasmicAppUser } from '@plasmicapp/auth-api';

async function authCallback() {
  // Logic to handle the callback

  // After callback handling
  // ...
  const result = await createPlasmicAppUser({
    email: 'USER_EMAIL',
    appSecret: 'YOUR_APP_SECRET'
  });

  // The function won't throw an error, but will return an error message instead
  if (result.error) {
    // Error handling
    console.error(result.error);
  }

  const { user: plasmicUser, token: plasmicUserToken } = result;

  // Store the token in a cookie or session
  // ...
}

The user token returned by this function should be stored in a cookie or session. The token is valid for 7 days. After that, you should call createPlasmicAppUser again to get a new user token.

getPlasmicAppUserFromToken

Once you have a user token, call getPlasmicAppUserFromToken to exchange the user token for a Plasmic user.

The following snippets show how this function could be used in a Next.js page route with server side rendering:

pages/index.tsx
Copy
import { getPlasmicAppUserFromToken } from '@plasmicapp/auth-api';
import { PlasmicRootProvider, PlasmicComponent, ComponentRenderData } from '@plasmicapp/loader-nextjs';
import { GetServerSideProps } from 'next';
import { PLASMIC } from '../plasmic-init';

// SSR fetch the data needed to render Plasmic pages or components and the plasmic user
export const getServerSideProps: GetServerSideProps = async (ctx) => {
  const plasmicData = await PLASMIC.fetchComponentData('Dashboard');
  if (!plasmicData) {
    throw new Error('No Plasmic design found');
  }

  // Retrieve user token from the cookie or session and call `getPlasmicAppUserFromToken`
  const plasmicUserToken = retrievePlasmicUserToken(ctx);
  const { user: plasmicUser } = getPlasmicUserFromToken({
    token: plasmicUserToken
  });

  return {
    props: {
      plasmicData,
      plasmicUser,
      plasmicUserToken
    }
  };
};

// Render the page or component from Plasmic.
export default function Dashboard(props: {
  plasmicData: ComponentRenderData;
  plasmicUser?: any;
  plasmicUserToken?: string;
}) {
  const compMeta = props.plasmicData.entryCompMetas[0];
  return (
    <PlasmicRootProvider
      loader={PLASMIC}
      prefetchedData={props.plasmicData}
      // Pass in the plasmic user and user token
      user={props.plasmicUser}
      userAuthToken={props.plasmicUserToken}
    >
      <PlasmicComponent component={compMeta.displayName} />
    </PlasmicRootProvider>
  );
}

Give feedback on this page