@prefabs.tech/saas-react

This package provides essential tools and components to support SaaS functionality in React applications. It simplifies account management, routing, and configuration for multi-tenant SaaS platforms.

Installation

Install with npm:

npm install @prefabs.tech/saas-react

Install with pnpm:

pnpm add --filter "@scope/project" @prefabs.tech/saas-react

Usage

Basic setup

To use this package, update the App.tsx to wrap your application code with SaasWrapper. This wrapper manages account-related states and configurations.

import { useUser } from "@prefabs.tech/react-user";
import { SaasWrapper } from "@prefabs.tech/saas-react";
import { ToastContainer } from "react-toastify";

import config from "./config";
import { AppRouter } from "./Router";

function App() {
  const { user } = useUser();

  return (
    <SaasWrapper userId={user?.id} config={config.saas}>
      <AppRouter />
      <ToastContainer position="top-center" />
    </SaasWrapper>
  );
}

export default App;

Configuration

The SaasWrapper accepts a config prop to customize its behavior. Below are the available options with detailed explanations:

export type SaasConfig = {
  accounts?: {
    autoSelectAccount?: boolean;
    allowMultipleSessions?: boolean;
    signup?: {
      apiPath?: string;
      appRedirection?: boolean;
      termsAndConditionsUrl?: string;
    };
  };
  apiBaseUrl: string;
  entity: "both" | "individual" | "organization";
  mainAppSubdomain: string;
  rootDomain: string;
  multiDatabase: boolean;
  saasAccountRoles?: string[];
  subdomains: "required" | "optional" | "disabled";
  ui?: {
    account?: {
      form?: {
        actionsAlignment?: "center" | "fill" | "left" | "right";
        actionsReverse?: boolean;
      };
    };
    invitation?: {
      form?: {
        actionsAlignment?: "center" | "fill" | "left" | "right";
        actionsReverse?: boolean;
      };
    };
    signup?: {
      form?: {
        actionsAlignment?: "center" | "fill" | "left" | "right";
        actionsReverse?: boolean;
      };
    };
  };
};

Detailed attribute descriptions

• accounts: Contains account-specific configurations.
  • autoSelectAccount: When enabled (default), the system automatically selects an account for the user if they have only one account.
  • allowMultipleSessions: When enabled (default), users can maintain multiple active sessions across different accounts.
  • signup: Configuration for signup-related operations.
    • apiPath: The api path for signup
    • appRedirection: Indicates whether to redirect to the app after signup.
    • termsAndConditionsUrl: url for the terms and conditions page.
• apiBaseUrl: The base url for all api requests.
• entity: The type of accounts allowed.
• mainAppSubdomain: [Depricated: use mainApp.subdomain] Specifies the subdomain for the main application.
• mainApp: Configuration for main app's domain and subdomain
  • subdomain: Specifies the subdomain for the main application
  • domain: Specifies the full domain for the main applications
• rootDomain: The root domain of your SaaS platform.
• multiDatabase: Indicates whether the SaaS platform supports multiple databases.
• saasAccountRoles: A list of roles available for accounts in the SaaS platform. Used when inviting users to an account.
• subdomains: Specifies the subdomain behavior for the SaaS platform. Options include:
  • "required": Subdomains are mandatory for tenant identification.
  • "optional": Subdomains are optional and can be used if needed.
  • "disabled": Subdomains are not used in the SaaS platform. ui: UI related configuration for customization.

Routing

This package provides pre-configured routes for SaaS applications, designed to simplify navigation in multi-tenant platforms. The two main methods for generating routes are:

getSaasAdminRoutes

• Purpose: Generates routes for the admin section of a SaaS application.
• Ideal use case: Use this method in your Admin App.
• Parameters:
  • type: Specifies the type of routes. Options:
    • "authenticated" (default): Routes for authenticated users.
    • "unauthenticated": Routes for unauthenticated users. No routes are returned at the moment.
    • "public": Routes for public users. No routes are returned at the moment.
  • options: An optional object to customize routes. Following route options are available under options.routes:
    • accountsAdd: Customizes the "Add Account" route.
    • accountsEdit: Customizes the "Edit Account" route.
    • accountsView: Customizes the "Viefw Account" route.

getSaasAppRoutes

• Purpose: Generates routes for the main application section of a SaaS platform.
• Ideal use case: Use this method in your Main App.
• Parameters:
  • type: Specifies the type of routes. Options:
    • "authenticated" (default): Routes for authenticated users.
    • "unauthenticated": Routes for unauthenticated users.
    • "public": Routes for public access.
  • options: An optional object to customize routes. Following route options are available under options.routes:
    • accountSettings: Customizes the "Account Settings" route.
    • invitationAccept: Customizes the "Accept Invitation" route.
    • invitationJoin: Customizes the "Join Invitation" route.
    • invitationSignup: Customizes the "Signup Invitation" route.
    • myAccounts: Customizes the "My Accounts" route.
    • signup: Customizes the "Signup" route.

Example usage

import {
  getSaasAdminRoutes,
  getSaasAppRoutes,
} from "@prefabs.tech/saas-react/routes";

// Admin App
const adminRoutes = getSaasAdminRoutes();

// Main App
const appRoutes = getSaasAppRoutes();

These methods allow you to easily define and manage routes for different sections of your SaaS platform.

Components and pages

This package provides several reusable components and pages to simplify SaaS application development. Below is a list of all exported components and pages:

Components

• Account components:
  • AccountSwitcher: Allows users to switch between accounts.
  • AccountForm: A form for creating or editing account details.
  • AccountInfo: Displays detailed information about an account.
  • AccountInvitationForm: A form for sending account invitations.
  • AccountInvitationModal: A modal for managing account invitations.
  • AccountInvitationsTable: Displays a table of account invitations.
  • AccountSignupForm: A form for signing up for an account.
  • AccountUsersTable: Displays a table of users associated with an account.
  • AccountsTable: Displays a table of all accounts.
  • MyAccounts: Displays a list of accounts associated with the user.
  • UserSignupForm: A form for user signup.

Pages

• AcceptInvitation pages:

  • AcceptInvitationPage: Handles the process of accepting an invitation to join or signup to an account.
  • JoinInvitationPage: Manages the process of joining an account via an invitation.
  • SignupInvitationPage: Facilitates signing up for an account through an invitation.

• Account pages:

  • AccountAddPage: Provides a page for adding a new account.
  • AccountEditPage: Allows editing of existing account details.
  • AccountSettingsPage: Displays and manages account information including user and invitations.
  • AccountViewPage: Shows detailed information about a specific account.

• MyAccounts pages:

  • MyAccountsPage: Displays a list of accounts associated with the user and allows account switching or management.

• Signup pages:

  • SignupPage: Facilitates user signup and account creation processes. Dynamically renders either an AccountSignupForm or UserSignupForm based on the app context (main app or user app).

These components and pages can be imported and used directly in your application.

Customizing tabs in AccountViewPage and AccountSettingsPage

To cutomize the tabs in AccountViewPage in admin app and AccountSettingsPage in user app, you can import these page components in your app and pass it as custom element to the route option in getSaasAdminRoutes or getSaasAppRoutes. Then you can use the page props to customize the tabs in the page along with other attributes.

{getSaasAdminRoutes("authenticated", {
  routes: {
    // accountSettings in case of user app
    accountsView: {
      element: (
        <AccountViewPage // <AccountSettingsPage /> in case of user app
          showToolbar={true} // to show/hide page toolbar, supported only in AccountViewPage
          tabs={[
            {
              key: "newTab",
              label: "New tab",
              children: <div>Content of new tab</div>,
            },
          ]}
          activeTab="info"
          visibleTabs={["info", "users", "invitations", "newTab"]}
        />
      ),
    },
  },
})}

• To add new tab, add new tab (type: AccountTab) object in tabs prop
• To change the default tab when opening the page, update value in the activeTab prop
• To change the order of tabs, change order of elements in the visibleTabs prop
• To customize existing tab, add an object in tabs with its key and update any attribute. for example {key: "info", label: "Information"}

See component to check prop types and other options: AccountViewPage AccountSettingsPage

Customizing form actions aligment

To customize the actions alignment in forms, you can pass following config options in saas config

ui?: {
    account?: {
      form?: {
        actionsAlignment?: "center" | "fill" | "left" | "right";
        actionsReverse?: boolean;
      };
    };
    invitation?: {
      form?: {
        actionsAlignment?: "center" | "fill" | "left" | "right";
        actionsReverse?: boolean;
      };
    };
    signup?: {
      form?: {
        actionsAlignment?: "center" | "fill" | "left" | "right";
        actionsReverse?: boolean;
      };
    };
  };

The current default values are as following

export const CONFIG_UI_DEFAULT = {
  account: {
    form: {
      actionsAlignment: "right" as const,
      actionsReverse: false,
    },
  },
  invitation: {
    form: {
      actionsAlignment: "fill" as const,
      actionsReverse: true,
    },
  },
  signup: {
    form: {
      actionsAlignment: "fill" as const,
      actionsReverse: true,
    },
  },
};

You can play around with actionsAligment and actionsReverse configs to get desired alignment of form actions.

i18n support

This package uses @prefabs.tech/react-i18n for translations. By default, it uses the following namespaces:

• account
• accounts

These namespaces are available in the following locales:

• English (en): locales/en/account.json, locales/en/accounts.json
• French (fr): locales/fr/account.json, locales/fr/accounts.json

Ensure you register these namespaces in your application's i18n setup.

Refer to the locales/en and locales/fr folders for the required translation keys.