diff --git a/v2/emailpassword/advanced-customizations/frontend-functions-override/usage.mdx b/v2/emailpassword/advanced-customizations/frontend-functions-override/usage.mdx index f5c4941dd..43dc0d793 100644 --- a/v2/emailpassword/advanced-customizations/frontend-functions-override/usage.mdx +++ b/v2/emailpassword/advanced-customizations/frontend-functions-override/usage.mdx @@ -2,22 +2,27 @@ id: usage title: How to use hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # How to use ## Use the override config + + + + + + :::info See all the [functions that can be overrided here](https://supertokens.com/docs/auth-react/modules/recipe_emailpassword.html#RecipeInterface) ::: - - - ```tsx import SuperTokens from "supertokens-auth-react"; import EmailPassword from "supertokens-auth-react/recipe/emailpassword"; @@ -54,8 +59,62 @@ SuperTokens.init({ ] }); ``` + - + + +:::info +See all the [functions that can be overrided here](https://supertokens.com/docs/web-js/modules/recipe_emailpassword.html#RecipeInterface) +::: + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + supertokensUIEmailPassword.init({ + // highlight-start + override: { + functions: (originalImplementation) => { + return { + ...originalImplementation, + + // we will only be overriding what happens when a user + // clicks the sign in button. + signIn: async function (input) { + // TODO: some custom logic + + // or call the default behaviour as show below + return originalImplementation.signIn(input); + }, + // ... + // TODO: override more functions + } + } + } + // highlight-end + }) + ] +}); +``` + + - `originalImplementation` is an object that contain functions that have the original implementation for this recipe. They can be used in your functions as a way to use the SuperTokens' default behaviour. -- In the above code snippet, we override the `signIn` function of this recipe. This means that when the user clicks the sign in button in the UI, your function will be called with the relevant `input` object. \ No newline at end of file +- In the above code snippet, we override the `signIn` function of this recipe. This means that when the user clicks the sign in button in the UI, your function will be called with the relevant `input` object. + + + + +:::caution +Not applicable since you need to build custom UI anyway, so when you call the functions from our SDK, or call the API directly, you can run pre / post logic in your own code. +::: + + + diff --git a/v2/emailpassword/advanced-customizations/frontend-hooks/handle-event.mdx b/v2/emailpassword/advanced-customizations/frontend-hooks/handle-event.mdx index f3743aec8..23a374b0b 100644 --- a/v2/emailpassword/advanced-customizations/frontend-hooks/handle-event.mdx +++ b/v2/emailpassword/advanced-customizations/frontend-hooks/handle-event.mdx @@ -2,16 +2,21 @@ id: handle-event title: Handle Event Hook hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Handle Event Hook + + + This function is called for various user actions. It can be used for logging, analytics or any side effect purposes (these are essentially fire and forget events). - + ```tsx @@ -38,9 +43,48 @@ EmailPassword.init({ } }) ``` + - + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; +supertokensUIEmailPassword.init({ + onHandleEvent: (context) => { + if (context.action === "PASSWORD_RESET_SUCCESSFUL") { + + } else if (context.action === "RESET_PASSWORD_EMAIL_SENT") { + + } else if (context.action === "SUCCESS") { + if (context.createdNewSession) { + let user = context.user; + if (context.isNewRecipeUser && context.user.loginMethods.length === 1) { + // sign up success + } else { + // sign in success + } + } else { + // this is during second factor login of step up auth flow + } + } + } +}) +``` + + + :::info Also checkout the [session recipe handle event hook](/docs/session/advanced-customizations/frontend-hooks/handle-event). -::: \ No newline at end of file +::: + + + + +:::caution +Not applicable since you need to build custom UI anyway, so when you call the functions from our SDK, or call the API directly, you can run pre / post logic in your own code. +::: + + + \ No newline at end of file diff --git a/v2/emailpassword/advanced-customizations/frontend-hooks/pre-api.mdx b/v2/emailpassword/advanced-customizations/frontend-hooks/pre-api.mdx index 9055e68d9..e8a96b1f6 100644 --- a/v2/emailpassword/advanced-customizations/frontend-hooks/pre-api.mdx +++ b/v2/emailpassword/advanced-customizations/frontend-hooks/pre-api.mdx @@ -59,6 +59,45 @@ EmailPassword.init({ ``` + + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; +supertokensUIEmailPassword.init({ + preAPIHook: async (context) => { + let url = context.url; + + // is the fetch config object that contains the header, body etc.. + let requestInit = context.requestInit; + + let action = context.action; + if (action === "EMAIL_EXISTS") { + + } else if (action === "SEND_RESET_PASSWORD_EMAIL") { + + } else if (action === "EMAIL_PASSWORD_SIGN_IN") { + + } else if (action === "EMAIL_PASSWORD_SIGN_UP") { + + } else if (action === "SUBMIT_NEW_PASSWORD") { + + } else if (action === "VERIFY_EMAIL") { + + } + + // events such as sign out are in the + // session recipe pre API hook (See the info box below) + return { + requestInit, url + }; + } +}) +``` + + :::info diff --git a/v2/emailpassword/advanced-customizations/frontend-hooks/redirection-callback.mdx b/v2/emailpassword/advanced-customizations/frontend-hooks/redirection-callback.mdx index 5e79e74df..7474bb16f 100644 --- a/v2/emailpassword/advanced-customizations/frontend-hooks/redirection-callback.mdx +++ b/v2/emailpassword/advanced-customizations/frontend-hooks/redirection-callback.mdx @@ -2,16 +2,21 @@ id: redirection-callback title: Redirection Callback Hook hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Redirection Callback Hook + + + This function is used to change where the user is redirected to post certain actions. For example, you can use this to redirect a user to a specific URL post sign in / up. If you're embedding the sign in / up components in a popup and wish to disable redirection entirely, simply return `null`. - + ```tsx @@ -61,5 +66,68 @@ SuperTokens.init({ ] }); ``` + - + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; +supertokensUIInit({ + appInfo: { + appName: "SuperTokens", + apiDomain: "http://localhost:3000", + websiteDomain: "http://localhost:3000", + }, + getRedirectionURL: async (context) => { + if (context.action === "TO_AUTH") { + // This is called when we want to navigate to the login page. + // By default, this will go to the configured websiteBasePath (/auth) + } else if (context.action === "SUCCESS" && context.newSessionCreated) { + // This is called when the user has successfully signed in / signed up. + // By default, this will go to "/" or to + // the redirectToPath if it is set (the page from which the user was redirected to the auth page). + let redirectToPath = context.redirectToPath; + if (redirectToPath !== undefined) { + // we are navigating back to where the user was before they authenticated + return redirectToPath; + } + if (context.createdNewUser) { + // user signed up + return "/onboarding" + } else { + // user signed in + return "/dashboard" + } + } + // return undefined to let the default behaviour play out + return undefined; + }, + recipeList: [ + supertokensUIEmailPassword.init({ + getRedirectionURL: async (context) => { + if (context.action === "RESET_PASSWORD") { + // called when the user clicked on the forgot password button + } + // return undefined to let the default behaviour play out + return undefined; + } + }) + ] +}); +``` + + + + + + + +:::caution +Not applicable since you need to build custom UI anyway, so you can redirect the user after calling our SDK functions / API. +::: + + + + diff --git a/v2/emailpassword/advanced-customizations/react-component-override/usage.mdx b/v2/emailpassword/advanced-customizations/react-component-override/usage.mdx index 64fde6cee..52f27720d 100644 --- a/v2/emailpassword/advanced-customizations/react-component-override/usage.mdx +++ b/v2/emailpassword/advanced-customizations/react-component-override/usage.mdx @@ -2,23 +2,27 @@ id: usage title: How to use hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" import {Answer} from "/src/components/question" import {Question}from "/src/components/question" # How to use + + + + + + 1. You will have to use the `EmailPasswordComponentsOverrideProvider` or the `AuthRecipeComponentsOverrideContextProvider` component as shown below. make sure that it render the SuperTokens components inside this component. 2. [Pick a component](#finding-which-component-will-be-overridden) that you'd like to override by its key. 3. Supply a React component against the key you have picked. Your custom component will get the original component as a `prop`. -## Example - - - @@ -117,9 +121,6 @@ Please make sure that the file in which this config is specified is a `.tsx` or ::: - - - ## Finding which component will be overridden To do that, you should use React Developer Tools extension which provides a component tree inspector. @@ -148,3 +149,24 @@ const customComponent = ({ DefaultComponent, ...props }: { DefaultComponent: Rea } ``` + + + + + +:::caution +Not applicable to non-react apps. You can disable the specific pre built UI component, and then build your own UI instead. +::: + + + + + + + +:::caution +Not applicable to custom UI +::: + + + \ No newline at end of file diff --git a/v2/emailpassword/common-customizations/changing-base-path/api-base-path.mdx b/v2/emailpassword/common-customizations/changing-base-path/api-base-path.mdx index f7a1a28f7..04d981956 100644 --- a/v2/emailpassword/common-customizations/changing-base-path/api-base-path.mdx +++ b/v2/emailpassword/common-customizations/changing-base-path/api-base-path.mdx @@ -112,6 +112,45 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +supertokensUIInit({ + appInfo: { + appName: "yourAppName", + apiDomain: "yourApi", + websiteDomain: "yourWebsite", + // highlight-next-line + apiBasePath: "/api/v3/auth" + }, + recipeList: [], +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +// this goes in the root of your frontend app +import SuperTokens from "supertokens-web-js"; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + // highlight-next-line + apiBasePath: "/api/v3/auth", + appName: "...", + }, + recipeList: [/* ... */], +}); +``` + + + diff --git a/v2/emailpassword/common-customizations/changing-base-path/website-base-path.mdx b/v2/emailpassword/common-customizations/changing-base-path/website-base-path.mdx index 0795a935f..3e3e959bd 100644 --- a/v2/emailpassword/common-customizations/changing-base-path/website-base-path.mdx +++ b/v2/emailpassword/common-customizations/changing-base-path/website-base-path.mdx @@ -2,6 +2,7 @@ id: website-base-path title: Website Base Path hide_title: true +show_ui_switcher: true --- @@ -9,6 +10,7 @@ hide_title: true import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" import BackendSDKTabs from "/src/components/tabs/BackendSDKTabs" import BackendSDKCasing from "/src/components/BackendSDKCasing" import TabItem from '@theme/TabItem'; @@ -16,6 +18,10 @@ import TabItem from '@theme/TabItem'; # Website Base Path ## Step 1) Front End Change + + + + Since the beginning of this guide, you probably noticed that all the front-end routes for SuperTokens widget are prefixed by `/auth`. You can change this value in the `init` function by setting websiteBasePath. @@ -39,8 +45,36 @@ SuperTokens.init({ + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +supertokensUIInit({ + appInfo: { + appName: "yourAppName", + apiDomain: "yourApi", + websiteDomain: "yourWebsite", + // highlight-next-line + websiteBasePath: "/authentication" + }, + recipeList: [], +}); +``` + + + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + ## Step 2) Back End Change diff --git a/v2/emailpassword/common-customizations/disable-sign-up/emailpassword-changes.mdx b/v2/emailpassword/common-customizations/disable-sign-up/emailpassword-changes.mdx index 0bdb7a397..aed9fffef 100644 --- a/v2/emailpassword/common-customizations/disable-sign-up/emailpassword-changes.mdx +++ b/v2/emailpassword/common-customizations/disable-sign-up/emailpassword-changes.mdx @@ -142,6 +142,29 @@ SuperTokens.init({ + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + style: ` + [data-supertokens~=authPage] [data-supertokens~=headerSubtitle] { + display: none; + } + `, + recipeList: [ /* ... */] +}); +``` + + + diff --git a/v2/emailpassword/common-customizations/email-verification/about.mdx b/v2/emailpassword/common-customizations/email-verification/about.mdx index 12e146de8..38e945c5f 100644 --- a/v2/emailpassword/common-customizations/email-verification/about.mdx +++ b/v2/emailpassword/common-customizations/email-verification/about.mdx @@ -212,6 +212,54 @@ function App() { + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + // highlight-start + supertokensUIEmailVerification.init({ + mode: "REQUIRED", // or "OPTIONAL" + }), + // highlight-end + ], +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from "supertokens-web-js"; +import EmailVerification from "supertokens-web-js/recipe/emailverification"; +import Session from "supertokens-web-js/recipe/session"; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + // highlight-next-line + EmailVerification.init(), + Session.init(), + ], +}); +``` + + + :::important diff --git a/v2/emailpassword/common-customizations/email-verification/changing-style.mdx b/v2/emailpassword/common-customizations/email-verification/changing-style.mdx index 596a7ca00..de0cbe03c 100644 --- a/v2/emailpassword/common-customizations/email-verification/changing-style.mdx +++ b/v2/emailpassword/common-customizations/email-verification/changing-style.mdx @@ -2,19 +2,20 @@ id: changing-style title: Changing Style via CSS hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Changing Style via CSS -:::important -This is applicable to prebuilt UI only. -::: + + Updating the CSS allows you to change the UI of our components to meet your needs. @@ -30,7 +31,7 @@ Each stylable components contains `data-supertokens` attributes (in our example Let's add a `border` to our `link` elements. The syntax for styling is plain CSS. - + ```tsx @@ -62,7 +63,38 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailVerification.init({ + // highlight-start + style: ` + [data-supertokens~=link] { + border: 2px solid #0076ff; + border-radius: 5; + width: 30%; + margin: 0 auto; + } + `, + // highlight-end + }) + ] +}); +``` + + + The above will result in: @@ -72,7 +104,7 @@ The above will result in: By default, SuperTokens uses the Arial font. The best way to override this is to add a `font-family` styling to the `container` component in the recipe configuration. - + ```tsx @@ -101,13 +133,39 @@ SuperTokens.init({ }); ``` - + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailVerification.init({ + // highlight-start + style: ` + [data-supertokens~=container] { + font-family: cursive + } + ` + // highlight-end + }), + ] +}); +``` + + ### Using media queries You may want to have different CSS for different viewports. This can be achieved via media queries like this: - + ```tsx @@ -145,7 +203,44 @@ SuperTokens.init({ }); ``` - + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + // ... + supertokensUIEmailVerification.init({ + // ... + style: ` + [data-supertokens~=link] { + border: 2px solid #0076ff; + borderRadius: 5; + width: 30%; + margin: 0 auto; + } + + // highlight-start + @media (max-width: 440px) { + [data-supertokens~=link] { + width: 90%; + } + } + // highlight-end + `, + }), + ], +}); +``` + + ## Customising individual screens @@ -153,7 +248,7 @@ SuperTokens.init({ This screen is where the user is redirected if `mode` is set to `REQUIRED` and they visit a path that requires a verified email. - + ```tsx @@ -180,13 +275,38 @@ SuperTokens.init({ }); ``` - + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + supertokensUIEmailVerification.init({ + // highlight-start + sendVerifyEmailScreen: { + style: ` ... ` + } + // highlight-end + }) + ] +}); +``` + + ### Verify link clicked screen This is the screen shown to users that click the email verification link in the email. - + ```tsx @@ -213,4 +333,41 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + supertokensUIEmailVerification.init({ + // highlight-start + verifyEmailLinkClickedScreen: { + style: ` ... `, + } + // highlight-end + }) + ] +}); +``` + + + + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/emailpassword/common-customizations/email-verification/embed-in-page.mdx b/v2/emailpassword/common-customizations/email-verification/embed-in-page.mdx index 8f8a84e8d..d1f1445d2 100644 --- a/v2/emailpassword/common-customizations/email-verification/embed-in-page.mdx +++ b/v2/emailpassword/common-customizations/email-verification/embed-in-page.mdx @@ -2,20 +2,25 @@ id: embed-in-page title: Embed in a page hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" import BackendSDKTabs from "/src/components/tabs/BackendSDKTabs" # Embed in a page + + + ## Step 1: Disable the default implementation - + ```tsx @@ -42,11 +47,39 @@ SuperTokens.init({ If you navigate to `/auth/verify-email`, you should not see the widget anymore. - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailVerification.init({ + mode: "REQUIRED", + // highlight-start + disableDefaultUI: true + // highlight-end + }), + ] +}); +``` + +If you navigate to `/auth/verify-email`, you should not see the widget anymore. + + + ## Step 2: Render the component yourself - + Add the `EmailVerification` component in your app: @@ -68,7 +101,27 @@ class EmailVerificationPage extends React.Component { } ``` - + + + +:::caution +You will have to build your own UI instead. +::: + + + + + + + +## Step 1 & 2: Disable the pre built UI + +:::caution +Not applicable since you do not use our pre built UI +::: + + + ## Step 3: Changing the website path for the email verification UI (optional) @@ -208,7 +261,10 @@ init( ### Step B: On the frontend - + + + + ```tsx @@ -238,4 +294,45 @@ SuperTokens.init({ }) ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + supertokensUIEmailVerification.init({ + mode: "REQUIRED", + //highlight-start + + // The user will be taken to the custom path when they need to get their email verified. + getRedirectionURL: async (context) => { + if (context.action === "VERIFY_EMAIL") { + return "/custom-email-verification-path"; + }; + } + //highlight-end + }) + ] +}) +``` + + + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/emailpassword/common-customizations/email-verification/protecting-routes.mdx b/v2/emailpassword/common-customizations/email-verification/protecting-routes.mdx index d7d7a5ca0..e0bf31003 100644 --- a/v2/emailpassword/common-customizations/email-verification/protecting-routes.mdx +++ b/v2/emailpassword/common-customizations/email-verification/protecting-routes.mdx @@ -1114,8 +1114,8 @@ function ProtectedComponent() { ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { EmailVerificationClaim } from "supertokens-auth-react/recipe/emailverification"; +import Session from "supertokens-web-js/recipe/session"; +import { EmailVerificationClaim } from "supertokens-web-js/recipe/emailverification"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { diff --git a/v2/emailpassword/common-customizations/embed-sign-in-up-form.mdx b/v2/emailpassword/common-customizations/embed-sign-in-up-form.mdx index e0ed9c507..de5021512 100644 --- a/v2/emailpassword/common-customizations/embed-sign-in-up-form.mdx +++ b/v2/emailpassword/common-customizations/embed-sign-in-up-form.mdx @@ -16,12 +16,13 @@ import RRDVersionSubTabs from "/src/components/tabs/RRDVersionSubTabs" + + + ## Case 1: Rendering the Auth Widget in a page The following example shows the scenario where you have a dedicated route, such as `/auth`, for rendering the Auth Widget. Upon a successful login, the user will be automatically redirected to the return value of `getRedirectionURL` (defaulting to `/`). - - @@ -178,8 +179,6 @@ function MyAuthPage() { ``` - - In the above code snippet, we: @@ -196,8 +195,6 @@ When the user visits the `/auth` page, they will see the SignIn UI by default. T The following example shows the scenario where you have a dedicated route, such as `/auth`, for rendering the Auth Widget. However, upon a successful login, the user will see a logged in UI instead of getting redirected. - - @@ -417,8 +414,6 @@ function LandingPage() { ``` - - In the above code snippet, we wrap the logged-in component with `Session.SessionAuth` to validate all claims before displaying the logged-in UI. For instance, with email verification enabled, if a user's email is unverified, `Session.SessionAuth` redirects to the email verification page. @@ -430,8 +425,6 @@ In the above case, redirection may occur if a claim fails. For instance, in the The following example shows the scenario where you embed the Auth Widget in a popup, and upon successful login, you aim to close the popup. - - @@ -690,13 +683,22 @@ function AuthPopup() { ``` - - :::note In the above case, redirection may occur if a claim fails. For instance, in the case of an Email Verification claim, if the user's email is not verified, they will be redirected to the email verification page. To prevent redirection for failed claims, please contact us on [Discord](https://supertokens.com/discord) for assistance. ::: + + + + +:::caution +Not applicable to non-react apps. Please build your own custom UI instead. +::: + + + + diff --git a/v2/emailpassword/common-customizations/handling-signin-success.mdx b/v2/emailpassword/common-customizations/handling-signin-success.mdx index e5050bcd9..52f260bad 100644 --- a/v2/emailpassword/common-customizations/handling-signin-success.mdx +++ b/v2/emailpassword/common-customizations/handling-signin-success.mdx @@ -61,6 +61,46 @@ Please refer to [this page](../advanced-customizations/frontend-hooks/handle-eve + + +This method allows you to fire events immediately after a successful sign in. For example to send analytics events post sign in. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailPassword.init({ + // highlight-start + onHandleEvent: async (context) => { + if (context.action === "SUCCESS") { + if (context.isNewRecipeUser && context.user.loginMethods.length === 1) { + // TODO: Sign up + } else { + // TODO: Sign in + } + } + } + // highlight-end + }), + supertokensUISession.init() + ] +}); +``` + +:::info +Please refer to [this page](../advanced-customizations/frontend-hooks/handle-event) to learn more about the `onHandleEvent` hook. +::: + + + diff --git a/v2/emailpassword/common-customizations/handling-signup-success.mdx b/v2/emailpassword/common-customizations/handling-signup-success.mdx index cc7da04bf..31e8e2db6 100644 --- a/v2/emailpassword/common-customizations/handling-signup-success.mdx +++ b/v2/emailpassword/common-customizations/handling-signup-success.mdx @@ -61,6 +61,46 @@ Please refer to [this page](../advanced-customizations/frontend-hooks/handle-eve + + +This method allows you to fire events immediately after a successful sign up. For example to send analytics events post sign up. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailPassword.init({ + // highlight-start + onHandleEvent: async (context) => { + if (context.action === "SUCCESS") { + if (context.isNewRecipeUser && context.user.loginMethods.length === 1) { + // TODO: Sign up + } else { + // TODO: Sign in + } + } + } + // highlight-end + }), + supertokensUISession.init() + ] +}); +``` + +:::info +Please refer to [this page](../advanced-customizations/frontend-hooks/handle-event) to learn more about the `onHandleEvent` hook. +::: + + + diff --git a/v2/emailpassword/common-customizations/multi-tenancy/common-domain-login.mdx b/v2/emailpassword/common-customizations/multi-tenancy/common-domain-login.mdx index 5df96868d..6ae04d6bd 100644 --- a/v2/emailpassword/common-customizations/multi-tenancy/common-domain-login.mdx +++ b/v2/emailpassword/common-customizations/multi-tenancy/common-domain-login.mdx @@ -173,51 +173,6 @@ export const AuthPage = () => { - - - - -```tsx -import { useState } from "react"; -import { getRoutingComponent } from "supertokens-auth-react/ui"; -^{prebuiltuiimport} -import { useSessionContext } from "supertokens-auth-react/recipe/session"; - -export const AuthPage = () => { - const [inputTenantId, setInputTenantId] = useState(""); - const tenantId = localStorage.getItem("tenantId") ?? undefined; - const session = useSessionContext(); - - if (session.loading) { - return null; - } - - if ( - tenantId !== undefined || // if we have a tenantId stored - session.doesSessionExist === true || // or an active session (it'll contain the tenantId) - new URLSearchParams(location.search).has("tenantId") // or we are on a link (e.g.: email verification) that contains the tenantId - ) { - return getRoutingComponent([^{recipePreBuiltUINameCapitalLetters}]); - } else { - return ( -
{ - // this value will be read by SuperTokens as shown in the next steps. - localStorage.setItem("tenantId", inputTenantId); - }}> -

Enter your organisation's name:

- setInputTenantId(e.target.value)} /> -
- -
- ); - } -}; -``` - - - - - We render a simple UI which asks the user for their organisation's name. Their input will be treated as their tenant ID. - Once the user has submitted that form, we will store their input in localstorage. This value will be read later on (as shown below) by SuperTokens to render the right login method based on the saved tenantId. - In case the tenantID exists in localstorage, we render the SuperTokens UI as usual. @@ -233,6 +188,20 @@ We want to render the `AuthPage` component to show on `^{form_websiteBasePath}/* The `AuthPage` will replace the call to `getSuperTokensRoutesForReactRouterDom` or `getRoutingComponent` that you may have added to your app from the quick setup section. ::: + + + + +:::caution +No code snippet provided here, however, if you visit the auth component, you will see that we are rendering the pre built UI in the `"supertokensui"` `div` element on page load. The logic here needs to change to first check if the user has provided us with the tenantId. If they have, we render the SuperTokens UI as usual. If they have not, we render a simple UI which asks the user for their tenant id and save that in localstorage. + +Switch to the React code tab here to see how this is implemented in React, and a similar logic can be followed here. +::: + + + + + @@ -376,6 +345,50 @@ We also set the `usesDynamicLoginMethods` to `true` which tells SuperTokens that + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIMultitenancy from "supertokens-auth-react-script/recipe/multitenancy"; + +supertokensUIInit({ + appInfo: { + appName: "...", + apiDomain: "...", + websiteDomain: "...", + apiBasePath: "...", + websiteBasePath: "..." + }, + // highlight-next-line + usesDynamicLoginMethods: true, + recipeList: [ + // highlight-start + supertokensUIMultitenancy.init({ + override: { + functions: (oI) => { + return { + ...oI, + getTenantId: (input) => { + let tid = localStorage.getItem("tenantId"); + return tid === null ? undefined : tid; + } + } + } + } + }) + // highlight-end + // other recipes... + ] +}); +``` + +:::important +We also set the `usesDynamicLoginMethods` to `true` which tells SuperTokens that the login methods are dynamic (based on the tenantId). This means that on page load (of the login page), SuperTokens will first fetch the configured login methods for the tenantId and display the login UI based on the result of the API call. +::: + + + @@ -641,6 +654,42 @@ SuperTokens.init({ + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; +import supertokensUIMultitenancy from "supertokens-auth-react-script/recipe/multitenancy"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + // highlight-start + getRedirectionURL: async (context) => { + if (context.action === "SUCCESS" && context.newSessionCreated) { + let claimValue: string[] | undefined = await supertokensUISession.getClaimValue({ + claim: supertokensUIMultitenancy.AllowedDomainsClaim + }); + if (claimValue !== undefined) { + window.location.href = "https://" + claimValue[0]; + } else { + // there was no configured allowed domain for this user. Throw an error cause of + // misconfig or redirect to a default sub domain + } + } + return undefined; + }, + // highlight-end + recipeList: [ /* Recipe init here... */ ] +}); +``` + + + @@ -761,6 +810,68 @@ Above, in `Session.init` on the frontend, we add the `hasAccessToCurrentDomain` + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; +import supertokensMultitenancy from "supertokens-web-js-script/recipe/multitenancy"; + +supertokensUISession.init({ + override: { + functions: (oI) => ({ + ...oI, + getGlobalClaimValidators: ({ claimValidatorsAddedByOtherRecipes }) => [ + ...claimValidatorsAddedByOtherRecipes, + { + ...supertokensMultitenancy.AllowedDomainsClaim.validators.hasAccessToCurrentDomain(), + onFailureRedirection: async () => { + let claimValue = await supertokensUISession.getClaimValue({ + claim: supertokensMultitenancy.AllowedDomainsClaim, + }); + return "https://" + claimValue![0]; + }, + }, + ], + }), + }, +}) +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: +```tsx +import Session from 'supertokens-web-js/recipe/session'; +import { AllowedDomainsClaim } from 'supertokens-web-js/recipe/multitenancy'; + +Session.init({ + override: { + functions: (oI) => ({ + ...oI, + getGlobalClaimValidators: ({ claimValidatorsAddedByOtherRecipes }) => [ + ...claimValidatorsAddedByOtherRecipes, + { + ...AllowedDomainsClaim.validators.hasAccessToCurrentDomain(), + onFailureRedirection: async () => { + let claimValue = await Session.getClaimValue({ + claim: AllowedDomainsClaim, + }); + return "https://" + claimValue![0]; + }, + }, + ], + }), + }, +}) +``` + +Above, in `Session.init` on the frontend, we add the `hasAccessToCurrentDomain` claim validator to the global validators. This means, that [whenever we check protect a route](../sessions/protecting-frontend-routes), it will check if `hasAccessToCurrentDomain` has passed, and if not, SuperTokens will redirect to the user to their right sub domain (via the values set in the `AllowedDomainsClaim` session claim). + + + diff --git a/v2/emailpassword/common-customizations/multi-tenancy/sub-domain-login.mdx b/v2/emailpassword/common-customizations/multi-tenancy/sub-domain-login.mdx index 1919f2b83..947ba5bf0 100644 --- a/v2/emailpassword/common-customizations/multi-tenancy/sub-domain-login.mdx +++ b/v2/emailpassword/common-customizations/multi-tenancy/sub-domain-login.mdx @@ -135,6 +135,49 @@ SuperTokens.init({ + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; +import supertokensUIMultitenancy from "supertokens-auth-react-script/recipe/multitenancy"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; +supertokensUIInit({ + appInfo: { + appName: "^{form_appName}", + apiDomain: "^{form_apiDomain}", + websiteDomain: "^{form_websiteDomain}", + apiBasePath: "^{form_apiBasePath}", + websiteBasePath: "^{form_websiteBasePath}" + }, + // highlight-start + usesDynamicLoginMethods: true, + // highlight-end + recipeList: [ + supertokensUIEmailPassword.init(), + supertokensUISession.init(), + // highlight-start + supertokensUIMultitenancy.init({ + override: { + functions: (oI) => { + return { + ...oI, + getTenantId: async () => { + // We treat the sub domain as the tenant ID + return window.location.host.split('.')[0] + } + } + } + }, + }) + // highlight-end + ] +}); +``` + + + @@ -475,6 +518,68 @@ Above, in `Session.init` on the frontend, we add the `hasAccessToCurrentDomain` + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; +import supertokensMultitenancy from "supertokens-web-js-script/recipe/multitenancy"; + +supertokensUISession.init({ + override: { + functions: (oI) => ({ + ...oI, + getGlobalClaimValidators: ({ claimValidatorsAddedByOtherRecipes }) => [ + ...claimValidatorsAddedByOtherRecipes, + { + ...supertokensMultitenancy.AllowedDomainsClaim.validators.hasAccessToCurrentDomain(), + onFailureRedirection: async () => { + let claimValue = await supertokensUISession.getClaimValue({ + claim: supertokensMultitenancy.AllowedDomainsClaim, + }); + return "https://" + claimValue![0]; + }, + }, + ], + }), + }, +}) +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: +```tsx +import Session from 'supertokens-web-js/recipe/session'; +import { AllowedDomainsClaim } from 'supertokens-web-js/recipe/multitenancy'; + +Session.init({ + override: { + functions: (oI) => ({ + ...oI, + getGlobalClaimValidators: ({ claimValidatorsAddedByOtherRecipes }) => [ + ...claimValidatorsAddedByOtherRecipes, + { + ...AllowedDomainsClaim.validators.hasAccessToCurrentDomain(), + onFailureRedirection: async () => { + let claimValue = await Session.getClaimValue({ + claim: AllowedDomainsClaim, + }); + return "https://" + claimValue![0]; + }, + }, + ], + }), + }, +}) +``` + +Above, in `Session.init` on the frontend, we add the `hasAccessToCurrentDomain` claim validator to the global validators. This means, that [whenever we check protect a route](../sessions/protecting-frontend-routes), it will check if `hasAccessToCurrentDomain` has passed, and if not, SuperTokens will redirect to the user to their right sub domain (via the values set in the `AllowedDomainsClaim` session claim). + + + diff --git a/v2/emailpassword/common-customizations/password-managers.mdx b/v2/emailpassword/common-customizations/password-managers.mdx index e4f437d2c..eb8a91d71 100644 --- a/v2/emailpassword/common-customizations/password-managers.mdx +++ b/v2/emailpassword/common-customizations/password-managers.mdx @@ -2,13 +2,20 @@ id: password-managers title: Password managers hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" + + + +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Password managers + + Styling encapsulation relies on the ["shadow DOM" browser feature](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM). @@ -16,7 +23,7 @@ Unfortunately, password managers such as Dashlane, LastPass, OnePassword, etc do Therefore, if you would like to make sure that your end users can use their password managers, you will have to disable shadow DOM. - + ```tsx @@ -34,7 +41,24 @@ SuperTokens.init({ ``` - + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + useShadowDom: false, + recipeList: [ /* ... */] +}); +``` + + + Demo of a password manager working with prebuilt UI when shadow DOM is disabled @@ -43,3 +67,13 @@ SuperTokens.init({ - SuperTokens uses a special attribute to define its styling so disabling shadow DOM should not impact the rest of your application's styles. On the other hand, when disabling Shadow DOM, make sure to verify that your CSS does not impact how SuperTokens UI is rendered. - Shadow DOM will always be disabled with Internet Explorer since it does not support it. Similarly, if you intend to support Internet Explorer for your application make sure to verify how SuperTokens UI is rendered. ::: + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/emailpassword/common-customizations/reset-password/embed-in-page.mdx b/v2/emailpassword/common-customizations/reset-password/embed-in-page.mdx index abf5ddafd..3571a8550 100644 --- a/v2/emailpassword/common-customizations/reset-password/embed-in-page.mdx +++ b/v2/emailpassword/common-customizations/reset-password/embed-in-page.mdx @@ -2,20 +2,25 @@ id: embed-in-page title: Embed in a page hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" import BackendSDKTabs from "/src/components/tabs/BackendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Embed in a page + + + ## Step 1: Disable the default implementation - + ```tsx @@ -40,7 +45,34 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailPassword.init({ + // highlight-start + resetPasswordUsingTokenFeature: { + disableDefaultUI: true + }, + // highlight-end + }), + ] +}); +``` + + + If you navigate to `/auth/reset-password`, you should not see the widget anymore. @@ -49,7 +81,7 @@ If you navigate to `/auth/reset-password`, you should not see the widget anymore Add the `ResetPasswordUsingToken` component in your app: - + ```tsx @@ -68,7 +100,27 @@ class ResetPasswordPage extends React.Component { } ``` - + + + +:::caution +You will have to build your own UI for this. +::: + + + + + + + +## Step 1 & 2: Disable the pre built UI. + +:::caution +Not applicable since you do not use our pre built UI. +::: + + + ## Step 3: Changing the website path for reset password UI (optional) @@ -205,7 +257,10 @@ init( ### Step B: On the frontend - + + + + ```tsx @@ -233,5 +288,47 @@ SuperTokens.init({ ] }) ``` + + + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + supertokensUIEmailPassword.init({ + //highlight-start + + // The user will be taken to the custom path when they click on forgot password. + getRedirectionURL: async (context) => { + if (context.action === "RESET_PASSWORD") { + return "/custom-reset-password-path"; + }; + } + //highlight-end + }) + ] +}) +``` + - + + + + + +:::caution +Not applicable since you do not use our pre built UI. +::: + + + diff --git a/v2/emailpassword/common-customizations/sessions/claims/access-token-payload.mdx b/v2/emailpassword/common-customizations/sessions/claims/access-token-payload.mdx index 828b6cb16..ac18be4b9 100644 --- a/v2/emailpassword/common-customizations/sessions/claims/access-token-payload.mdx +++ b/v2/emailpassword/common-customizations/sessions/claims/access-token-payload.mdx @@ -1111,7 +1111,7 @@ async function someFunc() { ```tsx -import Session from 'supertokens-auth-react/recipe/session'; +import Session from 'supertokens-web-js/recipe/session'; async function someFunc() { if (await Session.doesSessionExist()) { diff --git a/v2/emailpassword/common-customizations/sessions/claims/claim-validators.mdx b/v2/emailpassword/common-customizations/sessions/claims/claim-validators.mdx index 8ffe6e207..2a7b59a42 100644 --- a/v2/emailpassword/common-customizations/sessions/claims/claim-validators.mdx +++ b/v2/emailpassword/common-customizations/sessions/claims/claim-validators.mdx @@ -856,8 +856,8 @@ Now whenever you wrap your component with the `` wrapper, SuperToke ```tsx -import SuperTokens from "supertokens-auth-react"; -import Session, { BooleanClaim } from 'supertokens-auth-react/recipe/session'; +import SuperTokens from "supertokens-web-js"; +import Session, { BooleanClaim } from 'supertokens-web-js/recipe/session'; const SecondFactorClaim = new BooleanClaim({ id: "2fa-completed", @@ -870,7 +870,6 @@ SuperTokens.init({ appInfo: { apiDomain: "...", appName: "...", - websiteDomain: "..." }, recipeList: [ //... @@ -894,7 +893,7 @@ SuperTokens.init({ Now you can protect your frontend routes by using the `Session.validateClaims` function as shown below: ```tsx -import Session, { BooleanClaim } from "supertokens-auth-react/recipe/session"; +import Session, { BooleanClaim } from "supertokens-web-js/recipe/session"; const SecondFactorClaim = new BooleanClaim({ id: "2fa-completed", @@ -2286,8 +2285,8 @@ Unlike using the `overrideGlobalClaimValidators` prop, the `useClaimValue` funct ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { @@ -2330,8 +2329,8 @@ async function shouldLoadRoute(): Promise { If you want to have more complex access control, you can get the roles list from the session as follows, and check the list yourself: ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { diff --git a/v2/emailpassword/common-customizations/sessions/disable-interception.mdx b/v2/emailpassword/common-customizations/sessions/disable-interception.mdx index e1a878e6e..7d4a03d8a 100644 --- a/v2/emailpassword/common-customizations/sessions/disable-interception.mdx +++ b/v2/emailpassword/common-customizations/sessions/disable-interception.mdx @@ -58,6 +58,63 @@ Session.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUISession.init({ + override: { + functions: (oI) => { + return { + ...oI, + shouldDoInterceptionBasedOnUrl: (url, apiDomain, sessionTokenBackendDomain) => { + try { + let urlObj = new URL(url); + if (!urlObj.pathname.startsWith("/auth")) { + return false; + } + } catch (ignored) { } + return oI.shouldDoInterceptionBasedOnUrl(url, apiDomain, sessionTokenBackendDomain); + } + } + } + } +}) +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import Session from "supertokens-web-js/recipe/session"; + +Session.init({ + override: { + functions: (oI) => { + return { + ...oI, + shouldDoInterceptionBasedOnUrl: (url, apiDomain, sessionTokenBackendDomain) => { + try { + let urlObj = new URL(url); + if (!urlObj.pathname.startsWith("/auth")) { + return false; + } + } catch (ignored) { } + return oI.shouldDoInterceptionBasedOnUrl(url, apiDomain, sessionTokenBackendDomain); + } + } + } + } +}) +``` + + + diff --git a/v2/emailpassword/common-customizations/sessions/in-iframe.mdx b/v2/emailpassword/common-customizations/sessions/in-iframe.mdx index e43e2fa15..0589f4b94 100644 --- a/v2/emailpassword/common-customizations/sessions/in-iframe.mdx +++ b/v2/emailpassword/common-customizations/sessions/in-iframe.mdx @@ -69,6 +69,65 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; +declare let cookieHandler: any // typecheck-only, removed from output +declare let windowHandler: any // typecheck-only, removed from output + +supertokensUIInit({ + cookieHandler, + windowHandler, + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUISession.init({ + // highlight-start + tokenTransferMethod: "header", + isInIframe: true + // highlight-end + }) + ] +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from "supertokens-web-js"; +import Session from "supertokens-web-js/recipe/session"; +declare let cookieHandler: any // typecheck-only, removed from output +declare let windowHandler: any // typecheck-only, removed from output + +SuperTokens.init({ + cookieHandler, + windowHandler, + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + Session.init({ + // highlight-start + tokenTransferMethod: "header", + isInIframe: true + // highlight-end + }) + ], +}) +``` + + + @@ -84,8 +143,12 @@ SuperTokens.init({ ```tsx import SuperTokens from "supertokens-web-js"; import Session from "supertokens-web-js/recipe/session"; +declare let cookieHandler: any // typecheck-only, removed from output +declare let windowHandler: any // typecheck-only, removed from output SuperTokens.init({ + cookieHandler, + windowHandler, appInfo: { apiDomain: "...", appName: "...", @@ -107,7 +170,11 @@ SuperTokens.init({ ```tsx import supertokens from "supertokens-web-js-script"; import supertokensSession from "supertokens-web-js-script/recipe/session"; +declare let cookieHandler: any // typecheck-only, removed from output +declare let windowHandler: any // typecheck-only, removed from output supertokens.init({ + cookieHandler, + windowHandler, appInfo: { apiDomain: "...", appName: "...", diff --git a/v2/emailpassword/common-customizations/sessions/multiple-api-endpoints.mdx b/v2/emailpassword/common-customizations/sessions/multiple-api-endpoints.mdx index 2b9aae909..12d91616d 100644 --- a/v2/emailpassword/common-customizations/sessions/multiple-api-endpoints.mdx +++ b/v2/emailpassword/common-customizations/sessions/multiple-api-endpoints.mdx @@ -241,6 +241,51 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. +```tsx +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUISession.init({ + // highlight-next-line + sessionTokenBackendDomain: ".example.com" + }) + ] +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from 'supertokens-web-js'; +import Session from 'supertokens-web-js/recipe/session'; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + Session.init({ + sessionTokenBackendDomain: ".example.com" + }), + ], +}); +``` + + + diff --git a/v2/emailpassword/common-customizations/sessions/protecting-frontend-routes.mdx b/v2/emailpassword/common-customizations/sessions/protecting-frontend-routes.mdx index 13b1829bc..232bba79f 100644 --- a/v2/emailpassword/common-customizations/sessions/protecting-frontend-routes.mdx +++ b/v2/emailpassword/common-customizations/sessions/protecting-frontend-routes.mdx @@ -123,7 +123,7 @@ function MyDashboardComponent(props: any) { You can use the `doesSessionExist` function to check if a session exists in all your routes. ```tsx -import Session from 'supertokens-auth-react/recipe/session'; +import Session from 'supertokens-web-js/recipe/session'; async function doesSessionExist() { if (await Session.doesSessionExist()) { @@ -211,8 +211,8 @@ function ProtectedComponent() { ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { @@ -255,8 +255,8 @@ async function shouldLoadRoute(): Promise { If you want to have more complex access control, you can get the roles list from the session as follows, and check the list yourself: ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { diff --git a/v2/emailpassword/common-customizations/sessions/revoke-session.mdx b/v2/emailpassword/common-customizations/sessions/revoke-session.mdx index 500a1f526..fdfdad5b9 100644 --- a/v2/emailpassword/common-customizations/sessions/revoke-session.mdx +++ b/v2/emailpassword/common-customizations/sessions/revoke-session.mdx @@ -66,7 +66,7 @@ The [`signOut` method](https://supertokens.com/docs/web-js/modules/recipe_sessio ```tsx // highlight-next-line -import Session from "supertokens-auth-react/recipe/session"; +import Session from "supertokens-web-js/recipe/session"; async function logout () { // highlight-next-line diff --git a/v2/emailpassword/common-customizations/sessions/share-session-across-sub-domains.mdx b/v2/emailpassword/common-customizations/sessions/share-session-across-sub-domains.mdx index 9c95085ab..b0f863386 100644 --- a/v2/emailpassword/common-customizations/sessions/share-session-across-sub-domains.mdx +++ b/v2/emailpassword/common-customizations/sessions/share-session-across-sub-domains.mdx @@ -58,6 +58,56 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + // ... + // this should be equal to the domain where the user will see the login UI + apiDomain: "...", + appName: "...", + websiteDomain: "https://example.com" + }, + recipeList: [ + supertokensUISession.init({ + // highlight-next-line + sessionTokenFrontendDomain: ".example.com" + }) + ] +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from "supertokens-web-js"; +import Session from "supertokens-web-js/recipe/session"; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + Session.init({ + // highlight-start + sessionTokenFrontendDomain: ".example.com" + // highlight-end + }), + ], +}) +``` + + + :::caution diff --git a/v2/emailpassword/common-customizations/sessions/ssr.mdx b/v2/emailpassword/common-customizations/sessions/ssr.mdx index 116901a02..863e5cb5b 100644 --- a/v2/emailpassword/common-customizations/sessions/ssr.mdx +++ b/v2/emailpassword/common-customizations/sessions/ssr.mdx @@ -83,7 +83,7 @@ export function AttemptRefresh(props: any) { ```tsx -import Session from 'supertokens-auth-react/recipe/session'; +import Session from 'supertokens-web-js/recipe/session'; function attemptRefresh() { Session.attemptRefreshingSession().then(success => { diff --git a/v2/emailpassword/common-customizations/sessions/token-transfer-method.mdx b/v2/emailpassword/common-customizations/sessions/token-transfer-method.mdx index d07b73456..05bf214db 100644 --- a/v2/emailpassword/common-customizations/sessions/token-transfer-method.mdx +++ b/v2/emailpassword/common-customizations/sessions/token-transfer-method.mdx @@ -71,6 +71,54 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUISession.init({ + // highlight-next-line + tokenTransferMethod: "header" // or "cookie" + }) + ] +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from "supertokens-web-js"; +import Session from "supertokens-web-js/recipe/session"; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + Session.init({ + // highlight-next-line + tokenTransferMethod: "header" // or "cookie" + }) + ], +}) +``` + + + diff --git a/v2/emailpassword/common-customizations/sessions/with-jwt/read-jwt.mdx b/v2/emailpassword/common-customizations/sessions/with-jwt/read-jwt.mdx index fe1b9a7e5..6406c10f2 100644 --- a/v2/emailpassword/common-customizations/sessions/with-jwt/read-jwt.mdx +++ b/v2/emailpassword/common-customizations/sessions/with-jwt/read-jwt.mdx @@ -435,7 +435,7 @@ async function getJWT() { ```tsx -import Session from 'supertokens-auth-react/recipe/session'; +import Session from 'supertokens-web-js/recipe/session'; async function getJWT() { if (await Session.doesSessionExist()) { diff --git a/v2/emailpassword/common-customizations/signin-form/customising-each-form-field.mdx b/v2/emailpassword/common-customizations/signin-form/customising-each-form-field.mdx index 701d03866..d69adc061 100644 --- a/v2/emailpassword/common-customizations/signin-form/customising-each-form-field.mdx +++ b/v2/emailpassword/common-customizations/signin-form/customising-each-form-field.mdx @@ -70,6 +70,40 @@ SuperTokens.init({ }); ``` + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailPassword.init({ + signInAndUpFeature: { + signInForm: { + // highlight-start + formFields: [{ + id: "email", + label: "customFieldName", + placeholder: "Custom value" + }] + } + // highlight-end + } + }), + supertokensUISession.init() + ] +}); +``` + Prebuilt form UI with custom labels and placeholder @@ -118,6 +152,40 @@ SuperTokens.init({ }); ``` + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailPassword.init({ + signInAndUpFeature: { + signInForm: { + formFields: [{ + id: "email", + label: "Your Email", + // highlight-start + getDefaultValue: () => "john.doe@gmail.com" + // highlight-end + }] + } + } + }), + supertokensUISession.init() + ] +}); +``` + Prebuilt signin form UI with default values for fields @@ -177,6 +245,41 @@ SuperTokens.init({ }); ``` + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailPassword.init({ + signInAndUpFeature: { + signInForm: { + formFields: [{ + id: "email", + label: "Your Email", + placeholder: "Email", + // highlight-start + nonOptionalErrorMsg: "Please add your email" + // highlight-end + }] + } + } + }), + supertokensUISession.init() + ] +}); +``` + Prebuilt form UI with custom error message diff --git a/v2/emailpassword/common-customizations/signup-form/adding-fields.mdx b/v2/emailpassword/common-customizations/signup-form/adding-fields.mdx index d4877ef20..1a4daa911 100644 --- a/v2/emailpassword/common-customizations/signup-form/adding-fields.mdx +++ b/v2/emailpassword/common-customizations/signup-form/adding-fields.mdx @@ -182,6 +182,49 @@ SuperTokens.init({ }); ``` + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailPassword.init({ + signInAndUpFeature: { + // highlight-start + signUpForm: { + formFields: [{ + id: "name", + label: "Full name", + placeholder: "First name and last name" + }, { + id: "age", + label: "Your age", + placeholder: "How old are you?", + }, { + id: "country", + label: "Your country", + placeholder: "Where do you live?", + optional: true + }] + } + // highlight-end + } + }), + supertokensUISession.init() + ] +}); +``` + Prebuilt form UI with extra custom fields diff --git a/v2/emailpassword/common-customizations/signup-form/customising-each-form-field.mdx b/v2/emailpassword/common-customizations/signup-form/customising-each-form-field.mdx index c138b3c94..de3e9b93f 100644 --- a/v2/emailpassword/common-customizations/signup-form/customising-each-form-field.mdx +++ b/v2/emailpassword/common-customizations/signup-form/customising-each-form-field.mdx @@ -70,6 +70,40 @@ SuperTokens.init({ }); ``` + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword" +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailPassword.init({ + signInAndUpFeature: { + signUpForm: { + // highlight-start + formFields: [{ + id: "email", + label: "customFieldName", + placeholder: "Custom value" + }] + } + // highlight-end + } + }), + supertokensUISession.init() + ] +}); +``` + Prebuilt form UI with custom labels and placeholder @@ -129,6 +163,46 @@ SuperTokens.init({ ``` + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword" +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailPassword.init({ + signInAndUpFeature: { + signUpForm: { + formFields: [{ + id: "email", + label: "Your Email", + // highlight-start + getDefaultValue: () => "john.doe@gmail.com" + // highlight-end + }, { + id: "name", + label: "Full name", + // highlight-start + getDefaultValue: () => "John Doe", + // highlight-end + }] + } + } + }), + supertokensUISession.init() + ] +}); +``` + + Prebuilt form UI with default values for fields @@ -195,6 +269,48 @@ SuperTokens.init({ }); ``` + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword" +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailPassword.init({ + signInAndUpFeature: { + signUpForm: { + formFields: [{ + id: "email", + label: "Your Email", + placeholder: "Email", + // highlight-start + nonOptionalErrorMsg: "Please add your email" + // highlight-end + }, { + id: "name", + label: "Full name", + placeholder: "Name", + // highlight-start + nonOptionalErrorMsg: "Full name is required", + // highlight-end + }] + } + } + }), + supertokensUISession.init() + ] +}); +``` + Prebuilt form UI with custom error message @@ -313,6 +429,14 @@ SuperTokens.init({ ] }); ``` + + + + +:::caution +This is not applicable for non React apps. You will have to create your own custom UI instead. +::: + @@ -423,6 +547,17 @@ export default App; + + + +:::caution + +This is not applicable for non React apps. You will have to create your own custom UI instead. + +::: + + + Prebuilt form UI with custom components diff --git a/v2/emailpassword/common-customizations/signup-form/field-validators.mdx b/v2/emailpassword/common-customizations/signup-form/field-validators.mdx index 1197ee889..116c49ab5 100644 --- a/v2/emailpassword/common-customizations/signup-form/field-validators.mdx +++ b/v2/emailpassword/common-customizations/signup-form/field-validators.mdx @@ -86,6 +86,59 @@ SuperTokens.init({ }); ``` + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailPassword.init({ + signInAndUpFeature: { + signUpForm: { + formFields: [{ + id: "name", + label: "Full name", + placeholder: "First name and last name" + }, { + id: "age", + label: "Your age", + placeholder: "How old are you?", + optional: true, + + /* Validation method to make sure that age is above 18 */ + // highlight-start + validate: async (value) => { + if (parseInt(value) > 18) { + return undefined; // means that there is no error + } + return "You must be over 18 to register"; + } + // highlight-end + + }, { + id: "country", + label: "Your country", + placeholder: "Where do you live?", + optional: true + }] + } + } + }), + supertokensUISession.init() + ] +}); +``` + Here is what happens if someone tries to register with an age of 17: @@ -308,6 +361,48 @@ SuperTokens.init({ }); ``` + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailPassword.init({ + signInAndUpFeature: { + signUpForm: { + formFields: [{ + // highlight-start + id: "email", + label: "...", + validate: async (value) => { + // Your own validation returning a string or undefined if no errors. + return "..."; + } + }, { + id: "password", + label: "...", + validate: async (value) => { + // Your own validation returning a string or undefined if no errors. + return "..."; + } + // highlight-end + }] + } + } + }) + ] +}); +``` + diff --git a/v2/emailpassword/common-customizations/signup-form/toc-privacypolicy.mdx b/v2/emailpassword/common-customizations/signup-form/toc-privacypolicy.mdx index 1c413703e..6636eecda 100644 --- a/v2/emailpassword/common-customizations/signup-form/toc-privacypolicy.mdx +++ b/v2/emailpassword/common-customizations/signup-form/toc-privacypolicy.mdx @@ -2,19 +2,27 @@ id: toc-privacypolicy title: Terms of service & Privacy policy links hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" + + + +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Terms of service & Privacy policy links + + + You can provide a Privacy policy and Terms of service link which will render the following text on the sign up page: - Provided both links: "By signing up, you agree to our [Terms of Service](./toc-privacypolicy) and [Privacy Policy](./toc-privacypolicy)" - Provided only Terms of service link: "By signing up, you agree to our [Terms of Service](./toc-privacypolicy)" - Provided only Privacy policy link: "By signing up, you agree to our [Privacy Policy](./toc-privacypolicy)" - + ```tsx @@ -34,4 +42,36 @@ SuperTokens.init({ }); ``` - \ No newline at end of file + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + // highlight-start + termsOfServiceLink: "https://example.com/terms-of-service", + privacyPolicyLink: "https://example.com/privacy-policy", + // highlight-end + recipeList: [/* ... */] +}); +``` + + + + + + + +:::caution +Not applicable since you do not use our pre built UI. +::: + + + \ No newline at end of file diff --git a/v2/emailpassword/common-customizations/styling/changing-colours.mdx b/v2/emailpassword/common-customizations/styling/changing-colours.mdx index b9a8bdf33..5fda15c43 100644 --- a/v2/emailpassword/common-customizations/styling/changing-colours.mdx +++ b/v2/emailpassword/common-customizations/styling/changing-colours.mdx @@ -2,19 +2,24 @@ id: changing-colours title: Changing Colours hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Changing Colours + + + It is possible to update the default theme with your colours to make it fit perfectly with your website by defining a few css variables in the `style` property to the `EmailPassword.init` call. You have to specify the colors as RGB (see the following example), because we use the `rgb` and `rgba` functions to apply them. For example if your website uses a dark theme, here is how you can quickly customize it: - + ```tsx @@ -45,7 +50,39 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + // highlight-start + style: ` + [data-supertokens~=container] { + --palette-background: 51, 51, 51; + --palette-inputBackground: 41, 41, 41; + --palette-inputBorder: 41, 41, 41; + --palette-textTitle: 255, 255, 255; + --palette-textLabel: 255, 255, 255; + --palette-textPrimary: 255, 255, 255; + --palette-error: 173, 46, 46; + --palette-textInput: 169, 169, 169; + --palette-textLink: 169, 169, 169; + } + `, + // highlight-end + recipeList: [ /* ... */] +}); +``` + + Prebuilt form UI with custom color palette @@ -148,4 +185,14 @@ Changes to the palette will apply to all the UI components we provide. If you wa - Description: This value controls the color of the "Powered by SuperTokens" text on the bottom of sign-in/up pages - Default: ```173, 189, 196``` (heather grey) -Prebuilt form SuperTokens label \ No newline at end of file +Prebuilt form SuperTokens label + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/emailpassword/common-customizations/styling/changing-style.mdx b/v2/emailpassword/common-customizations/styling/changing-style.mdx index f62ad7147..d0ecf2d8e 100644 --- a/v2/emailpassword/common-customizations/styling/changing-style.mdx +++ b/v2/emailpassword/common-customizations/styling/changing-style.mdx @@ -2,13 +2,17 @@ id: changing-style title: Changing Style via CSS hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Changing Style via CSS + + Updating the CSS allows you to change the UI of our components to meet your needs. @@ -29,7 +33,7 @@ Each stylable components contains `data-supertokens` attributes (in our example Let's customize elements with the `button` attribute. The syntax for styling is plain CSS. - + ```tsx @@ -55,7 +59,34 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + // highlight-start + style: ` + [data-supertokens~=button] { + background-color: #252571; + border: 0px; + width: 30%; + margin: 0 auto; + } + `, + // highlight-end + recipeList: [ /* ... */] +}); +``` + + The above will result in: @@ -65,7 +96,7 @@ The above will result in: By default, SuperTokens uses the Arial font. The best way to override this is to add a `font-family` styling to the `container` component in the recipe configuration. - + ```tsx @@ -86,13 +117,35 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + style: ` + [data-supertokens~=container] { + font-family: cursive; + } + `, + recipeList: [ /* ... */] +}); +``` + + ### Using media queries You may want to have different CSS for different viewports. This can be achieved via media queries like this: - + ```tsx @@ -122,13 +175,44 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + style: ` + [data-supertokens~=button] { + background-color: #252571; + border: 0px; + width: 30%; + margin: 0 auto; + } + + @media (max-width: 440px) { + [data-supertokens~=button] { + width: 90%; + } + } + `, + recipeList: [ /* ... */], +}); +``` + + ## Customising the Sign-Up / Sign-In form These are the screens shown when the user tries to log in or sign up for the application. - + ```tsx @@ -147,7 +231,27 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + style: `[data-supertokens~=authPage] { + ... + }`, + recipeList: [ /* ... */] +}); +``` + + ## Customising the Password Reset forms @@ -155,7 +259,7 @@ SuperTokens.init({ This form is shown when the user clicks on "forgot password" in the sign in form. - + ```tsx @@ -184,13 +288,43 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + supertokensUIEmailPassword.init({ + // highlight-start + resetPasswordUsingTokenFeature: { + enterEmailForm: { + style: ` ... ` + } + } + // highlight-end + }), + supertokensUISession.init() + ] +}); +``` + + ### Submit new password form This screen is shown when the user clicks the password reset link on their email - to enter their new password - + ```tsx @@ -219,4 +353,44 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + supertokensUIEmailPassword.init({ + // highlight-start + resetPasswordUsingTokenFeature: { + submitNewPasswordForm: { + style: ` ... ` + } + } + // highlight-end + }), + supertokensUISession.init() + ] +}); +``` + + + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/emailpassword/common-customizations/styling/shadow-dom.mdx b/v2/emailpassword/common-customizations/styling/shadow-dom.mdx index d32a9e245..eb9077930 100644 --- a/v2/emailpassword/common-customizations/styling/shadow-dom.mdx +++ b/v2/emailpassword/common-customizations/styling/shadow-dom.mdx @@ -2,13 +2,21 @@ id: shadow-dom title: Disable use of shadow DOM hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" + + + +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Disable use of shadow DOM + + + We use [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) to prevent CSS clashes between your CSS and the ones we provide. This guarantees that all our UI will render as expected. However, this has a few problems: @@ -17,7 +25,7 @@ However, this has a few problems: If you want to disable use of shadow dom, you can do so like: - + ```tsx @@ -35,8 +43,37 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + // highlight-next-line + useShadowDom: false, + recipeList: [/* ... */] +}); +``` + + :::caution If disabled, please be sure to check that our components render correctly - because your CSS might affect our components' UI (the other way around won't happen). -::: \ No newline at end of file +::: + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/emailpassword/common-customizations/translations.mdx b/v2/emailpassword/common-customizations/translations.mdx index 00a3309be..48f9ef313 100644 --- a/v2/emailpassword/common-customizations/translations.mdx +++ b/v2/emailpassword/common-customizations/translations.mdx @@ -2,16 +2,19 @@ id: translations title: Language Translation for the UI hide_title: true +show_ui_switcher: true --- - - -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs"; +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; -import NpmOrScriptTabs from "/src/components/tabs/NpmOrScriptTabs" +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" + # Language Translation for the UI + + + You can translate the UI using two main methods: 1. You can override all displayed translation strings by providing translated versions for different languages (and even change the default English version). 2. You can provide a translation function to integrate supertokens with your preferred internationalization library. @@ -27,7 +30,7 @@ You can provide translations for each segment displayed in our UIs. - You can find the emailpassword login UI keys [here](https://github.com/supertokens/supertokens-auth-react/blob/master/lib/ts/recipe/emailpassword/components/themes/translations.ts). ::: - + ```tsx @@ -72,13 +75,58 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +supertokensUIInit({ + // highlight-start + languageTranslations: { // This object contains all translation related options + translations: { // These are the displayed translation strings for each language + // The property names define the language code of the translations + en: { + // Here each key is a translation key and the value is the string that will be displayed + // Setting the value to undefined will either display the translation from the default language or the translation key + BRANDING_POWERED_BY_START: "We ❤️ ", + // If you added a custom label or placeholder you can also provide translation for them if necessary + // You can also use these to provide translations for your component overrides + MY_CUSTOM_LABEL: "Age", + }, + hu: { + BRANDING_POWERED_BY_START: "Sok szeretettel: ", + // This key is associated with an empty string by default, but you can override these as well. + BRANDING_POWERED_BY_END: " 😊", + } + }, + /* + * This optional property sets the default and fallback language. + * It can be any string that will be used to fetch translations from the above object. + * Defaults to "en" + */ + defaultLanguage: "hu", + }, + // highlight-end + appInfo: { + appName: "...", + apiDomain: "...", + websiteDomain: "...", + }, + recipeList: [ + // ... + ], +}); +``` + + + ### Loading translations After initialization, you can provide additional translation data by calling the `SuperTokens.loadTranslation`. This can be useful if you are loading them asynchronously. - + ```tsx @@ -93,13 +141,26 @@ SuperTokens.loadTranslation({ }); ``` - + + +```tsx +import supertokensUI from "supertokens-auth-react-script"; +// This method takes an object as a parameter, which is structured the same as above. +// This will be merged into the existing definitions, so any properties missing here won't remove them from the already loaded translations +supertokensUI.loadTranslation({ + en: { + BRANDING_POWERED_BY_END: " :)", + } +}); +``` + + ### Changing the current language You can update which translations store is displayed by calling the `SuperTokens.changeLanguage`. - + ```tsx @@ -108,7 +169,14 @@ import SuperTokens from "supertokens-auth-react"; SuperTokens.changeLanguage("hu"); ``` - + + +```tsx +import supertokensUI from "supertokens-auth-react-script"; +supertokensUI.changeLanguage("hu"); +``` + + ## Using an internationalization library @@ -116,7 +184,7 @@ You can easily integrate SuperTokens with your internationalization library of c 1. Provide the translation function in `SuperTokens.init` - + ```tsx @@ -143,7 +211,32 @@ SuperTokens.init({ }); ``` - + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +supertokensUIInit({ + // highlight-start + languageTranslations: { + translationFunc: (key: string) => { + // The string returned by this function will be displayed + return key + "!"; + }, + }, + // highlight-end + appInfo: { + appName: "...", + apiDomain: "...", + websiteDomain: "...", + }, + recipeList: [ + // ... + ], +}); +``` + + 2. Call `SuperTokens.changeLanguage` or `SuperTokens.loadTranslation` to re-render the translated UI @@ -157,7 +250,7 @@ If the SDK can't find a segment in the current language's translation store, we The currently chosen language is stored in a cookie, this way it can be restored the next time the page loads. The domain of this cookie can be customized through the `currentLanguageCookieScope` option. This can be useful if you are running our SDK in multiple applications and want to share the language choice between sub-domains. - + ```tsx @@ -181,13 +274,35 @@ SuperTokens.init({ }); ``` - + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +supertokensUIInit({ + // highlight-start + languageTranslations: { + currentLanguageCookieScope: ".example.com", + }, + // highlight-end + appInfo: { + appName: "...", + apiDomain: "...", + websiteDomain: "...", + }, + recipeList: [ + // ... + ], +}); +``` + + ## Translations in component overrides The SDK also exports the `useTranslation` React hook you can use while overriding components. It returns a function that takes a translation segment key and returns it translated to the currently selected language. For more information on what translation keys you should use and the exact syntax, please see the original source code of the component you are overriding. - + ```tsx @@ -207,4 +322,22 @@ export const HeaderOverride = () => { ``` - + + +:::caution +Not applicable for non react apps. +::: + + + + + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/emailpassword/pre-built-ui/auth-redirection.mdx b/v2/emailpassword/pre-built-ui/auth-redirection.mdx index 1d9265bda..e93c3f38b 100644 --- a/v2/emailpassword/pre-built-ui/auth-redirection.mdx +++ b/v2/emailpassword/pre-built-ui/auth-redirection.mdx @@ -50,6 +50,47 @@ SuperTokens.init({ }); ``` + + + + +By default, the user is redirected the the `/` route on your website post login. To change this, you can use the `getRedirectionURL` function on the frontend as shown below: + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + // highlight-start + getRedirectionURL: async (context) => { + if (context.action === "SUCCESS" && context.newSessionCreated) { + if (context.redirectToPath !== undefined) { + // we are navigating back to where the user was before they authenticated + return context.redirectToPath; + } + if (context.createdNewUser) { + // user signed up + } else { + // user signed in + } + return "/dashboard"; + } + return undefined; + }, + // highlight-end + recipeList: [ /* Recipe list */] +}); +``` + + + + + The user will be redirected to the provided URL on: - Successful sign up. - Successful sign in. @@ -62,9 +103,6 @@ If you want to redirect the user to a different domain, then you can do so by fi Please refer to [this page](../advanced-customizations/frontend-hooks/redirection-callback) to learn more about the `getRedirectionURL` hook. ::: - - - ## Redirect user to the login page @@ -100,12 +138,10 @@ function NavBar () { -Use the `redirectToAuth({show?: "signin" | "signup", redirectBack?: boolean}?)` function to redirect the user to the login screen. For example, you may want to call this function when the user clicks on the login button. +Redirect the user to the `/auth` (this is the default path for the pre built UI) ```ts import { Component } from "@angular/core"; -// highlight-next-line -import { redirectToAuth } from "supertokens-auth-react"; @Component({ selector: 'nav-bar', @@ -120,20 +156,20 @@ import { redirectToAuth } from "supertokens-auth-react"; export class NavBarComponent { async onLogin () { // highlight-next-line - redirectToAuth(); + window.location.href = "/auth?show=signin&redirecToPath=" + encodeURIComponent(window.location.pathname); } } ``` -- Call `redirectToAuth({show: "signin"})` to take them to the sign in screen -- Call `redirectToAuth({show: "signup"})` to take them to the sign up screen -- If you do not want the user to be redirected to the current page post sign in, use `redirectToAuth({redirectBack: false})` +- Set `show=signin` to take them to the sign in screen +- Set `show=signup` to take them to the sign up screen +- Set `redirecToPath` to redirect the user to a specific page after they have signed in, or you can skip it to take them to the `/` route (which is the default one). -Use the `redirectToAuth({show?: "signin" | "signup", redirectBack?: boolean}?)` function to redirect the user to the login screen. For example, you may want to call this function when the user clicks on the login button. +Redirect the user to the `/auth` (this is the default path for the pre built UI) ```html ``` -- Call `redirectToAuth({show: "signin"})` to take them to the sign in screen -- Call `redirectToAuth({show: "signup"})` to take them to the sign up screen -- If you do not want the user to be redirected to the current page post sign in, use `redirectToAuth({redirectBack: false})` +- Set `show=signin` to take them to the sign in screen +- Set `show=signup` to take them to the sign up screen +- Set `redirecToPath` to redirect the user to a specific page after they have signed in, or you can skip it to take them to the `/` route (which is the default one). @@ -195,6 +229,26 @@ SuperTokens.init({ }); ``` + + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + // highlight-next-line + defaultToSignUp: true, + recipeList: [ /* ... */] +}); +``` + diff --git a/v2/emailpassword/pre-built-ui/enable-email-verification.mdx b/v2/emailpassword/pre-built-ui/enable-email-verification.mdx index 9d216fed5..75f90ad35 100644 --- a/v2/emailpassword/pre-built-ui/enable-email-verification.mdx +++ b/v2/emailpassword/pre-built-ui/enable-email-verification.mdx @@ -209,6 +209,33 @@ function App() { + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + // highlight-start + supertokensUIEmailVerification.init({ + mode: "REQUIRED", // or "OPTIONAL" + }), + // highlight-end + supertokensUISession.init(), + ], +}); +``` + + + @@ -732,8 +759,8 @@ If all validations pass, we render the `props.children` component. ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { EmailVerificationClaim } from "supertokens-auth-react/recipe/emailverification"; +import Session from "supertokens-web-js/recipe/session"; +import { EmailVerificationClaim } from "supertokens-web-js/recipe/emailverification"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { diff --git a/v2/emailpassword/pre-built-ui/handling-session-tokens.mdx b/v2/emailpassword/pre-built-ui/handling-session-tokens.mdx index 6d37e05ca..11f2460fa 100644 --- a/v2/emailpassword/pre-built-ui/handling-session-tokens.mdx +++ b/v2/emailpassword/pre-built-ui/handling-session-tokens.mdx @@ -61,7 +61,15 @@ async function getToken(): Promise { -~COPY-TABS=reactjs +```tsx +import Session from "supertokens-web-js/recipe/session"; + +async function getToken(): Promise { + // highlight-next-line + const accessToken = await Session.getAccessToken(); + console.log(accessToken); +} +``` diff --git a/v2/emailpassword/pre-built-ui/securing-routes.mdx b/v2/emailpassword/pre-built-ui/securing-routes.mdx index 4df26e055..22d56941e 100644 --- a/v2/emailpassword/pre-built-ui/securing-routes.mdx +++ b/v2/emailpassword/pre-built-ui/securing-routes.mdx @@ -490,7 +490,7 @@ class App extends React.Component { You can use the `doesSessionExist` function to check if a session exists in all your routes. ```tsx -import Session from 'supertokens-auth-react/recipe/session'; +import Session from 'supertokens-web-js/recipe/session'; async function doesSessionExist() { if (await Session.doesSessionExist()) { diff --git a/v2/emailpassword/pre-built-ui/setup/frontend.mdx b/v2/emailpassword/pre-built-ui/setup/frontend.mdx index efc7c044d..3cfc4901e 100644 --- a/v2/emailpassword/pre-built-ui/setup/frontend.mdx +++ b/v2/emailpassword/pre-built-ui/setup/frontend.mdx @@ -14,6 +14,7 @@ import {Question, Answer}from "/src/components/question" import AppInfoForm from "/src/components/appInfoForm" import RRDVersionSubTabs from "/src/components/tabs/RRDVersionSubTabs" import NpmVersionOrYarnSubTabs from "/src/components/tabs/NpmVersionOrYarnSubTabs" +import PreBuiltUIInjector from "/src/components/prebuiltuiInjector" # Frontend Integration @@ -71,58 +72,35 @@ yarn add supertokens-auth-react supertokens-web-js -:::important -SuperTokens does not provide Angular components for pre built UI, but, there are two ways of implementing SuperTokens in your Angular frontend: -- Load SuperTokens's pre-built React UI components in your Angular app. Continue following the guide for this flow. -- Build your own UI. Click [here](../../custom-ui/init/frontend) to learn more. -::: - -Start by installing the SuperTokens ReactJS SDK and React: +Start by installing the SuperTokens Web SDK: ```bash -npm i -s supertokens-auth-react +npm i -s supertokens-web-js ``` -:::important -SuperTokens does not provide Angular components for pre built UI, but, there are two ways of implementing SuperTokens in your Angular frontend: -- Load SuperTokens's pre-built React UI components in your Angular app. Continue following the guide for this flow. -- Build your own UI. Click [here](../../custom-ui/init/frontend) to learn more. -::: -Start by installing the SuperTokens ReactJS SDK and React: +Start by installing the SuperTokens Web SDK: ```bash -npm i -s supertokens-auth-react supertokens-web-js +npm i -s supertokens-web-js ``` -:::important -SuperTokens does not provide Angular components for pre built UI, but, there are two ways of implementing SuperTokens in your Angular frontend: -- Load SuperTokens's pre-built React UI components in your Angular app. Continue following the guide for this flow. -- Build your own UI. Click [here](../../custom-ui/init/frontend) to learn more. -::: -Start by installing the SuperTokens ReactJS SDK and React: +Start by installing the SuperTokens Web SDK: ```bash -yarn add supertokens-auth-react supertokens-web-js +yarn add supertokens-web-js ``` -You will also need to update `compilerOptions` in your `tsconfig.json` file with the following: - -```json title="tsconfig.json" -"jsx": "react", -"allowSyntheticDefaultImports": true, -``` - @@ -130,46 +108,30 @@ You will also need to update `compilerOptions` in your `tsconfig.json` file with -:::important -SuperTokens does not provide Vue components for pre built UI, but, there are two ways of implementing SuperTokens in your Vue frontend: -- Load SuperTokens's pre-built React UI components in your Vue app. Continue following the guide for this flow. -- Build your own UI. Click [here](../../custom-ui/init/frontend) to learn more. -::: - -Start by installing the SuperTokens ReactJS SDK and React: +Start by installing the SuperTokens web SDK: ```bash -npm i -s supertokens-auth-react +npm i -s supertokens-web-js ``` -:::important -SuperTokens does not provide Vue components for pre built UI, but, there are two ways of implementing SuperTokens in your Vue frontend: -- Load SuperTokens's pre-built React UI components in your Vue app. Continue following the guide for this flow. -- Build your own UI. Click [here](../../custom-ui/init/frontend) to learn more. -::: -Start by installing the SuperTokens ReactJS SDK and React: +Start by installing the SuperTokens web SDK: ```bash -npm i -s supertokens-auth-react supertokens-web-js +npm i -s supertokens-web-js ``` -:::important -SuperTokens does not provide Vue components for pre built UI, but, there are two ways of implementing SuperTokens in your Vue frontend: -- Load SuperTokens's pre-built React UI components in your Vue app. Continue following the guide for this flow. -- Build your own UI. Click [here](../../custom-ui/init/frontend) to learn more. -::: -Start by installing the SuperTokens ReactJS SDK and React: +Start by installing the SuperTokens web SDK: ```bash -yarn add supertokens-auth-react supertokens-web-js +yarn add supertokens-web-js ``` @@ -252,12 +214,14 @@ class App extends React.Component { askForAPIDomain askForWebsiteDomain> -Before we initialize the `supertokens-auth-react` SDK let's see how we will use it in our Angular app + + +Before we initialize the `supertokens-web-js` SDK let's see how we will use it in our Angular app **Architecture** -- The `supertokens-auth-react` SDK is responsible for rendering the login UI, handling authentication flows and session management. -- Using `supertokens-auth-react`'s pre-built UI does not increase application's bundle size. React is only added to authentication-related routes. +- The `supertokens-web-js` SDK is responsible for session management and providing helper functions to check if a session exists, or validate the access token claims on the frontend (for example, to check for user roles before showing some UI). We will initialise this SDK on the root of your Angular app, so that all pages in your app can use it. +- We will create a `^{form_websiteBasePath}*` route in the Angular app which will render our pre built UI which will also need to be initialised, but only on that route. **Creating the `^{form_websiteBasePath}` route** @@ -267,94 +231,84 @@ Before we initialize the `supertokens-auth-react` SDK let's see how we will use ng generate module auth --route auth --module app.module ``` -- In your `auth` component folder create a react component `supertokensAuthComponent.tsx`. This component will be used to render appropriate UI when user visits the login page. - - ```tsx title="/app/auth/supertokensAuthComponent.tsx" - import * as React from "react"; - import * as SuperTokens from "supertokens-auth-react"; - import { canHandleRoute, getRoutingComponent } from "supertokens-auth-react/ui"; - ^{prebuiltuiimport} - - // highlight-start - class SuperTokensReactComponent extends React.Component { - override render() { - if (canHandleRoute([^{recipePreBuiltUINameCapitalLetters}])) { - return getRoutingComponent([^{recipePreBuiltUINameCapitalLetters}]); - } - return "Route not found"; - } - } - // highlight-end - - export default SuperTokensReactComponent; - ``` - -- Load `superTokensAuthComponent` in the `auth` angular component +- Add the following code to your `auth` angular component ```tsx title="/app/auth/auth.component.ts" - import { AfterViewInit, Component, OnDestroy } from "@angular/core"; - import * as React from "react"; - import * as ReactDOM from "react-dom"; - // @ts-ignore - import SuperTokensReactComponent from "./supertokensAuthComponent.tsx"; + import {init as supertokensUIInit} from "supertokens-auth-react-script"; + import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; + import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + import { Component, OnDestroy, AfterViewInit, Renderer2, Inject } from "@angular/core"; + import { DOCUMENT } from "@angular/common"; @Component({ selector: "app-auth", - template: '
', + template: '
', }) - export class AuthComponent implements AfterViewInit, OnDestroy { - title = "angularreactapp"; + export class AuthComponent implements OnDestroy, AfterViewInit { - public rootId = "rootId"; + constructor( + private renderer: Renderer2, + @Inject(DOCUMENT) private document: Document + ) { } - // highlight-start - // We use the ngAfterViewInit lifecycle hook to render the React component after the Angular component view gets initialized ngAfterViewInit() { - ReactDOM.render(React.createElement(SuperTokensReactComponent), document.getElementById(this.rootId)); + this.loadScript('^{jsdeliver_prebuiltui}'); } - // We use the ngOnDestroy lifecycle hook to unmount the React component when the Angular wrapper component is destroyed. ngOnDestroy() { - ReactDOM.unmountComponentAtNode(document.getElementById(this.rootId) as Element); + // Remove the script when the component is destroyed + const script = this.document.getElementById('supertokens-script'); + if (script) { + script.remove(); + } + } + + private loadScript(src: string) { + const script = this.renderer.createElement('script'); + script.type = 'text/javascript'; + script.src = src; + script.id = 'supertokens-script'; + script.onload = () => { + supertokensUIInit({ + appInfo: { + appName: "^{form_appName}", + apiDomain: "^{form_apiDomain}", + websiteDomain: "^{form_websiteDomain}", + apiBasePath: "^{form_apiBasePath}", + websiteBasePath: "^{form_websiteBasePath}" + }, + recipeList: [ + supertokensUIEmailPassword.init(), + supertokensUISession.init(), + ], + }); + } + this.renderer.appendChild(this.document.body, script); } - // highlight-end } ``` + - In the `loadScript` function, we provide the SuperTokens config for the UI. We add the emailpassword and session recipe. -- Initialize the `supertokens-auth-react` SDK in your angular app's root component. This will provide session management across your entire application. - - ```tsx title="/app/app.component.ts " - import { Component } from "@angular/core"; - - import * as SuperTokens from "supertokens-auth-react"; - import * as EmailPassword from "supertokens-auth-react/recipe/emailpassword"; - import Session from "supertokens-auth-react/recipe/session"; +- Initialize the `supertokens-web-js` SDK in your angular app's root component. This will provide session management across your entire application. + ```tsx title="/app/app.component.ts " + import SuperTokens from "supertokens-web-js"; + import Session from "supertokens-web-js/recipe/session"; + SuperTokens.init({ - // highlight-start appInfo: { appName: "^{form_appName}", apiDomain: "^{form_apiDomain}", - websiteDomain: "^{form_websiteDomain}", apiBasePath: "^{form_apiBasePath}", - websiteBasePath: "^{form_websiteBasePath}" }, recipeList: [ - EmailPassword.init(), Session.init(), ], - // highlight-end }); - - @Component({ - selector: "app-root", - template: "", - }) - export class AppComponent { - title = "^{form_appName}"; - } ``` + + @@ -366,87 +320,90 @@ Before we initialize the `supertokens-auth-react` SDK let's see how we will use askForAPIDomain askForWebsiteDomain> -Before we initialize the `supertokens-auth-react` SDK let's see how we will use it in our Vue app + + +Before we initialize the `supertokens-web-js` SDK let's see how we will use it in our Vue app **Architecture** -- The `supertokens-auth-react` SDK is responsible for rendering the login UI, handling authentication flows and session management. -- Using `supertokens-auth-react`'s pre-built UI does not increase application's bundle size. React is only added to authentication-related routes. +- The `supertokens-web-js` SDK is responsible for session management and providing helper functions to check if a session exists, or validate the access token claims on the frontend (for example, to check for user roles before showing some UI). We will initialise this SDK on the root of your Vue app, so that all pages in your app can use it. +- We will create a `^{form_websiteBasePath}*` route in the Vue app which will render our pre built UI which will also need to be initialised, but only on that route. **Creating the `^{form_websiteBasePath}` route** -- Create a new file `AuthView.vue`, this Vue component will be used to render the auth component - -- Create a React component `Supertokens.tsx`. This will tell SuperTokens which UI to show when the user visits the login page. - - ```tsx title="/components/Supertokens.tsx" - import * as SuperTokens from "supertokens-auth-react"; - import { canHandleRoute, getRoutingComponent } from "supertokens-auth-react/ui"; - ^{prebuiltuiimport} - - // highlight-start - function SuperTokensReactComponent(props: any) { - if (canHandleRoute([^{recipePreBuiltUINameCapitalLetters}])) { - return getRoutingComponent([^{recipePreBuiltUINameCapitalLetters}]); - } - return "Route not found"; - } - // highlight-end - - export default SuperTokensReactComponent; - ``` - -- Load `SuperTokensReactComponent` in the `AuthView.vue` component - - ```html title="/views/AuthView.vue" +- Create a new file `AuthView.vue`, this Vue component will be used to render the auth component: + ```tsx + import {init as supertokensUIInit} from "supertokens-auth-react-script"; + import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; + import supertokensUISession from "supertokens-auth-react-script/recipe/session"; ``` + - In the `loadScript` function, we provide the SuperTokens config for the UI. We add the emailpassword and session recipe. -- Initialize the `supertokens-auth-react` SDK in your Vue app's `main.ts` file. This will provide session management across your entire application. +- Initialize the `supertokens-web-js` SDK in your Vue app's `main.ts` file. This will provide session management across your entire application. ```tsx title="/main.ts " // @ts-ignore import { createApp } from "vue"; - import * as SuperTokens from "supertokens-auth-react"; - import * as EmailPassword from "supertokens-auth-react/recipe/emailpassword"; - import Session from "supertokens-auth-react/recipe/session"; + import SuperTokens from "supertokens-web-js"; + import Session from "supertokens-web-js/recipe/session"; // @ts-ignore import App from "./App.vue"; // @ts-ignore import router from "./router"; SuperTokens.init({ - // highlight-start appInfo: { appName: "^{form_appName}", apiDomain: "^{form_apiDomain}", - websiteDomain: "^{form_websiteDomain}", apiBasePath: "^{form_apiBasePath}", - websiteBasePath: "^{form_websiteBasePath}" }, recipeList: [ - EmailPassword.init(), Session.init(), - ] - // highlight-end + ], }); const app = createApp(App); @@ -457,6 +414,8 @@ Before we initialize the `supertokens-auth-react` SDK let's see how we will use ``` + + @@ -646,6 +605,8 @@ Update your Vue router so that all auth related requests load the `AuthView` com import { createRouter, createWebHistory } from "vue-router"; // @ts-ignore import HomeView from "../views/HomeView.vue"; +// @ts-ignore +import AuthView from "../views/AuthView.vue"; const router = createRouter({ // @ts-ignore @@ -659,8 +620,7 @@ const router = createRouter({ { path: "^{form_websiteBasePath}/:pathMatch(.*)*", name: "auth", - // @ts-ignore - component: () => import("../views/AuthView.vue"), + component: AuthView, }, ], }); diff --git a/v2/emailpassword/pre-built-ui/sign-out.mdx b/v2/emailpassword/pre-built-ui/sign-out.mdx index 8b25a1f07..799748faa 100644 --- a/v2/emailpassword/pre-built-ui/sign-out.mdx +++ b/v2/emailpassword/pre-built-ui/sign-out.mdx @@ -42,11 +42,11 @@ function NavBar() { -The [`signOut` method](https://supertokens.com/docs/auth-react/modules/recipe_session.html#signOut-1) revokes the session for the user. +The [`signOut` method](https://supertokens.com/docs/web-js/modules/recipe_session.html#signOut-1) revokes the session for the user. ```tsx // highlight-next-line -import Session from "supertokens-auth-react/recipe/session"; +import Session from "supertokens-web-js/recipe/session"; async function logout () { // highlight-next-line diff --git a/v2/emailpassword/troubleshooting/how-to-troubleshoot.mdx b/v2/emailpassword/troubleshooting/how-to-troubleshoot.mdx index 41507a865..901aaa4d7 100644 --- a/v2/emailpassword/troubleshooting/how-to-troubleshoot.mdx +++ b/v2/emailpassword/troubleshooting/how-to-troubleshoot.mdx @@ -132,6 +132,45 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + // highlight-next-line + enableDebugLogs: true, + // @ts-ignore + appInfo: { /*...*/ }, + // @ts-ignore + recipeList: [/*...*/] +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from 'supertokens-web-js'; +import Session from 'supertokens-web-js/recipe/session'; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + Session.init(), + ], + // highlight-next-line + enableDebugLogs: true, +}); +``` + + + diff --git a/v2/emailpassword/user-roles/protecting-routes.mdx b/v2/emailpassword/user-roles/protecting-routes.mdx index b3ea9478d..58c95e15f 100644 --- a/v2/emailpassword/user-roles/protecting-routes.mdx +++ b/v2/emailpassword/user-roles/protecting-routes.mdx @@ -1224,8 +1224,8 @@ function ProtectedComponent() { ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { @@ -1268,8 +1268,8 @@ async function shouldLoadRoute(): Promise { If you want to have more complex access control, you can get the roles list from the session as follows, and check the list yourself: ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { diff --git a/v2/mfa/email-sms-otp/embed.mdx b/v2/mfa/email-sms-otp/embed.mdx index c1d257169..b07fa27ab 100644 --- a/v2/mfa/email-sms-otp/embed.mdx +++ b/v2/mfa/email-sms-otp/embed.mdx @@ -17,6 +17,9 @@ import RRDVersionSubTabs from "/src/components/tabs/RRDVersionSubTabs" + + + :::important The snippets below assume that you are using the Passwordless recipe for Email / SMS OTP. But if you are using ThirdPartyPasswordless, that works as well. ::: @@ -25,8 +28,6 @@ The snippets below assume that you are using the Passwordless recipe for Email / The following example shows the scenario where you have a dedicated route, such as `/otp`, for rendering the Email / SMS OTP Widget. Upon a successful login, the user will be automatically redirected to the return value of `getRedirectionURL` (defaulting to `/`). - - @@ -213,8 +214,6 @@ function OTPPage() { ``` - - In the above code snippet, we: @@ -228,8 +227,6 @@ Feel free to customize the redirection URLs as needed. The following example shows the scenario where you embed the Email / SMS OTP Widget in a popup, and upon successful login, you aim to close the popup. This is especially useful for step up auth. - - @@ -374,11 +371,20 @@ history ``` - - The above snippet uses `MfaOtpEmail` for otp-email factor, but if you are using `otp-phone`, then you can use the `MfaOtpPhone` component. Be sure to also change the `contactMethod` prop in Passwordless.init to use `PHONE` or `EMAIL_OR_PHONE`, depending on if you are using emial otp / link as the first factor or not. + + + + +:::caution +Not applicable to non-react apps. Please build your own custom UI instead. +::: + + + + diff --git a/v2/mfa/email-sms-otp/otp-for-all-users.mdx b/v2/mfa/email-sms-otp/otp-for-all-users.mdx index f6a039f19..4f5a9410f 100644 --- a/v2/mfa/email-sms-otp/otp-for-all-users.mdx +++ b/v2/mfa/email-sms-otp/otp-for-all-users.mdx @@ -224,6 +224,69 @@ supertokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIThirdParty from "supertokens-auth-react-script/recipe/thirdparty" +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword" +import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless" +import supertokensUIMultiFactorAuth from "supertokens-auth-react-script/recipe/multifactorauth" + +supertokensUIInit({ + appInfo: { + appName: "...", + apiDomain: "...", + websiteDomain: "...", + }, + recipeList: [ + supertokensUIThirdParty.init(/* ... */), + supertokensUIEmailPassword.init( /* ... */), + // highlight-start + supertokensUIPasswordless.init({ + contactMethod: "EMAIL" + }), + supertokensUIMultiFactorAuth.init({ + firstFactors: [ + supertokensUIMultiFactorAuth.FactorIds.EMAILPASSWORD, + supertokensUIMultiFactorAuth.FactorIds.THIRDPARTY + ] + }) + // highlight-end + ] +}) +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from 'supertokens-web-js'; +import MultiFactorAuth from 'supertokens-web-js/recipe/multifactorauth'; +import Passwordless from "supertokens-web-js/recipe/passwordless"; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + apiBasePath: "...", + appName: "...", + }, + recipeList: [ + // other recipes... + // highlight-start + MultiFactorAuth.init(), + Passwordless.init() + // highlight-end + ], +}); +``` + + + - Just like on the backend, we init the `passwordless` recipe in the `recipeList`. The `contactMethod` needs to be consistent with the backend setting. @@ -298,6 +361,14 @@ function App() { + + +:::success +This step is not required for non React apps, since all the pre built UI components are already added into the bundle. +::: + + + With the above configuration, users will see emailpassword or social login UI when they visit the auth page. After completing that, users will be redirected to `/auth/mfa/otp-email` (assuming that the `websiteBasePath` is `/auth`) where they will be asked to complete the OTP challenge. The UI for this screen looks like: @@ -676,6 +747,82 @@ supertokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIThirdParty from "supertokens-auth-react-script/recipe/thirdparty" +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword" +import supertokensUIMultiFactorAuth from "supertokens-auth-react-script/recipe/multifactorauth" +import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless" +import supertokensUIMultitenancy from "supertokens-auth-react-script/recipe/multitenancy" + +supertokensUIInit({ + appInfo: { + appName: "...", + apiDomain: "...", + websiteDomain: "...", + }, + // highlight-next-line + usesDynamicLoginMethods: true, + recipeList: [ + supertokensUIThirdParty.init({ + //... + }), + supertokensUIEmailPassword.init({ + //... + }), + // highlight-start + supertokensUIPasswordless.init({ + contactMethod: "EMAIL" + }), + supertokensUIMultiFactorAuth.init(), + supertokensUIMultitenancy.init({ + override: { + functions: (originalImplementation) => { + return { + ...originalImplementation, + getTenantId: async (context) => { + return "TODO" + } + } + } + } + }) + // highlight-end + ] +}) +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import supertokens from "supertokens-web-js-script"; +import MultiFactorAuth from 'supertokens-web-js-script/recipe/multifactorauth'; +import Session from "supertokens-web-js-script/recipe/session"; + +supertokens.init({ + appInfo: { + apiDomain: "...", + apiBasePath: "...", + appName: "...", + }, + recipeList: [ + // highlight-start + Session.init(), + MultiFactorAuth.init(), + // highlight-end + ], +}); +``` + + + - Just like on the backend, we init the `Passwordless` recipe in the `recipeList`. Make sure that the config for it is consistent with whats on the backend. @@ -752,6 +899,14 @@ function App() { + + +:::success +This step is not required for non React apps, since all the pre built UI components are already added into the bundle. +::: + + + With the above configuration, users will see the first and second factor based on the tenant configuration. For the tenant we configured above, users will see email password or social login first. After completing that, users will be redirected to `/auth/mfa/otp-email` (assuming that the `websiteBasePath` is `/auth`) where they will be asked complete the OTP challenge. The UI for this screen looks like: diff --git a/v2/mfa/frontend-setup.mdx b/v2/mfa/frontend-setup.mdx index 1fa4cbb5b..4dc9f5c50 100644 --- a/v2/mfa/frontend-setup.mdx +++ b/v2/mfa/frontend-setup.mdx @@ -69,6 +69,64 @@ supertokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword" +import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless" +import supertokensUIMultiFactorAuth from "supertokens-auth-react-script/recipe/multifactorauth" + +supertokensUIInit({ + appInfo: { + appName: "...", + apiDomain: "...", + websiteDomain: "...", + }, + recipeList: [ + supertokensUIEmailPassword.init( /* ... */), + supertokensUIPasswordless.init({ + contactMethod: "EMAIL_OR_PHONE", + }), + // highlight-start + supertokensUIMultiFactorAuth.init({ + firstFactors: [ + supertokensUIMultiFactorAuth.FactorIds.EMAILPASSWORD, + supertokensUIMultiFactorAuth.FactorIds.THIRDPARTY + ] + }) + // highlight-end + ] +}) +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from 'supertokens-web-js'; +import MultiFactorAuth from 'supertokens-web-js/recipe/multifactorauth'; +import Session from 'supertokens-web-js/recipe/session' + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + apiBasePath: "...", + appName: "...", + }, + recipeList: [ + Session.init(), + MultiFactorAuth.init() + ], +}); +``` + + + In the above snippet, we have configured thirdparty and email password as first factors. The second factor is configured [on the backend](./backend-setup), and is determined based on the boolean value of [`v` in the MFA claim in the session](./important-concepts#how-are-auth-factors-marked-as-completed). If the `v` is `false` in the session, it means that there are still factors pending before the user has completed login. In this case, the frontend SDK calls the MFAInfo endpoint (see more about this later) on the backend which returns the list of factors (`string[]`) that the user must complete next. For example: @@ -138,6 +196,78 @@ supertokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword" +import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless" +import supertokensUIMultiFactorAuth from "supertokens-auth-react-script/recipe/multifactorauth" +import supertokensUIMultitenancy from "supertokens-auth-react-script/recipe/multitenancy" + +supertokensUIInit({ + appInfo: { + appName: "...", + apiDomain: "...", + websiteDomain: "...", + }, + // highlight-next-line + usesDynamicLoginMethods: true, + recipeList: [ + supertokensUIMultitenancy.init({ + override: { + functions: (oI) => { + return { + ...oI, + // highlight-start + getTenantId: (input) => { + // Implement the following based on the UX flow you want for + // tenant discovery + return "TODO.." + } + // highlight-end + } + } + } + }), + supertokensUIEmailPassword.init( /* ... */), + supertokensUIPasswordless.init({ + contactMethod: "EMAIL_OR_PHONE", + }), + // highlight-start + supertokensUIMultiFactorAuth.init() + // highlight-end + ] +}) +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from 'supertokens-web-js'; +import MultiFactorAuth from 'supertokens-web-js/recipe/multifactorauth'; +import Session from 'supertokens-web-js/recipe/session' + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + apiBasePath: "...", + appName: "...", + }, + recipeList: [ + Session.init(), + MultiFactorAuth.init() + ], +}); +``` + + + - In the above code snippet, we have added `ThirdPartyEmailPassword` and `Passwordless` as the auth methods. This works for a variety of use cases like: @@ -253,6 +383,14 @@ export default App; + + +:::caution +You cannot override the pre built UI in non react apps as of yet. +::: + + + @@ -772,6 +910,64 @@ SuperTokens.init({ + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIMultiFactorAuth from "supertokens-auth-react-script/recipe/multifactorauth" +import supertokensUITOTP from "supertokens-auth-react-script/recipe/totp"; +import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless"; + +supertokensUIInit({ + appInfo: { + appName: "...", + apiDomain: "...", + websiteDomain: "...", + }, + recipeList: [ + supertokensUIPasswordless.init({ + contactMethod: "EMAIL_OR_PHONE", + onHandleEvent: (context) => { + if (context.action === "PASSWORDLESS_CODE_SENT") { + // this event is fired when the user has successfully sent out an OTP email / SMS + } else if (context.action === "PASSWORDLESS_RESTART_FLOW") { + // This event is fired when the user's OTP has expired, or + // they have reached the max limit of number of failed OTP attempts. + } else if (context.action === "SUCCESS" && !context.createdNewSession) { + // this event is fired when successfully completing the OTP email / SMS challenge + // and if it's not used in first factor (cause we do !context.createdNewSession) + } + } + }), + supertokensUITOTP.init({ + onHandleEvent: (context) => { + if (context.action === "TOTP_DEVICE_CREATED") { + // this event is fired during factor setup, when the user has successfully created the TOTP device. They still have to verify it by entering the TOTP. + } else if (context.action === "TOTP_DEVICE_VERIFIED") { + // this event is fired during factor setup, when the user has successfully verified the TOTP device + } else if (context.action === "TOTP_CODE_VERIFIED") { + // this event is fired when the user has successfully verified the TOTP code + // marking the TOTP factor as completed + } + } + }), + supertokensUIMultiFactorAuth.init({ + firstFactors: [/*...*/], + onHandleEvent: (context) => { + if (context.action === "FACTOR_CHOOSEN") { + let chosenFactorId = context.factorId; + // this event is fired when the user is shown the screen for + // picking one factor out of a choice of multiple factors + } + } + }) + ] +}) +``` + + + diff --git a/v2/mfa/totp/embed.mdx b/v2/mfa/totp/embed.mdx index ec2904d94..40c91c47e 100644 --- a/v2/mfa/totp/embed.mdx +++ b/v2/mfa/totp/embed.mdx @@ -17,12 +17,13 @@ import RRDVersionSubTabs from "/src/components/tabs/RRDVersionSubTabs" + + + ## Case 1: Rendering the TOTP Widget in a page The following example shows the scenario where you have a dedicated route, such as `/totp`, for rendering the TOTP Widget. Upon a successful login, the user will be automatically redirected to the return value of `getRedirectionURL` (defaulting to `/`). - - @@ -200,8 +201,6 @@ function TOTPPage() { ``` - - In the above code snippet, we: @@ -214,8 +213,6 @@ Feel free to customize the redirection URLs as needed. The following example shows the scenario where you embed the TOTP Widget in a popup, and upon successful login, you aim to close the popup. This is especially useful for step up auth. - - @@ -412,6 +409,15 @@ function TOTPPopup() { + + + +:::caution +Not applicable to non-react apps. Please build your own custom UI instead. +::: + + + diff --git a/v2/mfa/totp/totp-for-all-users.mdx b/v2/mfa/totp/totp-for-all-users.mdx index a539e28da..27dafe1ef 100644 --- a/v2/mfa/totp/totp-for-all-users.mdx +++ b/v2/mfa/totp/totp-for-all-users.mdx @@ -178,6 +178,64 @@ supertokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless" +import supertokensUIMultiFactorAuth from "supertokens-auth-react-script/recipe/multifactorauth" +import supertokensUITOTP from "supertokens-auth-react-script/recipe/totp" +supertokensUIInit({ + appInfo: { + appName: "...", + apiDomain: "...", + websiteDomain: "...", + }, + recipeList: [ + // other recipes.. + // highlight-start + supertokensUITOTP.init(), + supertokensUIMultiFactorAuth.init({ + firstFactors: [ + supertokensUIMultiFactorAuth.FactorIds.EMAILPASSWORD, + supertokensUIMultiFactorAuth.FactorIds.THIRDPARTY + ] + }) + // highlight-end + ] +}) +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from 'supertokens-web-js'; +import MultiFactorAuth from 'supertokens-web-js/recipe/multifactorauth'; +import Totp from "supertokens-web-js/recipe/totp"; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + apiBasePath: "...", + appName: "...", + }, + recipeList: [ + // other recipes... + // highlight-start + MultiFactorAuth.init(), + Totp.init() + // highlight-end + ], +}); +``` + + + - Just like on the backend, we init the `totp` recipe in the `recipeList`. @@ -248,6 +306,14 @@ function App() { + + +:::success +This step is not required for non React apps, since all the pre built UI components are already added into the bundle. +::: + + + With the above configuration, users will see emailpassword or social login UI when they visit the auth page. After completing that, users will be redirected to `/auth/mfa/totp` (assuming that the `websiteBasePath` is `/auth`) where they will be asked to setup the factor, or complete the TOTP challenge if they have already setup the factor before. The UI for this screen looks like: @@ -959,6 +1025,73 @@ supertokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIMultiFactorAuth from "supertokens-auth-react-script/recipe/multifactorauth" +import supertokensUITOTP from "supertokens-auth-react-script/recipe/totp" +import supertokensUIMultitenancy from "supertokens-auth-react-script/recipe/multitenancy" + +supertokensUIInit({ + appInfo: { + appName: "...", + apiDomain: "...", + websiteDomain: "...", + }, + // highlight-next-line + usesDynamicLoginMethods: true, + recipeList: [ + // other recipes... + // highlight-start + supertokensUITOTP.init(), + supertokensUIMultiFactorAuth.init(), + supertokensUIMultitenancy.init({ + override: { + functions: (originalImplementation) => { + return { + ...originalImplementation, + getTenantId: async (context) => { + return "TODO" + } + } + } + } + }) + // highlight-end + ] +}) +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import supertokens from "supertokens-web-js-script"; +import MultiFactorAuth from 'supertokens-web-js-script/recipe/multifactorauth'; +import Session from "supertokens-web-js-script/recipe/session"; + +supertokens.init({ + appInfo: { + apiDomain: "...", + apiBasePath: "...", + appName: "...", + }, + recipeList: [ + // highlight-start + Session.init(), + MultiFactorAuth.init(), + // highlight-end + ], +}); +``` + + + - Just like on the backend, we init the `totp` recipe in the `recipeList`. @@ -1031,6 +1164,14 @@ function App() { + + +:::success +This step is not required for non React apps, since all the pre built UI components are already added into the bundle. +::: + + + With the above configuration, users will see the first and second factor based on the tenant configuration. For the tenant we configured above, users will see email password or social login first. After completing that, users will be redirected to `/auth/mfa/totp` (assuming that the `websiteBasePath` is `/auth`) where they will be asked to setup the factor, or complete the TOTP challenge if they have already setup the factor before. The UI for this screen looks like: diff --git a/v2/mfa/with-email-verification.mdx b/v2/mfa/with-email-verification.mdx index f220fe850..53f149287 100644 --- a/v2/mfa/with-email-verification.mdx +++ b/v2/mfa/with-email-verification.mdx @@ -84,6 +84,49 @@ In the snippet above, we override the `getGlobalClaimValidators` function in the + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + appName: "...", + apiDomain: "...", + websiteDomain: "...", + }, + recipeList: [ + // other recipes... + supertokensUIEmailVerification.init({ + mode: "REQUIRED", + }), + supertokensUISession.init({ + override: { + functions: (originalImplementation) => { + return { + ...originalImplementation, + // highlight-start + getGlobalClaimValidators: (input) => { + let emailVerificationClaimValidator = input.claimValidatorsAddedByOtherRecipes.find(v => v.id === supertokensUIEmailVerification.EmailVerificationClaim.id)!; + let filteredValidators = input.claimValidatorsAddedByOtherRecipes.filter(v => v.id !== supertokensUIEmailVerification.EmailVerificationClaim.id); + return [...filteredValidators, emailVerificationClaimValidator]; + } + // highlight-end + } + } + } + }) + ] +}) +``` + +In the snippet above, we override the `getGlobalClaimValidators` function in the Session recipe to add the email verification validator at the end of the returned validators array. This ensures that post the first factor sign up, the first validator that fails is the MFA one which will redirect the user to complete the MFA factors. + + + diff --git a/v2/passwordless/advanced-customizations/frontend-functions-override/usage.mdx b/v2/passwordless/advanced-customizations/frontend-functions-override/usage.mdx index 0700c64e8..bdc73c369 100644 --- a/v2/passwordless/advanced-customizations/frontend-functions-override/usage.mdx +++ b/v2/passwordless/advanced-customizations/frontend-functions-override/usage.mdx @@ -2,20 +2,25 @@ id: usage title: How to use hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # How to use ## Use the override config + + + :::info See all the [functions that can be overrided here](https://supertokens.com/docs/auth-react/modules/recipe_passwordless.html#RecipeInterface) ::: - + ```tsx @@ -55,7 +60,58 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIPasswordless.init({ + contactMethod: "EMAIL", // This example will work with any contactMethod + //highlight-start + override: { + functions: (originalImplementation) => { + return { + ...originalImplementation, + // we will only be overriding what happens when a user + // enters the OTP or clicks on the magic link + consumeCode: async function (input) { + // TODO: some custom logic + + // or call the default behaviour as show below + return originalImplementation.consumeCode(input); + }, + // ... + // TODO: override more functions + } + } + } + //highlight-end + }) + ] +}); +``` + + - `originalImplementation` is an object that contain functions that have the original implementation for this recipe. They can be used in your functions as a way to use the SuperTokens' default behaviour. -- In the above code snippet, we override the `consumeCode` function of this recipe. This means that when the user clicks enters the OTP or clicks on the magic link, your function will be called with the relevant `input` object. \ No newline at end of file +- In the above code snippet, we override the `consumeCode` function of this recipe. This means that when the user clicks enters the OTP or clicks on the magic link, your function will be called with the relevant `input` object. + + + + +:::caution +Not applicable since you need to build custom UI anyway, so when you call the functions from our SDK, or call the API directly, you can run pre / post logic in your own code. +::: + + + diff --git a/v2/passwordless/advanced-customizations/frontend-hooks/handle-event.mdx b/v2/passwordless/advanced-customizations/frontend-hooks/handle-event.mdx index bb1c6fc3d..fc9ba698c 100644 --- a/v2/passwordless/advanced-customizations/frontend-hooks/handle-event.mdx +++ b/v2/passwordless/advanced-customizations/frontend-hooks/handle-event.mdx @@ -2,16 +2,22 @@ id: handle-event title: Handle Event Hook hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Handle Event Hook + + + + This function is called for various user actions. It can be used for logging, analytics or any side effect purposes (these are essentially fire and forget events). - + ```tsx @@ -40,9 +46,51 @@ Passwordless.init({ }) ``` + + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) + +import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless"; + +supertokensUIPasswordless.init({ + contactMethod: "EMAIL", // This example works with any contactMethod + onHandleEvent: (context) => { + if (context.action === "PASSWORDLESS_CODE_SENT") { + + } else if (context.action === "PASSWORDLESS_RESTART_FLOW") { + + } else if (context.action === "SUCCESS") { + if (context.createdNewSession) { + let user = context.user; + if (context.isNewRecipeUser && context.user.loginMethods.length === 1) { + // sign up success + } else { + // sign in success + } + } else { + // this is during second factor login + } + } + }, +}) +``` + + + + :::info Also checkout the [session recipe hand event hook](/docs/session/advanced-customizations/frontend-hooks/handle-event). ::: - - \ No newline at end of file + + + +:::caution +Not applicable since you need to build custom UI anyway, so when you call the functions from our SDK, or call the API directly, you can run pre / post logic in your own code. +::: + + + diff --git a/v2/passwordless/advanced-customizations/frontend-hooks/pre-api.mdx b/v2/passwordless/advanced-customizations/frontend-hooks/pre-api.mdx index 43a7ee38c..7e32098f5 100644 --- a/v2/passwordless/advanced-customizations/frontend-hooks/pre-api.mdx +++ b/v2/passwordless/advanced-customizations/frontend-hooks/pre-api.mdx @@ -56,6 +56,43 @@ Passwordless.init({ }) ``` + + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless"; + +supertokensUIPasswordless.init({ + contactMethod: "EMAIL", // This example will work with any contactMethod. + preAPIHook: async (context) => { + let url = context.url; + + // is the fetch config object that contains the header, body etc.. + let requestInit = context.requestInit; + + let action = context.action; + if (action === "EMAIL_EXISTS") { + + } else if (action === "PASSWORDLESS_CONSUME_CODE") { + + } else if (action === "PASSWORDLESS_CREATE_CODE") { + + } else if (action === "PASSWORDLESS_RESEND_CODE") { + + } else if (action === "PHONE_NUMBER_EXISTS") { + + } + + // events such as sign out are in the + // session recipe pre API hook (See the info box below) + return { + requestInit, url + }; + } +}) +``` diff --git a/v2/passwordless/advanced-customizations/frontend-hooks/redirection-callback.mdx b/v2/passwordless/advanced-customizations/frontend-hooks/redirection-callback.mdx index 396c9d1e0..5780bb5b0 100644 --- a/v2/passwordless/advanced-customizations/frontend-hooks/redirection-callback.mdx +++ b/v2/passwordless/advanced-customizations/frontend-hooks/redirection-callback.mdx @@ -2,16 +2,22 @@ id: redirection-callback title: Redirection Callback Hook hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" + # Redirection Callback Hook + + + This function is used to change where the user is redirected to post certain actions. For example, you can use this to redirect a user to a specific URL post sign in / up. If you're embedding the sign in / up components in a popup and wish to disable redirection entirely, simply return `null`. - + ```tsx @@ -48,5 +54,56 @@ SuperTokens.init({ })], }); ``` + + + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless"; +import {init as supertokensUIInit} from "supertokens-auth-react-script" + +supertokensUIInit({ + appInfo: { + appName: "SuperTokens", + apiDomain: "http://localhost:3000", + websiteDomain: "http://localhost:3000", + }, + getRedirectionURL: async (context) => { + if (context.action === "SUCCESS" && context.newSessionCreated) { + // called on a successful sign in / up. Where should the user go next? + let redirectToPath = context.redirectToPath; + if (redirectToPath !== undefined) { + // we are navigating back to where the user was before they authenticated + return redirectToPath; + } + if (context.createdNewUser) { + // user signed up + return "/onboarding" + } else { + // user signed in + return "/dashboard" + } + } + // return undefined to let the default behaviour play out + return undefined; + }, + recipeList: [supertokensUIPasswordless.init({ + contactMethod: "EMAIL", // This example will work with any contactMethod. + })], +}); +``` + - + + + + + +:::caution +Not applicable since you need to build custom UI anyway, so you can redirect the user after calling our SDK functions / API. +::: + + + \ No newline at end of file diff --git a/v2/passwordless/advanced-customizations/react-component-override/usage.mdx b/v2/passwordless/advanced-customizations/react-component-override/usage.mdx index fd4461f6b..70cc7416b 100644 --- a/v2/passwordless/advanced-customizations/react-component-override/usage.mdx +++ b/v2/passwordless/advanced-customizations/react-component-override/usage.mdx @@ -2,23 +2,27 @@ id: usage title: How to use hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" import {Answer} from "/src/components/question" import {Question}from "/src/components/question" # How to use + + + + + + 1. You will have to use the `PasswordlessComponentsOverrideProvider` or the `AuthRecipeComponentsOverrideContextProvider` component as shown below. make sure that it render the SuperTokens components inside this component. 2. [Pick a component](#finding-which-component-will-be-overridden) that you'd like to override by its key. 3. Supply a React component against the key you have picked. Your custom component will get the original component as a `prop`. -## Example - - - @@ -123,9 +127,6 @@ export default App; Please make sure that the file in which this config is specified is a `.tsx` or ` .jsx` file type. ::: - - - ## Finding which component will be overridden To do that, you should use React Developer Tools extension which provides a component tree inspector. @@ -169,4 +170,24 @@ function App() { ); } export default App; -``` \ No newline at end of file +``` + + + + +:::caution +Not applicable to non-react apps. You can disable the specific pre built UI component, and then build your own UI instead. +::: + + + + + + + +:::caution +Not applicable to custom UI +::: + + + \ No newline at end of file diff --git a/v2/passwordless/common-customizations/change-magic-link-url.mdx b/v2/passwordless/common-customizations/change-magic-link-url.mdx index 7f915dcc5..8f219e260 100644 --- a/v2/passwordless/common-customizations/change-magic-link-url.mdx +++ b/v2/passwordless/common-customizations/change-magic-link-url.mdx @@ -2,14 +2,16 @@ id: change-magic-link-url title: Changing the Magic Link URL hide_title: true +show_ui_switcher: true --- import BackendSDKTabs from "/src/components/tabs/BackendSDKTabs"; -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Changing the Magic Link URL @@ -147,7 +149,10 @@ init( ## Frontend change - + + + + When the user clicks the magic link, you need to render the `LinkClicked` component that exported by our SDK on that page. By default, this already happens on the `${websiteDomain}/${websiteBasePath}/verify` path. To change this, you need to: @@ -174,4 +179,34 @@ function CustomLinkClickedScreen () { ``` - + + + +When the user clicks the magic link, you need to build your own UI on that page to handle the link clicked. You also need to disable the pre built UI that was provided by our SDK for the link clicked screen as shown below: + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless"; + +supertokensUIPasswordless.init({ + contactMethod: "EMAIL", // This example will work with any contactMethod + linkClickedScreenFeature: { + disableDefaultUI: true + }, +}); +``` + + + + + + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/passwordless/common-customizations/changing-base-path/api-base-path.mdx b/v2/passwordless/common-customizations/changing-base-path/api-base-path.mdx index f7a1a28f7..04d981956 100644 --- a/v2/passwordless/common-customizations/changing-base-path/api-base-path.mdx +++ b/v2/passwordless/common-customizations/changing-base-path/api-base-path.mdx @@ -112,6 +112,45 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +supertokensUIInit({ + appInfo: { + appName: "yourAppName", + apiDomain: "yourApi", + websiteDomain: "yourWebsite", + // highlight-next-line + apiBasePath: "/api/v3/auth" + }, + recipeList: [], +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +// this goes in the root of your frontend app +import SuperTokens from "supertokens-web-js"; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + // highlight-next-line + apiBasePath: "/api/v3/auth", + appName: "...", + }, + recipeList: [/* ... */], +}); +``` + + + diff --git a/v2/passwordless/common-customizations/changing-base-path/website-base-path.mdx b/v2/passwordless/common-customizations/changing-base-path/website-base-path.mdx index 0795a935f..3e3e959bd 100644 --- a/v2/passwordless/common-customizations/changing-base-path/website-base-path.mdx +++ b/v2/passwordless/common-customizations/changing-base-path/website-base-path.mdx @@ -2,6 +2,7 @@ id: website-base-path title: Website Base Path hide_title: true +show_ui_switcher: true --- @@ -9,6 +10,7 @@ hide_title: true import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" import BackendSDKTabs from "/src/components/tabs/BackendSDKTabs" import BackendSDKCasing from "/src/components/BackendSDKCasing" import TabItem from '@theme/TabItem'; @@ -16,6 +18,10 @@ import TabItem from '@theme/TabItem'; # Website Base Path ## Step 1) Front End Change + + + + Since the beginning of this guide, you probably noticed that all the front-end routes for SuperTokens widget are prefixed by `/auth`. You can change this value in the `init` function by setting websiteBasePath. @@ -39,8 +45,36 @@ SuperTokens.init({ + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +supertokensUIInit({ + appInfo: { + appName: "yourAppName", + apiDomain: "yourApi", + websiteDomain: "yourWebsite", + // highlight-next-line + websiteBasePath: "/authentication" + }, + recipeList: [], +}); +``` + + + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + ## Step 2) Back End Change diff --git a/v2/passwordless/common-customizations/email-verification/about.mdx b/v2/passwordless/common-customizations/email-verification/about.mdx index 12e146de8..38e945c5f 100644 --- a/v2/passwordless/common-customizations/email-verification/about.mdx +++ b/v2/passwordless/common-customizations/email-verification/about.mdx @@ -212,6 +212,54 @@ function App() { + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + // highlight-start + supertokensUIEmailVerification.init({ + mode: "REQUIRED", // or "OPTIONAL" + }), + // highlight-end + ], +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from "supertokens-web-js"; +import EmailVerification from "supertokens-web-js/recipe/emailverification"; +import Session from "supertokens-web-js/recipe/session"; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + // highlight-next-line + EmailVerification.init(), + Session.init(), + ], +}); +``` + + + :::important diff --git a/v2/passwordless/common-customizations/email-verification/changing-style.mdx b/v2/passwordless/common-customizations/email-verification/changing-style.mdx index 596a7ca00..de0cbe03c 100644 --- a/v2/passwordless/common-customizations/email-verification/changing-style.mdx +++ b/v2/passwordless/common-customizations/email-verification/changing-style.mdx @@ -2,19 +2,20 @@ id: changing-style title: Changing Style via CSS hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Changing Style via CSS -:::important -This is applicable to prebuilt UI only. -::: + + Updating the CSS allows you to change the UI of our components to meet your needs. @@ -30,7 +31,7 @@ Each stylable components contains `data-supertokens` attributes (in our example Let's add a `border` to our `link` elements. The syntax for styling is plain CSS. - + ```tsx @@ -62,7 +63,38 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailVerification.init({ + // highlight-start + style: ` + [data-supertokens~=link] { + border: 2px solid #0076ff; + border-radius: 5; + width: 30%; + margin: 0 auto; + } + `, + // highlight-end + }) + ] +}); +``` + + + The above will result in: @@ -72,7 +104,7 @@ The above will result in: By default, SuperTokens uses the Arial font. The best way to override this is to add a `font-family` styling to the `container` component in the recipe configuration. - + ```tsx @@ -101,13 +133,39 @@ SuperTokens.init({ }); ``` - + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailVerification.init({ + // highlight-start + style: ` + [data-supertokens~=container] { + font-family: cursive + } + ` + // highlight-end + }), + ] +}); +``` + + ### Using media queries You may want to have different CSS for different viewports. This can be achieved via media queries like this: - + ```tsx @@ -145,7 +203,44 @@ SuperTokens.init({ }); ``` - + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + // ... + supertokensUIEmailVerification.init({ + // ... + style: ` + [data-supertokens~=link] { + border: 2px solid #0076ff; + borderRadius: 5; + width: 30%; + margin: 0 auto; + } + + // highlight-start + @media (max-width: 440px) { + [data-supertokens~=link] { + width: 90%; + } + } + // highlight-end + `, + }), + ], +}); +``` + + ## Customising individual screens @@ -153,7 +248,7 @@ SuperTokens.init({ This screen is where the user is redirected if `mode` is set to `REQUIRED` and they visit a path that requires a verified email. - + ```tsx @@ -180,13 +275,38 @@ SuperTokens.init({ }); ``` - + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + supertokensUIEmailVerification.init({ + // highlight-start + sendVerifyEmailScreen: { + style: ` ... ` + } + // highlight-end + }) + ] +}); +``` + + ### Verify link clicked screen This is the screen shown to users that click the email verification link in the email. - + ```tsx @@ -213,4 +333,41 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + supertokensUIEmailVerification.init({ + // highlight-start + verifyEmailLinkClickedScreen: { + style: ` ... `, + } + // highlight-end + }) + ] +}); +``` + + + + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/passwordless/common-customizations/email-verification/embed-in-page.mdx b/v2/passwordless/common-customizations/email-verification/embed-in-page.mdx index 8f8a84e8d..d1f1445d2 100644 --- a/v2/passwordless/common-customizations/email-verification/embed-in-page.mdx +++ b/v2/passwordless/common-customizations/email-verification/embed-in-page.mdx @@ -2,20 +2,25 @@ id: embed-in-page title: Embed in a page hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" import BackendSDKTabs from "/src/components/tabs/BackendSDKTabs" # Embed in a page + + + ## Step 1: Disable the default implementation - + ```tsx @@ -42,11 +47,39 @@ SuperTokens.init({ If you navigate to `/auth/verify-email`, you should not see the widget anymore. - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailVerification.init({ + mode: "REQUIRED", + // highlight-start + disableDefaultUI: true + // highlight-end + }), + ] +}); +``` + +If you navigate to `/auth/verify-email`, you should not see the widget anymore. + + + ## Step 2: Render the component yourself - + Add the `EmailVerification` component in your app: @@ -68,7 +101,27 @@ class EmailVerificationPage extends React.Component { } ``` - + + + +:::caution +You will have to build your own UI instead. +::: + + + + + + + +## Step 1 & 2: Disable the pre built UI + +:::caution +Not applicable since you do not use our pre built UI +::: + + + ## Step 3: Changing the website path for the email verification UI (optional) @@ -208,7 +261,10 @@ init( ### Step B: On the frontend - + + + + ```tsx @@ -238,4 +294,45 @@ SuperTokens.init({ }) ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + supertokensUIEmailVerification.init({ + mode: "REQUIRED", + //highlight-start + + // The user will be taken to the custom path when they need to get their email verified. + getRedirectionURL: async (context) => { + if (context.action === "VERIFY_EMAIL") { + return "/custom-email-verification-path"; + }; + } + //highlight-end + }) + ] +}) +``` + + + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/passwordless/common-customizations/email-verification/protecting-routes.mdx b/v2/passwordless/common-customizations/email-verification/protecting-routes.mdx index d7d7a5ca0..e0bf31003 100644 --- a/v2/passwordless/common-customizations/email-verification/protecting-routes.mdx +++ b/v2/passwordless/common-customizations/email-verification/protecting-routes.mdx @@ -1114,8 +1114,8 @@ function ProtectedComponent() { ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { EmailVerificationClaim } from "supertokens-auth-react/recipe/emailverification"; +import Session from "supertokens-web-js/recipe/session"; +import { EmailVerificationClaim } from "supertokens-web-js/recipe/emailverification"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { diff --git a/v2/passwordless/common-customizations/embed-sign-in-up-form.mdx b/v2/passwordless/common-customizations/embed-sign-in-up-form.mdx index 8864ca6ff..d78b707ce 100644 --- a/v2/passwordless/common-customizations/embed-sign-in-up-form.mdx +++ b/v2/passwordless/common-customizations/embed-sign-in-up-form.mdx @@ -16,12 +16,13 @@ import RRDVersionSubTabs from "/src/components/tabs/RRDVersionSubTabs" + + + ## Case 1: Rendering the Auth Widget in a page The following example shows the scenario where you have a dedicated route, such as `/auth`, for rendering the Auth Widget. Upon a successful login, the user will be automatically redirected to the return value of `getRedirectionURL` (defaulting to `/`). - - @@ -181,8 +182,6 @@ function MyAuthPage() { ``` - - In the above code snippet, we: @@ -199,8 +198,6 @@ When the user visits the `/auth` page, they will see the SignIn UI by default. T The following example shows the scenario where you have a dedicated route, such as `/auth`, for rendering the Auth Widget. However, upon a successful login, the user will see a logged in UI instead of getting redirected. - - @@ -417,8 +414,6 @@ function LandingPage() { ``` - - In the above code snippet, we wrap the logged-in component with `Session.SessionAuth` to validate all claims before displaying the logged-in UI. For instance, with email verification enabled, if a user's email is unverified, `Session.SessionAuth` redirects to the email verification page. @@ -430,8 +425,6 @@ In the above case, redirection may occur if a claim fails. For instance, in the The following example shows the scenario where you embed the Auth Widget in a popup, and upon successful login, you aim to close the popup. - - @@ -687,13 +680,23 @@ function AuthPopup() { ``` - - :::note In the above case, redirection may occur if a claim fails. For instance, in the case of an Email Verification claim, if the user's email is not verified, they will be redirected to the email verification page. To prevent redirection for failed claims, please contact us on [Discord](https://supertokens.com/discord) for assistance. ::: + + + + +:::caution +Not applicable to non-react apps. Please build your own custom UI instead. +::: + + + + + diff --git a/v2/passwordless/common-customizations/handling-signinup-success.mdx b/v2/passwordless/common-customizations/handling-signinup-success.mdx index 7914484a6..ea08ea158 100644 --- a/v2/passwordless/common-customizations/handling-signinup-success.mdx +++ b/v2/passwordless/common-customizations/handling-signinup-success.mdx @@ -70,6 +70,56 @@ Please refer to [this page](../advanced-customizations/frontend-hooks/handle-eve + + +This method allows you to fire events immediately after a successful sign in. For example to send analytics events post sign in. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIPasswordless.init({ + contactMethod: "EMAIL_OR_PHONE", + + // highlight-start + onHandleEvent: async (context) => { + if (context.action === "PASSWORDLESS_RESTART_FLOW") { + // TODO: + } else if (context.action === "PASSWORDLESS_CODE_SENT") { + // TODO: + } else { + let {id, emails, phoneNumbers} = context.user; + if (context.action === "SUCCESS") { + if (context.isNewRecipeUser && context.user.loginMethods.length === 1) { + // TODO: Sign up + } else { + // TODO: Sign in + } + } + } + } + // highlight-end + }), + supertokensUISession.init() + ] +}); +``` + +:::info +Please refer to [this page](../advanced-customizations/frontend-hooks/handle-event) to learn more about the `onHandleEvent` hook. +::: + + + diff --git a/v2/passwordless/common-customizations/multi-tenancy/common-domain-login.mdx b/v2/passwordless/common-customizations/multi-tenancy/common-domain-login.mdx index 0df6ef549..306891fca 100644 --- a/v2/passwordless/common-customizations/multi-tenancy/common-domain-login.mdx +++ b/v2/passwordless/common-customizations/multi-tenancy/common-domain-login.mdx @@ -173,51 +173,6 @@ export const AuthPage = () => { - - - - -```tsx -import { useState } from "react"; -import { getRoutingComponent } from "supertokens-auth-react/ui"; -^{prebuiltuiimport} -import { useSessionContext } from "supertokens-auth-react/recipe/session"; - -export const AuthPage = () => { - const [inputTenantId, setInputTenantId] = useState(""); - const tenantId = localStorage.getItem("tenantId") ?? undefined; - const session = useSessionContext(); - - if (session.loading) { - return null; - } - - if ( - tenantId !== undefined || // if we have a tenantId stored - session.doesSessionExist === true || // or an active session (it'll contain the tenantId) - new URLSearchParams(location.search).has("tenantId") // or we are on a link (e.g.: email verification) that contains the tenantId - ) { - return getRoutingComponent([^{recipePreBuiltUINameCapitalLetters}]); - } else { - return ( -
{ - // this value will be read by SuperTokens as shown in the next steps. - localStorage.setItem("tenantId", inputTenantId); - }}> -

Enter your organisation's name:

- setInputTenantId(e.target.value)} /> -
- -
- ); - } -}; -``` - - - - - We render a simple UI which asks the user for their organisation's name. Their input will be treated as their tenant ID. - Once the user has submitted that form, we will store their input in localstorage. This value will be read later on (as shown below) by SuperTokens to render the right login method based on the saved tenantId. - In case the tenantID exists in localstorage, we render the SuperTokens UI as usual. @@ -233,6 +188,20 @@ We want to render the `AuthPage` component to show on `^{form_websiteBasePath}/* The `AuthPage` will replace the call to `getSuperTokensRoutesForReactRouterDom` or `getRoutingComponent` that you may have added to your app from the quick setup section. ::: + + + + +:::caution +No code snippet provided here, however, if you visit the auth component, you will see that we are rendering the pre built UI in the `"supertokensui"` `div` element on page load. The logic here needs to change to first check if the user has provided us with the tenantId. If they have, we render the SuperTokens UI as usual. If they have not, we render a simple UI which asks the user for their tenant id and save that in localstorage. + +Switch to the React code tab here to see how this is implemented in React, and a similar logic can be followed here. +::: + + + + + @@ -382,6 +351,50 @@ We also set the `usesDynamicLoginMethods` to `true` which tells SuperTokens that + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIMultitenancy from "supertokens-auth-react-script/recipe/multitenancy"; + +supertokensUIInit({ + appInfo: { + appName: "...", + apiDomain: "...", + websiteDomain: "...", + apiBasePath: "...", + websiteBasePath: "..." + }, + // highlight-next-line + usesDynamicLoginMethods: true, + recipeList: [ + // highlight-start + supertokensUIMultitenancy.init({ + override: { + functions: (oI) => { + return { + ...oI, + getTenantId: (input) => { + let tid = localStorage.getItem("tenantId"); + return tid === null ? undefined : tid; + } + } + } + } + }) + // highlight-end + // other recipes... + ] +}); +``` + +:::important +We also set the `usesDynamicLoginMethods` to `true` which tells SuperTokens that the login methods are dynamic (based on the tenantId). This means that on page load (of the login page), SuperTokens will first fetch the configured login methods for the tenantId and display the login UI based on the result of the API call. +::: + + + @@ -641,6 +654,42 @@ SuperTokens.init({ + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; +import supertokensUIMultitenancy from "supertokens-auth-react-script/recipe/multitenancy"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + // highlight-start + getRedirectionURL: async (context) => { + if (context.action === "SUCCESS" && context.newSessionCreated) { + let claimValue: string[] | undefined = await supertokensUISession.getClaimValue({ + claim: supertokensUIMultitenancy.AllowedDomainsClaim + }); + if (claimValue !== undefined) { + window.location.href = "https://" + claimValue[0]; + } else { + // there was no configured allowed domain for this user. Throw an error cause of + // misconfig or redirect to a default sub domain + } + } + return undefined; + }, + // highlight-end + recipeList: [ /* Recipe init here... */ ] +}); +``` + + + @@ -761,6 +810,68 @@ Above, in `Session.init` on the frontend, we add the `hasAccessToCurrentDomain` + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; +import supertokensMultitenancy from "supertokens-web-js-script/recipe/multitenancy"; + +supertokensUISession.init({ + override: { + functions: (oI) => ({ + ...oI, + getGlobalClaimValidators: ({ claimValidatorsAddedByOtherRecipes }) => [ + ...claimValidatorsAddedByOtherRecipes, + { + ...supertokensMultitenancy.AllowedDomainsClaim.validators.hasAccessToCurrentDomain(), + onFailureRedirection: async () => { + let claimValue = await supertokensUISession.getClaimValue({ + claim: supertokensMultitenancy.AllowedDomainsClaim, + }); + return "https://" + claimValue![0]; + }, + }, + ], + }), + }, +}) +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: +```tsx +import Session from 'supertokens-web-js/recipe/session'; +import { AllowedDomainsClaim } from 'supertokens-web-js/recipe/multitenancy'; + +Session.init({ + override: { + functions: (oI) => ({ + ...oI, + getGlobalClaimValidators: ({ claimValidatorsAddedByOtherRecipes }) => [ + ...claimValidatorsAddedByOtherRecipes, + { + ...AllowedDomainsClaim.validators.hasAccessToCurrentDomain(), + onFailureRedirection: async () => { + let claimValue = await Session.getClaimValue({ + claim: AllowedDomainsClaim, + }); + return "https://" + claimValue![0]; + }, + }, + ], + }), + }, +}) +``` + +Above, in `Session.init` on the frontend, we add the `hasAccessToCurrentDomain` claim validator to the global validators. This means, that [whenever we check protect a route](../sessions/protecting-frontend-routes), it will check if `hasAccessToCurrentDomain` has passed, and if not, SuperTokens will redirect to the user to their right sub domain (via the values set in the `AllowedDomainsClaim` session claim). + + + diff --git a/v2/passwordless/common-customizations/multi-tenancy/sub-domain-login.mdx b/v2/passwordless/common-customizations/multi-tenancy/sub-domain-login.mdx index 1ad32b1cd..a1018910e 100644 --- a/v2/passwordless/common-customizations/multi-tenancy/sub-domain-login.mdx +++ b/v2/passwordless/common-customizations/multi-tenancy/sub-domain-login.mdx @@ -134,6 +134,48 @@ SuperTokens.init({ + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; +import supertokensUIMultitenancy from "supertokens-auth-react-script/recipe/multitenancy"; +supertokensUIInit({ + appInfo: { + appName: "^{form_appName}", + apiDomain: "^{form_apiDomain}", + websiteDomain: "^{form_websiteDomain}", + apiBasePath: "^{form_apiBasePath}", + websiteBasePath: "^{form_websiteBasePath}" + }, + // highlight-start + usesDynamicLoginMethods: true, + // highlight-end + recipeList: [ + // Other recipes.. + supertokensUISession.init(), + // highlight-start + supertokensUIMultitenancy.init({ + override: { + functions: (oI) => { + return { + ...oI, + getTenantId: async () => { + // We treat the sub domain as the tenant ID + return window.location.host.split('.')[0] + } + } + } + }, + }) + // highlight-end + ] +}); +``` + + + @@ -475,6 +517,68 @@ Above, in `Session.init` on the frontend, we add the `hasAccessToCurrentDomain` + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; +import supertokensMultitenancy from "supertokens-web-js-script/recipe/multitenancy"; + +supertokensUISession.init({ + override: { + functions: (oI) => ({ + ...oI, + getGlobalClaimValidators: ({ claimValidatorsAddedByOtherRecipes }) => [ + ...claimValidatorsAddedByOtherRecipes, + { + ...supertokensMultitenancy.AllowedDomainsClaim.validators.hasAccessToCurrentDomain(), + onFailureRedirection: async () => { + let claimValue = await supertokensUISession.getClaimValue({ + claim: supertokensMultitenancy.AllowedDomainsClaim, + }); + return "https://" + claimValue![0]; + }, + }, + ], + }), + }, +}) +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: +```tsx +import Session from 'supertokens-web-js/recipe/session'; +import { AllowedDomainsClaim } from 'supertokens-web-js/recipe/multitenancy'; + +Session.init({ + override: { + functions: (oI) => ({ + ...oI, + getGlobalClaimValidators: ({ claimValidatorsAddedByOtherRecipes }) => [ + ...claimValidatorsAddedByOtherRecipes, + { + ...AllowedDomainsClaim.validators.hasAccessToCurrentDomain(), + onFailureRedirection: async () => { + let claimValue = await Session.getClaimValue({ + claim: AllowedDomainsClaim, + }); + return "https://" + claimValue![0]; + }, + }, + ], + }), + }, +}) +``` + +Above, in `Session.init` on the frontend, we add the `hasAccessToCurrentDomain` claim validator to the global validators. This means, that [whenever we check protect a route](../sessions/protecting-frontend-routes), it will check if `hasAccessToCurrentDomain` has passed, and if not, SuperTokens will redirect to the user to their right sub domain (via the values set in the `AllowedDomainsClaim` session claim). + + + diff --git a/v2/passwordless/common-customizations/sessions/claims/access-token-payload.mdx b/v2/passwordless/common-customizations/sessions/claims/access-token-payload.mdx index 828b6cb16..ac18be4b9 100644 --- a/v2/passwordless/common-customizations/sessions/claims/access-token-payload.mdx +++ b/v2/passwordless/common-customizations/sessions/claims/access-token-payload.mdx @@ -1111,7 +1111,7 @@ async function someFunc() { ```tsx -import Session from 'supertokens-auth-react/recipe/session'; +import Session from 'supertokens-web-js/recipe/session'; async function someFunc() { if (await Session.doesSessionExist()) { diff --git a/v2/passwordless/common-customizations/sessions/claims/claim-validators.mdx b/v2/passwordless/common-customizations/sessions/claims/claim-validators.mdx index 8ffe6e207..2a7b59a42 100644 --- a/v2/passwordless/common-customizations/sessions/claims/claim-validators.mdx +++ b/v2/passwordless/common-customizations/sessions/claims/claim-validators.mdx @@ -856,8 +856,8 @@ Now whenever you wrap your component with the `` wrapper, SuperToke ```tsx -import SuperTokens from "supertokens-auth-react"; -import Session, { BooleanClaim } from 'supertokens-auth-react/recipe/session'; +import SuperTokens from "supertokens-web-js"; +import Session, { BooleanClaim } from 'supertokens-web-js/recipe/session'; const SecondFactorClaim = new BooleanClaim({ id: "2fa-completed", @@ -870,7 +870,6 @@ SuperTokens.init({ appInfo: { apiDomain: "...", appName: "...", - websiteDomain: "..." }, recipeList: [ //... @@ -894,7 +893,7 @@ SuperTokens.init({ Now you can protect your frontend routes by using the `Session.validateClaims` function as shown below: ```tsx -import Session, { BooleanClaim } from "supertokens-auth-react/recipe/session"; +import Session, { BooleanClaim } from "supertokens-web-js/recipe/session"; const SecondFactorClaim = new BooleanClaim({ id: "2fa-completed", @@ -2286,8 +2285,8 @@ Unlike using the `overrideGlobalClaimValidators` prop, the `useClaimValue` funct ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { @@ -2330,8 +2329,8 @@ async function shouldLoadRoute(): Promise { If you want to have more complex access control, you can get the roles list from the session as follows, and check the list yourself: ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { diff --git a/v2/passwordless/common-customizations/sessions/disable-interception.mdx b/v2/passwordless/common-customizations/sessions/disable-interception.mdx index e1a878e6e..7d4a03d8a 100644 --- a/v2/passwordless/common-customizations/sessions/disable-interception.mdx +++ b/v2/passwordless/common-customizations/sessions/disable-interception.mdx @@ -58,6 +58,63 @@ Session.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUISession.init({ + override: { + functions: (oI) => { + return { + ...oI, + shouldDoInterceptionBasedOnUrl: (url, apiDomain, sessionTokenBackendDomain) => { + try { + let urlObj = new URL(url); + if (!urlObj.pathname.startsWith("/auth")) { + return false; + } + } catch (ignored) { } + return oI.shouldDoInterceptionBasedOnUrl(url, apiDomain, sessionTokenBackendDomain); + } + } + } + } +}) +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import Session from "supertokens-web-js/recipe/session"; + +Session.init({ + override: { + functions: (oI) => { + return { + ...oI, + shouldDoInterceptionBasedOnUrl: (url, apiDomain, sessionTokenBackendDomain) => { + try { + let urlObj = new URL(url); + if (!urlObj.pathname.startsWith("/auth")) { + return false; + } + } catch (ignored) { } + return oI.shouldDoInterceptionBasedOnUrl(url, apiDomain, sessionTokenBackendDomain); + } + } + } + } +}) +``` + + + diff --git a/v2/passwordless/common-customizations/sessions/in-iframe.mdx b/v2/passwordless/common-customizations/sessions/in-iframe.mdx index e43e2fa15..0589f4b94 100644 --- a/v2/passwordless/common-customizations/sessions/in-iframe.mdx +++ b/v2/passwordless/common-customizations/sessions/in-iframe.mdx @@ -69,6 +69,65 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; +declare let cookieHandler: any // typecheck-only, removed from output +declare let windowHandler: any // typecheck-only, removed from output + +supertokensUIInit({ + cookieHandler, + windowHandler, + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUISession.init({ + // highlight-start + tokenTransferMethod: "header", + isInIframe: true + // highlight-end + }) + ] +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from "supertokens-web-js"; +import Session from "supertokens-web-js/recipe/session"; +declare let cookieHandler: any // typecheck-only, removed from output +declare let windowHandler: any // typecheck-only, removed from output + +SuperTokens.init({ + cookieHandler, + windowHandler, + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + Session.init({ + // highlight-start + tokenTransferMethod: "header", + isInIframe: true + // highlight-end + }) + ], +}) +``` + + + @@ -84,8 +143,12 @@ SuperTokens.init({ ```tsx import SuperTokens from "supertokens-web-js"; import Session from "supertokens-web-js/recipe/session"; +declare let cookieHandler: any // typecheck-only, removed from output +declare let windowHandler: any // typecheck-only, removed from output SuperTokens.init({ + cookieHandler, + windowHandler, appInfo: { apiDomain: "...", appName: "...", @@ -107,7 +170,11 @@ SuperTokens.init({ ```tsx import supertokens from "supertokens-web-js-script"; import supertokensSession from "supertokens-web-js-script/recipe/session"; +declare let cookieHandler: any // typecheck-only, removed from output +declare let windowHandler: any // typecheck-only, removed from output supertokens.init({ + cookieHandler, + windowHandler, appInfo: { apiDomain: "...", appName: "...", diff --git a/v2/passwordless/common-customizations/sessions/multiple-api-endpoints.mdx b/v2/passwordless/common-customizations/sessions/multiple-api-endpoints.mdx index 2b9aae909..12d91616d 100644 --- a/v2/passwordless/common-customizations/sessions/multiple-api-endpoints.mdx +++ b/v2/passwordless/common-customizations/sessions/multiple-api-endpoints.mdx @@ -241,6 +241,51 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. +```tsx +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUISession.init({ + // highlight-next-line + sessionTokenBackendDomain: ".example.com" + }) + ] +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from 'supertokens-web-js'; +import Session from 'supertokens-web-js/recipe/session'; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + Session.init({ + sessionTokenBackendDomain: ".example.com" + }), + ], +}); +``` + + + diff --git a/v2/passwordless/common-customizations/sessions/protecting-frontend-routes.mdx b/v2/passwordless/common-customizations/sessions/protecting-frontend-routes.mdx index 13b1829bc..232bba79f 100644 --- a/v2/passwordless/common-customizations/sessions/protecting-frontend-routes.mdx +++ b/v2/passwordless/common-customizations/sessions/protecting-frontend-routes.mdx @@ -123,7 +123,7 @@ function MyDashboardComponent(props: any) { You can use the `doesSessionExist` function to check if a session exists in all your routes. ```tsx -import Session from 'supertokens-auth-react/recipe/session'; +import Session from 'supertokens-web-js/recipe/session'; async function doesSessionExist() { if (await Session.doesSessionExist()) { @@ -211,8 +211,8 @@ function ProtectedComponent() { ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { @@ -255,8 +255,8 @@ async function shouldLoadRoute(): Promise { If you want to have more complex access control, you can get the roles list from the session as follows, and check the list yourself: ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { diff --git a/v2/passwordless/common-customizations/sessions/revoke-session.mdx b/v2/passwordless/common-customizations/sessions/revoke-session.mdx index 500a1f526..fdfdad5b9 100644 --- a/v2/passwordless/common-customizations/sessions/revoke-session.mdx +++ b/v2/passwordless/common-customizations/sessions/revoke-session.mdx @@ -66,7 +66,7 @@ The [`signOut` method](https://supertokens.com/docs/web-js/modules/recipe_sessio ```tsx // highlight-next-line -import Session from "supertokens-auth-react/recipe/session"; +import Session from "supertokens-web-js/recipe/session"; async function logout () { // highlight-next-line diff --git a/v2/passwordless/common-customizations/sessions/share-session-across-sub-domains.mdx b/v2/passwordless/common-customizations/sessions/share-session-across-sub-domains.mdx index 9c95085ab..b0f863386 100644 --- a/v2/passwordless/common-customizations/sessions/share-session-across-sub-domains.mdx +++ b/v2/passwordless/common-customizations/sessions/share-session-across-sub-domains.mdx @@ -58,6 +58,56 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + // ... + // this should be equal to the domain where the user will see the login UI + apiDomain: "...", + appName: "...", + websiteDomain: "https://example.com" + }, + recipeList: [ + supertokensUISession.init({ + // highlight-next-line + sessionTokenFrontendDomain: ".example.com" + }) + ] +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from "supertokens-web-js"; +import Session from "supertokens-web-js/recipe/session"; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + Session.init({ + // highlight-start + sessionTokenFrontendDomain: ".example.com" + // highlight-end + }), + ], +}) +``` + + + :::caution diff --git a/v2/passwordless/common-customizations/sessions/ssr.mdx b/v2/passwordless/common-customizations/sessions/ssr.mdx index 116901a02..863e5cb5b 100644 --- a/v2/passwordless/common-customizations/sessions/ssr.mdx +++ b/v2/passwordless/common-customizations/sessions/ssr.mdx @@ -83,7 +83,7 @@ export function AttemptRefresh(props: any) { ```tsx -import Session from 'supertokens-auth-react/recipe/session'; +import Session from 'supertokens-web-js/recipe/session'; function attemptRefresh() { Session.attemptRefreshingSession().then(success => { diff --git a/v2/passwordless/common-customizations/sessions/token-transfer-method.mdx b/v2/passwordless/common-customizations/sessions/token-transfer-method.mdx index d07b73456..05bf214db 100644 --- a/v2/passwordless/common-customizations/sessions/token-transfer-method.mdx +++ b/v2/passwordless/common-customizations/sessions/token-transfer-method.mdx @@ -71,6 +71,54 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUISession.init({ + // highlight-next-line + tokenTransferMethod: "header" // or "cookie" + }) + ] +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from "supertokens-web-js"; +import Session from "supertokens-web-js/recipe/session"; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + Session.init({ + // highlight-next-line + tokenTransferMethod: "header" // or "cookie" + }) + ], +}) +``` + + + diff --git a/v2/passwordless/common-customizations/sessions/with-jwt/read-jwt.mdx b/v2/passwordless/common-customizations/sessions/with-jwt/read-jwt.mdx index fe1b9a7e5..6406c10f2 100644 --- a/v2/passwordless/common-customizations/sessions/with-jwt/read-jwt.mdx +++ b/v2/passwordless/common-customizations/sessions/with-jwt/read-jwt.mdx @@ -435,7 +435,7 @@ async function getJWT() { ```tsx -import Session from 'supertokens-auth-react/recipe/session'; +import Session from 'supertokens-web-js/recipe/session'; async function getJWT() { if (await Session.doesSessionExist()) { diff --git a/v2/passwordless/common-customizations/sign-in-and-up/default-country.mdx b/v2/passwordless/common-customizations/sign-in-and-up/default-country.mdx index ebe9d3965..948c47e34 100644 --- a/v2/passwordless/common-customizations/sign-in-and-up/default-country.mdx +++ b/v2/passwordless/common-customizations/sign-in-and-up/default-country.mdx @@ -2,15 +2,20 @@ id: default-country title: Setting default country for phone inputs hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" import { PasswordlessFrontendForm, ConditionalSection } from "/src/components/snippetConfigForm/passwordlessFrontendForm"; # Setting default country for phone inputs + + + + ```tsx @@ -60,7 +65,40 @@ SuperTokens.init({ ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIPasswordless.init({ + contactMethod: "^{form_contactMethod}", + // highlight-start + signInUpFeature: { + /* + * Must be a two-letter ISO country code (e.g.: "US") + */ + defaultCountry: "HU", + } + // highlight-end + }), + supertokensUISession.init({ /* ... */ }) + ] +}); +``` + + + @@ -72,7 +110,7 @@ By default, there is no default country selected. This means that users will hav If you would like to set a default country (for all users), then you should use the `defaultCountry` config: - + ```tsx @@ -104,8 +142,51 @@ SuperTokens.init({ ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIPasswordless.init({ + contactMethod: "^{form_contactMethod}", + // highlight-start + signInUpFeature: { + /* + * Must be a two-letter ISO country code (e.g.: "US") + */ + defaultCountry: "HU", + } + // highlight-end + }), + supertokensUISession.init({ /* ... */ }) + ] +}); +``` + + + + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/passwordless/common-customizations/sign-in-and-up/resend-time-gap.mdx b/v2/passwordless/common-customizations/sign-in-and-up/resend-time-gap.mdx index 788bcda66..b261df0b7 100644 --- a/v2/passwordless/common-customizations/sign-in-and-up/resend-time-gap.mdx +++ b/v2/passwordless/common-customizations/sign-in-and-up/resend-time-gap.mdx @@ -2,13 +2,18 @@ id: resend-time-gap title: Changing email / SMS resend time interval hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Changing email / SMS resend time interval + + + :::caution This limit is only enforced on the client-side. For API rate-limiting please check out the [Advanced customizations](../../advanced-customizations/apis-override/about) section. @@ -17,7 +22,7 @@ This limit is only enforced on the client-side. For API rate-limiting please che You can set `resendEmailOrSMSGapInSeconds` to establish a minimum delay before the frontend allows the user to click the "Resend" button. - + ```tsx @@ -47,4 +52,45 @@ SuperTokens.init({ ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIPasswordless.init({ + contactMethod: "EMAIL_OR_PHONE", // This example will work with any contactMethod. + // highlight-start + signInUpFeature: { + // The default value is 15 seconds + resendEmailOrSMSGapInSeconds: 60, + } + // highlight-end + }), + supertokensUISession.init({ /* ... */ }) + ] +}); +``` + + + + + + + +:::caution +At the moment, this is a frontend only setting for the pre built UI, and is therefore not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/passwordless/common-customizations/sign-in-and-up/toc-privacypolicy.mdx b/v2/passwordless/common-customizations/sign-in-and-up/toc-privacypolicy.mdx index 8c6cbe6f7..380a49b86 100644 --- a/v2/passwordless/common-customizations/sign-in-and-up/toc-privacypolicy.mdx +++ b/v2/passwordless/common-customizations/sign-in-and-up/toc-privacypolicy.mdx @@ -2,19 +2,27 @@ id: toc-privacypolicy title: Terms of service & Privacy policy links hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" + + + +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Terms of service & Privacy policy links + + + You can provide a Privacy policy and Terms of service link which will render the following text on the sign up page: -- Provided both links: "By continuing, you agree to our [Terms of Service](./toc-privacypolicy) and [Privacy Policy](./toc-privacypolicy)" -- Provided only Terms of service link: "By continuing, you agree to our [Terms of Service](./toc-privacypolicy)" -- Provided only Privacy policy link: "By continuing, you agree to our [Privacy Policy](./toc-privacypolicy)" +- Provided both links: "By signing up, you agree to our [Terms of Service](./toc-privacypolicy) and [Privacy Policy](./toc-privacypolicy)" +- Provided only Terms of service link: "By signing up, you agree to our [Terms of Service](./toc-privacypolicy)" +- Provided only Privacy policy link: "By signing up, you agree to our [Privacy Policy](./toc-privacypolicy)" - + ```tsx @@ -30,9 +38,40 @@ SuperTokens.init({ termsOfServiceLink: "https://example.com/terms-of-service", privacyPolicyLink: "https://example.com/privacy-policy", // highlight-end - recipeList: [ /* recipe list */] + recipeList: [/* ... */] +}); +``` + + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + // highlight-start + termsOfServiceLink: "https://example.com/terms-of-service", + privacyPolicyLink: "https://example.com/privacy-policy", + // highlight-end + recipeList: [/* ... */] }); ``` - + + + + + +:::caution +Not applicable since you do not use our pre built UI. +::: + + + diff --git a/v2/passwordless/common-customizations/styling/changing-colours.mdx b/v2/passwordless/common-customizations/styling/changing-colours.mdx index ab08f3cfe..8d0fff7cb 100644 --- a/v2/passwordless/common-customizations/styling/changing-colours.mdx +++ b/v2/passwordless/common-customizations/styling/changing-colours.mdx @@ -2,19 +2,24 @@ id: changing-colours title: Changing Colours hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Changing Colours + + + It is possible to update the default theme with your colours to make it fit perfectly with your website by defining a few css variables in the `style` property to the `Passwordless.init` call. You have to specify the colors as RGB (see the following example), because we use the `rgb` and `rgba` functions to apply them. For example if your website uses a dark theme, here is how you can quickly customize it: - + ```tsx @@ -45,7 +50,39 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + // highlight-start + style: ` + [data-supertokens~=container] { + --palette-background: 51, 51, 51; + --palette-inputBackground: 41, 41, 41; + --palette-inputBorder: 41, 41, 41; + --palette-textTitle: 255, 255, 255; + --palette-textLabel: 255, 255, 255; + --palette-textPrimary: 255, 255, 255; + --palette-error: 173, 46, 46; + --palette-textInput: 169, 169, 169; + --palette-textLink: 169, 169, 169; + } + `, + // highlight-end + recipeList: [ /* ... */] +}); +``` + + Prebuilt form with custom colors @@ -148,4 +185,14 @@ Changes to the palette will apply to all the UI components we provide. If you wa - Description: This value controls the color of the "Powered by SuperTokens" text on the bottom of sign-in/up pages - Default: ```173, 189, 196``` (heather grey) -Prebuilt form SuperTokens label \ No newline at end of file +Prebuilt form SuperTokens label + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/passwordless/common-customizations/styling/changing-style.mdx b/v2/passwordless/common-customizations/styling/changing-style.mdx index 0b8345234..314ed9c03 100644 --- a/v2/passwordless/common-customizations/styling/changing-style.mdx +++ b/v2/passwordless/common-customizations/styling/changing-style.mdx @@ -2,14 +2,18 @@ id: changing-style title: Changing Style via CSS hide_title: true +show_ui_switcher: true --- import { PasswordlessFrontendForm } from "/src/components/snippetConfigForm/passwordlessFrontendForm"; -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Changing Style via CSS + + Updating the CSS allows you to change the UI of our components to meet your needs. @@ -28,7 +32,7 @@ Each stylable components contains `data-supertokens` attributes (in our example Let's customize elements with the `button` attribute. The syntax for styling is plain CSS. - + ```tsx @@ -54,7 +58,35 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + // highlight-start + style: ` + [data-supertokens~=button] { + background-color: #252571; + border: 0px; + width: 30%; + margin: 0 auto; + } + `, + // highlight-end + recipeList: [ /* ... */] +}); +``` + + + The above will result in: @@ -64,7 +96,7 @@ The above will result in: By default, SuperTokens uses the Arial font. The best way to override this is to add a `font-family` styling to the `container` component in the recipe configuration. - + ```tsx @@ -85,13 +117,35 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + style: ` + [data-supertokens~=container] { + font-family: cursive; + } + `, + recipeList: [ /* ... */] +}); +``` + + ### Using media queries You may want to have different CSS for different viewports. This can be achieved via media queries like this: - + ```tsx @@ -121,13 +175,45 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + style: ` + [data-supertokens~=button] { + background-color: #252571; + border: 0px; + width: 30%; + margin: 0 auto; + } + + @media (max-width: 440px) { + [data-supertokens~=button] { + width: 90%; + } + } + `, + recipeList: [ /* ... */], +}); +``` + + + ## Customising the Sign-Up / Sign-In form These are the screens shown when the user tries to log in or sign up for the application. - + ```tsx @@ -146,13 +232,34 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + style: `[data-supertokens~=authPage] { + ... + }`, + recipeList: [ /* ... */] +}); +``` + + + ### OTP input screen This screen is shown if your users are logging in by typing an OTP - + ```tsx @@ -180,14 +287,43 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIPasswordless.init({ + contactMethod: "EMAIL_OR_PHONE", // This example will work with any contactMethod. + // highlight-start + signInUpFeature: { + userInputCodeFormStyle: ` ... ` + } + // highlight-end + }), + supertokensUISession.init() + ] +}); +``` + + ### Link sent screen This screen is shown if your users can only log in via a magic link. - + ```tsx @@ -215,13 +351,42 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIPasswordless.init({ + contactMethod: "EMAIL_OR_PHONE", // This example will work with any contactMethod. + // highlight-start + signInUpFeature: { + linkSentScreenStyle: ` ... ` + } + // highlight-end + }), + supertokensUISession.init() + ] +}); +``` + + ## Customizing the Magic Link Clicked Screen This screen is shown when the user clicks a magic link. - + ```tsx @@ -249,4 +414,44 @@ SuperTokens.init({ }); ``` - \ No newline at end of file + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIPasswordless.init({ + contactMethod: "EMAIL_OR_PHONE", // This example will work with any contactMethod. + // highlight-start + linkClickedScreenFeature: { + style: ` ... ` + } + // highlight-end + }), + supertokensUISession.init() + ] +}); +``` + + + + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/passwordless/common-customizations/styling/shadow-dom.mdx b/v2/passwordless/common-customizations/styling/shadow-dom.mdx index deac5d8e9..eb9077930 100644 --- a/v2/passwordless/common-customizations/styling/shadow-dom.mdx +++ b/v2/passwordless/common-customizations/styling/shadow-dom.mdx @@ -2,20 +2,30 @@ id: shadow-dom title: Disable use of shadow DOM hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" + + + +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Disable use of shadow DOM + + + We use [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) to prevent CSS clashes between your CSS and the ones we provide. This guarantees that all our UI will render as expected. -However, this means that you cannot override our CSS using your CSS (though you can [use JS to do that](./changing-style)). +However, this has a few problems: +- You cannot override our CSS using your CSS (though you can [use JS to do that](./changing-style)). +- Password managers may not work for your end user. If you want to disable use of shadow dom, you can do so like: - + ```tsx @@ -28,13 +38,42 @@ SuperTokens.init({ websiteDomain: "..." }, // highlight-next-line - useShadowDom: true, - recipeList: [ /* recipe list */] + useShadowDom: false, + recipeList: [/* ... */] }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + // highlight-next-line + useShadowDom: false, + recipeList: [/* ... */] +}); +``` + + :::caution If disabled, please be sure to check that our components render correctly - because your CSS might affect our components' UI (the other way around won't happen). -::: \ No newline at end of file +::: + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/passwordless/common-customizations/translations.mdx b/v2/passwordless/common-customizations/translations.mdx index 1f1e226ed..438c0c948 100644 --- a/v2/passwordless/common-customizations/translations.mdx +++ b/v2/passwordless/common-customizations/translations.mdx @@ -2,16 +2,18 @@ id: translations title: Language Translation for the UI hide_title: true +show_ui_switcher: true --- - - -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs"; +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; -import NpmOrScriptTabs from "/src/components/tabs/NpmOrScriptTabs" +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Language Translation for the UI + + + You can translate the UI using two main methods: 1. You can override all displayed translation strings by providing translated versions for different languages (and even change the default English version). 2. You can provide a translation function to integrate supertokens with your preferred internationalization library. @@ -27,7 +29,7 @@ You can provide translations for each segment displayed in our UIs. - You can find the passwordless login UI keys [here](https://github.com/supertokens/supertokens-auth-react/blob/master/lib/ts/recipe/passwordless/components/themes/translations.ts). ::: - + ```tsx @@ -72,13 +74,58 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +supertokensUIInit({ + // highlight-start + languageTranslations: { // This object contains all translation related options + translations: { // These are the displayed translation strings for each language + // The property names define the language code of the translations + en: { + // Here each key is a translation key and the value is the string that will be displayed + // Setting the value to undefined will either display the translation from the default language or the translation key + BRANDING_POWERED_BY_START: "We ❤️ ", + // If you added a custom label or placeholder you can also provide translation for them if necessary + // You can also use these to provide translations for your component overrides + MY_CUSTOM_LABEL: "Age", + }, + hu: { + BRANDING_POWERED_BY_START: "Sok szeretettel: ", + // This key is associated with an empty string by default, but you can override these as well. + BRANDING_POWERED_BY_END: " 😊", + } + }, + /* + * This optional property sets the default and fallback language. + * It can be any string that will be used to fetch translations from the above object. + * Defaults to "en" + */ + defaultLanguage: "hu", + }, + // highlight-end + appInfo: { + appName: "...", + apiDomain: "...", + websiteDomain: "...", + }, + recipeList: [ + // ... + ], +}); +``` + + + ### Loading translations After initialization, you can provide additional translation data by calling the `SuperTokens.loadTranslation`. This can be useful if you are loading them asynchronously. - + ```tsx @@ -93,13 +140,28 @@ SuperTokens.loadTranslation({ }); ``` - + + + +```tsx +import supertokensUI from "supertokens-auth-react-script"; +// This method takes an object as a parameter, which is structured the same as above. +// This will be merged into the existing definitions, so any properties missing here won't remove them from the already loaded translations +supertokensUI.loadTranslation({ + en: { + BRANDING_POWERED_BY_END: " :)", + } +}); +``` + + + ### Changing the current language You can update which translations store is displayed by calling the `SuperTokens.changeLanguage`. - + ```tsx @@ -108,7 +170,16 @@ import SuperTokens from "supertokens-auth-react"; SuperTokens.changeLanguage("hu"); ``` - + + + +```tsx +import supertokensUI from "supertokens-auth-react-script"; +supertokensUI.changeLanguage("hu"); +``` + + + ## Using an internationalization library @@ -116,7 +187,7 @@ You can easily integrate SuperTokens with your internationalization library of c 1. Provide the translation function in `SuperTokens.init` - + ```tsx @@ -143,7 +214,34 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +supertokensUIInit({ + // highlight-start + languageTranslations: { + translationFunc: (key: string) => { + // The string returned by this function will be displayed + return key + "!"; + }, + }, + // highlight-end + appInfo: { + appName: "...", + apiDomain: "...", + websiteDomain: "...", + }, + recipeList: [ + // ... + ], +}); +``` + + + 2. Call `SuperTokens.changeLanguage` or `SuperTokens.loadTranslation` to re-render the translated UI @@ -157,7 +255,7 @@ If the SDK can't find a segment in the current language's translation store, we The currently chosen language is stored in a cookie, this way it can be restored the next time the page loads. The domain of this cookie can be customized through the `currentLanguageCookieScope` option. This can be useful if you are running our SDK in multiple applications and want to share the language choice between sub-domains. - + ```tsx @@ -181,13 +279,37 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +supertokensUIInit({ + // highlight-start + languageTranslations: { + currentLanguageCookieScope: ".example.com", + }, + // highlight-end + appInfo: { + appName: "...", + apiDomain: "...", + websiteDomain: "...", + }, + recipeList: [ + // ... + ], +}); +``` + + + ## Translations in component overrides The SDK also exports the `useTranslation` React hook you can use while overriding components. It returns a function that takes a translation segment key and returns it translated to the currently selected language. For more information on what translation keys you should use and the exact syntax, please see the original source code of the component you are overriding. - + ```tsx @@ -207,4 +329,24 @@ export const HeaderOverride = () => { ``` - \ No newline at end of file + + + +:::caution +Not applicable for non react apps. +::: + + + + + + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/passwordless/pre-built-ui/auth-redirection.mdx b/v2/passwordless/pre-built-ui/auth-redirection.mdx index 319295e7e..ed93e37c6 100644 --- a/v2/passwordless/pre-built-ui/auth-redirection.mdx +++ b/v2/passwordless/pre-built-ui/auth-redirection.mdx @@ -50,6 +50,47 @@ SuperTokens.init({ }); ``` + + + + +By default, the user is redirected the the `/` route on your website post login. To change this, you can use the `getRedirectionURL` function on the frontend as shown below: + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + // highlight-start + getRedirectionURL: async (context) => { + if (context.action === "SUCCESS" && context.newSessionCreated) { + if (context.redirectToPath !== undefined) { + // we are navigating back to where the user was before they authenticated + return context.redirectToPath; + } + if (context.createdNewUser) { + // user signed up + } else { + // user signed in + } + return "/dashboard"; + } + return undefined; + }, + // highlight-end + recipeList: [ /* Recipe list */] +}); +``` + + + + + The user will be redirected to the provided URL on: - Successful sign up. - Successful sign in. @@ -62,9 +103,6 @@ If you want to redirect the user to a different domain, then you can do so by fi Please refer to [this page](../advanced-customizations/frontend-hooks/redirection-callback) to learn more about the `getRedirectionURL` hook. ::: - - - ## Redirect user to the login page @@ -100,12 +138,10 @@ function NavBar () { -Use the `redirectToAuth({show?: "signin" | "signup", redirectBack?: boolean}?)` function to redirect the user to the login screen. For example, you may want to call this function when the user clicks on the login button. +Redirect the user to the `/auth` (this is the default path for the pre built UI) ```ts import { Component } from "@angular/core"; -// highlight-next-line -import { redirectToAuth } from "supertokens-auth-react"; @Component({ selector: 'nav-bar', @@ -120,20 +156,20 @@ import { redirectToAuth } from "supertokens-auth-react"; export class NavBarComponent { async onLogin () { // highlight-next-line - redirectToAuth(); + window.location.href = "/auth?show=signin&redirecToPath=" + encodeURIComponent(window.location.pathname); } } ``` -- Call `redirectToAuth({show: "signin"})` to take them to the sign in screen -- Call `redirectToAuth({show: "signup"})` to take them to the sign up screen -- If you do not want the user to be redirected to the current page post sign in, use `redirectToAuth({redirectBack: false})` +- Set `show=signin` to take them to the sign in screen +- Set `show=signup` to take them to the sign up screen +- Set `redirecToPath` to redirect the user to a specific page after they have signed in, or you can skip it to take them to the `/` route (which is the default one). -Use the `redirectToAuth({show?: "signin" | "signup", redirectBack?: boolean}?)` function to redirect the user to the login screen. For example, you may want to call this function when the user clicks on the login button. +Redirect the user to the `/auth` (this is the default path for the pre built UI) ```html ``` -- Call `redirectToAuth({show: "signin"})` to take them to the sign in screen -- Call `redirectToAuth({show: "signup"})` to take them to the sign up screen -- If you do not want the user to be redirected to the current page post sign in, use `redirectToAuth({redirectBack: false})` +- Set `show=signin` to take them to the sign in screen +- Set `show=signup` to take them to the sign up screen +- Set `redirecToPath` to redirect the user to a specific page after they have signed in, or you can skip it to take them to the `/` route (which is the default one). diff --git a/v2/passwordless/pre-built-ui/enable-email-verification.mdx b/v2/passwordless/pre-built-ui/enable-email-verification.mdx index bfc40b2bf..8810f910f 100644 --- a/v2/passwordless/pre-built-ui/enable-email-verification.mdx +++ b/v2/passwordless/pre-built-ui/enable-email-verification.mdx @@ -213,6 +213,33 @@ function App() { + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + // highlight-start + supertokensUIEmailVerification.init({ + mode: "REQUIRED", // or "OPTIONAL" + }), + // highlight-end + supertokensUISession.init(), + ], +}); +``` + + + @@ -736,8 +763,8 @@ If all validations pass, we render the `props.children` component. ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { EmailVerificationClaim } from "supertokens-auth-react/recipe/emailverification"; +import Session from "supertokens-web-js/recipe/session"; +import { EmailVerificationClaim } from "supertokens-web-js/recipe/emailverification"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { diff --git a/v2/passwordless/pre-built-ui/handling-session-tokens.mdx b/v2/passwordless/pre-built-ui/handling-session-tokens.mdx index 6d37e05ca..11f2460fa 100644 --- a/v2/passwordless/pre-built-ui/handling-session-tokens.mdx +++ b/v2/passwordless/pre-built-ui/handling-session-tokens.mdx @@ -61,7 +61,15 @@ async function getToken(): Promise { -~COPY-TABS=reactjs +```tsx +import Session from "supertokens-web-js/recipe/session"; + +async function getToken(): Promise { + // highlight-next-line + const accessToken = await Session.getAccessToken(); + console.log(accessToken); +} +``` diff --git a/v2/passwordless/pre-built-ui/securing-routes.mdx b/v2/passwordless/pre-built-ui/securing-routes.mdx index 4df26e055..22d56941e 100644 --- a/v2/passwordless/pre-built-ui/securing-routes.mdx +++ b/v2/passwordless/pre-built-ui/securing-routes.mdx @@ -490,7 +490,7 @@ class App extends React.Component { You can use the `doesSessionExist` function to check if a session exists in all your routes. ```tsx -import Session from 'supertokens-auth-react/recipe/session'; +import Session from 'supertokens-web-js/recipe/session'; async function doesSessionExist() { if (await Session.doesSessionExist()) { diff --git a/v2/passwordless/pre-built-ui/setup/frontend.mdx b/v2/passwordless/pre-built-ui/setup/frontend.mdx index 72027715c..baf8a64fb 100644 --- a/v2/passwordless/pre-built-ui/setup/frontend.mdx +++ b/v2/passwordless/pre-built-ui/setup/frontend.mdx @@ -15,6 +15,7 @@ import {Question, Answer}from "/src/components/question" import AppInfoForm from "/src/components/appInfoForm" import RRDVersionSubTabs from "/src/components/tabs/RRDVersionSubTabs" import NpmVersionOrYarnSubTabs from "/src/components/tabs/NpmVersionOrYarnSubTabs" +import PreBuiltUIInjector from "/src/components/prebuiltuiInjector" # Frontend Integration @@ -72,58 +73,35 @@ yarn add supertokens-auth-react supertokens-web-js -:::important -SuperTokens does not provide Angular components for pre built UI, but, there are two ways of implementing SuperTokens in your Angular frontend: -- Load SuperTokens's pre-built React UI components in your Angular app. Continue following the guide for this flow. -- Build your own UI. Click [here](../../custom-ui/init/frontend) to learn more. -::: - -Start by installing the SuperTokens ReactJS SDK and React: +Start by installing the SuperTokens Web SDK: ```bash -npm i -s supertokens-auth-react +npm i -s supertokens-web-js ``` -:::important -SuperTokens does not provide Angular components for pre built UI, but, there are two ways of implementing SuperTokens in your Angular frontend: -- Load SuperTokens's pre-built React UI components in your Angular app. Continue following the guide for this flow. -- Build your own UI. Click [here](../../custom-ui/init/frontend) to learn more. -::: -Start by installing the SuperTokens ReactJS SDK and React: +Start by installing the SuperTokens Web SDK: ```bash -npm i -s supertokens-auth-react supertokens-web-js +npm i -s supertokens-web-js ``` -:::important -SuperTokens does not provide Angular components for pre built UI, but, there are two ways of implementing SuperTokens in your Angular frontend: -- Load SuperTokens's pre-built React UI components in your Angular app. Continue following the guide for this flow. -- Build your own UI. Click [here](../../custom-ui/init/frontend) to learn more. -::: -Start by installing the SuperTokens ReactJS SDK and React: +Start by installing the SuperTokens Web SDK: ```bash -yarn add supertokens-auth-react supertokens-web-js +yarn add supertokens-web-js ``` -You will also need to update `compilerOptions` in your `tsconfig.json` file with the following: - -```json title="tsconfig.json" -"jsx": "react", -"allowSyntheticDefaultImports": true, -``` - @@ -131,46 +109,30 @@ You will also need to update `compilerOptions` in your `tsconfig.json` file with -:::important -SuperTokens does not provide Vue components for pre built UI, but, there are two ways of implementing SuperTokens in your Vue frontend: -- Load SuperTokens's pre-built React UI components in your Vue app. Continue following the guide for this flow. -- Build your own UI. Click [here](../../custom-ui/init/frontend) to learn more. -::: - -Start by installing the SuperTokens ReactJS SDK and React: +Start by installing the SuperTokens web SDK: ```bash -npm i -s supertokens-auth-react +npm i -s supertokens-web-js ``` -:::important -SuperTokens does not provide Vue components for pre built UI, but, there are two ways of implementing SuperTokens in your Vue frontend: -- Load SuperTokens's pre-built React UI components in your Vue app. Continue following the guide for this flow. -- Build your own UI. Click [here](../../custom-ui/init/frontend) to learn more. -::: -Start by installing the SuperTokens ReactJS SDK and React: +Start by installing the SuperTokens web SDK: ```bash -npm i -s supertokens-auth-react supertokens-web-js +npm i -s supertokens-web-js ``` -:::important -SuperTokens does not provide Vue components for pre built UI, but, there are two ways of implementing SuperTokens in your Vue frontend: -- Load SuperTokens's pre-built React UI components in your Vue app. Continue following the guide for this flow. -- Build your own UI. Click [here](../../custom-ui/init/frontend) to learn more. -::: -Start by installing the SuperTokens ReactJS SDK and React: +Start by installing the SuperTokens web SDK: ```bash -yarn add supertokens-auth-react supertokens-web-js +yarn add supertokens-web-js ``` @@ -254,14 +216,16 @@ class App extends React.Component { askForAPIDomain askForWebsiteDomain> + + -Before we initialize the `supertokens-auth-react` SDK let's see how we will use it in our Angular app +Before we initialize the `supertokens-web-js` SDK let's see how we will use it in our Angular app **Architecture** -- The `supertokens-auth-react` SDK is responsible for rendering the login UI, handling authentication flows and session management. -- Using `supertokens-auth-react`'s pre-built UI does not increase application's bundle size. React is only added to authentication-related routes. +- The `supertokens-web-js` SDK is responsible for session management and providing helper functions to check if a session exists, or validate the access token claims on the frontend (for example, to check for user roles before showing some UI). We will initialise this SDK on the root of your Angular app, so that all pages in your app can use it. +- We will create a `^{form_websiteBasePath}*` route in the Angular app which will render our pre built UI which will also need to be initialised, but only on that route. **Creating the `^{form_websiteBasePath}` route** @@ -271,98 +235,88 @@ Before we initialize the `supertokens-auth-react` SDK let's see how we will use ng generate module auth --route auth --module app.module ``` -- In your `auth` component folder create a react component `supertokensAuthComponent.tsx`. This component will be used to render appropriate UI when user visits the login page. - - ```tsx title="/app/auth/supertokensAuthComponent.tsx" - import * as React from "react"; - import * as SuperTokens from "supertokens-auth-react"; - import {canHandleRoute, getRoutingComponent} from "supertokens-auth-react/ui"; - ^{prebuiltuiimport} - - // highlight-start - class SuperTokensReactComponent extends React.Component { - override render() { - if (canHandleRoute([^{recipePreBuiltUINameCapitalLetters}])) { - return getRoutingComponent([^{recipePreBuiltUINameCapitalLetters}]); - } - return "Route not found"; - } - } - // highlight-end - - export default SuperTokensReactComponent; - ``` - -- Load `superTokensAuthComponent` in the `auth` angular component +- Add the following code to your `auth` angular component ```tsx title="/app/auth/auth.component.ts" - import { AfterViewInit, Component, OnDestroy } from "@angular/core"; - import * as React from "react"; - import * as ReactDOM from "react-dom"; - // @ts-ignore - import SuperTokensReactComponent from "./supertokensAuthComponent.tsx"; + import {init as supertokensUIInit} from "supertokens-auth-react-script"; + import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless"; + import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + import { Component, OnDestroy, AfterViewInit, Renderer2, Inject } from "@angular/core"; + import { DOCUMENT } from "@angular/common"; @Component({ selector: "app-auth", - template: '
', + template: '
', }) - export class AuthComponent implements AfterViewInit, OnDestroy { - title = "angularreactapp"; + export class AuthComponent implements OnDestroy, AfterViewInit { - public rootId = "rootId"; + constructor( + private renderer: Renderer2, + @Inject(DOCUMENT) private document: Document + ) { } - // highlight-start - // We use the ngAfterViewInit lifecycle hook to render the React component after the Angular component view gets initialized ngAfterViewInit() { - ReactDOM.render(React.createElement(SuperTokensReactComponent), document.getElementById(this.rootId)); + this.loadScript('^{jsdeliver_prebuiltui}'); } - // We use the ngOnDestroy lifecycle hook to unmount the React component when the Angular wrapper component is destroyed. ngOnDestroy() { - ReactDOM.unmountComponentAtNode(document.getElementById(this.rootId) as Element); + // Remove the script when the component is destroyed + const script = this.document.getElementById('supertokens-script'); + if (script) { + script.remove(); + } + } + + private loadScript(src: string) { + const script = this.renderer.createElement('script'); + script.type = 'text/javascript'; + script.src = src; + script.id = 'supertokens-script'; + script.onload = () => { + supertokensUIInit({ + appInfo: { + appName: "^{form_appName}", + apiDomain: "^{form_apiDomain}", + websiteDomain: "^{form_websiteDomain}", + apiBasePath: "^{form_apiBasePath}", + websiteBasePath: "^{form_websiteBasePath}" + }, + recipeList: [ + supertokensUIPasswordless.init({ + contactMethod: "^{form_contactMethod}" + }), + supertokensUISession.init(), + ], + }); + } + this.renderer.appendChild(this.document.body, script); } - // highlight-end } ``` + - In the `loadScript` function, we provide the SuperTokens config for the UI. We add the passwordless and session recipes. -- Initialize the `supertokens-auth-react` SDK in your angular app's root component. This will provide session management across your entire application. - - ```tsx title="/app/app.component.ts " - import { Component } from "@angular/core"; - - import * as SuperTokens from "supertokens-auth-react"; - import * as Passwordless from "supertokens-auth-react/recipe/passwordless"; - import Session from "supertokens-auth-react/recipe/session"; +- Initialize the `supertokens-web-js` SDK in your angular app's root component. This will provide session management across your entire application. + ```tsx title="/app/app.component.ts " + import SuperTokens from "supertokens-web-js"; + import Session from "supertokens-web-js/recipe/session"; + SuperTokens.init({ - // highlight-start appInfo: { appName: "^{form_appName}", apiDomain: "^{form_apiDomain}", - websiteDomain: "^{form_websiteDomain}", apiBasePath: "^{form_apiBasePath}", - websiteBasePath: "^{form_websiteBasePath}" }, recipeList: [ - Passwordless.init({ - contactMethod: "^{form_contactMethod}" - }), Session.init(), ], - // highlight-end }); - - @Component({ - selector: "app-root", - template: "", - }) - export class AppComponent { - title = "^{form_appName}"; - } ``` + + @@ -374,92 +328,94 @@ Before we initialize the `supertokens-auth-react` SDK let's see how we will use askForAPIDomain askForWebsiteDomain> + + -Before we initialize the `supertokens-auth-react` SDK let's see how we will use it in our Vue app +Before we initialize the `supertokens-web-js` SDK let's see how we will use it in our Vue app **Architecture** -- The `supertokens-auth-react` SDK is responsible for rendering the login UI, handling authentication flows and session management. -- Using `supertokens-auth-react`'s pre-built UI does not increase application's bundle size. React is only added to authentication-related routes. +- The `supertokens-web-js` SDK is responsible for session management and providing helper functions to check if a session exists, or validate the access token claims on the frontend (for example, to check for user roles before showing some UI). We will initialise this SDK on the root of your Vue app, so that all pages in your app can use it. +- We will create a `^{form_websiteBasePath}*` route in the Vue app which will render our pre built UI which will also need to be initialised, but only on that route. **Creating the `^{form_websiteBasePath}` route** -- Create a new file `AuthView.vue`, this Vue component will be used to render the auth component - -- Create a React component `Supertokens.tsx`. This component will be used to render appropriate UI when user visits the login page. - - ```tsx title="/components/Supertokens.tsx" - import * as SuperTokens from "supertokens-auth-react"; - import { canHandleRoute, getRoutingComponent } from "supertokens-auth-react/ui"; - ^{prebuiltuiimport} - - // highlight-start - function SuperTokensReactComponent(props: any) { - if (canHandleRoute([^{recipePreBuiltUINameCapitalLetters}])) { - return getRoutingComponent([^{recipePreBuiltUINameCapitalLetters}]); - } - return "Route not found"; - } - // highlight-end - - export default SuperTokensReactComponent; - ``` - -- Load `SuperTokensReactComponent` in the `AuthView.vue` component - - ```html title="/views/AuthView.vue" +- Create a new file `AuthView.vue`, this Vue component will be used to render the auth component: + ```tsx + import {init as supertokensUIInit} from "supertokens-auth-react-script"; + import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless"; + import supertokensUISession from "supertokens-auth-react-script/recipe/session"; ``` + - In the `loadScript` function, we provide the SuperTokens config for the UI. We add the passwordless and session recipes. -- Initialize the `supertokens-auth-react` SDK in your Vue app's `main.ts` file. This will provide session management across your entire application. +- Initialize the `supertokens-web-js` SDK in your Vue app's `main.ts` file. This will provide session management across your entire application. ```tsx title="/main.ts " // @ts-ignore import { createApp } from "vue"; - import * as SuperTokens from "supertokens-auth-react"; - import * as Passwordless from "supertokens-auth-react/recipe/passwordless"; - import Session from "supertokens-auth-react/recipe/session"; - + import SuperTokens from "supertokens-web-js"; + import Session from "supertokens-web-js/recipe/session"; // @ts-ignore import App from "./App.vue"; // @ts-ignore import router from "./router"; SuperTokens.init({ - // highlight-start appInfo: { appName: "^{form_appName}", apiDomain: "^{form_apiDomain}", - websiteDomain: "^{form_websiteDomain}", apiBasePath: "^{form_apiBasePath}", - websiteBasePath: "^{form_websiteBasePath}" }, recipeList: [ - Passwordless.init({ - contactMethod: "^{form_contactMethod}" - }), Session.init(), ], - // highlight-end }); const app = createApp(App); @@ -467,9 +423,13 @@ Before we initialize the `supertokens-auth-react` SDK let's see how we will use app.use(router); app.mount("#app"); + ``` + + + @@ -659,6 +619,8 @@ Update your Vue router so that all auth related requests load the `AuthView` com import { createRouter, createWebHistory } from "vue-router"; // @ts-ignore import HomeView from "../views/HomeView.vue"; +// @ts-ignore +import AuthView from "../views/AuthView.vue"; const router = createRouter({ // @ts-ignore @@ -672,8 +634,7 @@ const router = createRouter({ { path: "^{form_websiteBasePath}/:pathMatch(.*)*", name: "auth", - // @ts-ignore - component: () => import("../views/AuthView.vue"), + component: AuthView, }, ], }); diff --git a/v2/passwordless/pre-built-ui/sign-out.mdx b/v2/passwordless/pre-built-ui/sign-out.mdx index 8b25a1f07..799748faa 100644 --- a/v2/passwordless/pre-built-ui/sign-out.mdx +++ b/v2/passwordless/pre-built-ui/sign-out.mdx @@ -42,11 +42,11 @@ function NavBar() { -The [`signOut` method](https://supertokens.com/docs/auth-react/modules/recipe_session.html#signOut-1) revokes the session for the user. +The [`signOut` method](https://supertokens.com/docs/web-js/modules/recipe_session.html#signOut-1) revokes the session for the user. ```tsx // highlight-next-line -import Session from "supertokens-auth-react/recipe/session"; +import Session from "supertokens-web-js/recipe/session"; async function logout () { // highlight-next-line diff --git a/v2/passwordless/troubleshooting/how-to-troubleshoot.mdx b/v2/passwordless/troubleshooting/how-to-troubleshoot.mdx index 41507a865..901aaa4d7 100644 --- a/v2/passwordless/troubleshooting/how-to-troubleshoot.mdx +++ b/v2/passwordless/troubleshooting/how-to-troubleshoot.mdx @@ -132,6 +132,45 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + // highlight-next-line + enableDebugLogs: true, + // @ts-ignore + appInfo: { /*...*/ }, + // @ts-ignore + recipeList: [/*...*/] +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from 'supertokens-web-js'; +import Session from 'supertokens-web-js/recipe/session'; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + Session.init(), + ], + // highlight-next-line + enableDebugLogs: true, +}); +``` + + + diff --git a/v2/passwordless/user-roles/protecting-routes.mdx b/v2/passwordless/user-roles/protecting-routes.mdx index b3ea9478d..58c95e15f 100644 --- a/v2/passwordless/user-roles/protecting-routes.mdx +++ b/v2/passwordless/user-roles/protecting-routes.mdx @@ -1224,8 +1224,8 @@ function ProtectedComponent() { ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { @@ -1268,8 +1268,8 @@ async function shouldLoadRoute(): Promise { If you want to have more complex access control, you can get the roles list from the session as follows, and check the list yourself: ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { diff --git a/v2/session/advanced-customizations/frontend-functions-override/usage.mdx b/v2/session/advanced-customizations/frontend-functions-override/usage.mdx index ea787c1c9..6d6b5083e 100644 --- a/v2/session/advanced-customizations/frontend-functions-override/usage.mdx +++ b/v2/session/advanced-customizations/frontend-functions-override/usage.mdx @@ -65,6 +65,89 @@ SuperTokens.init({ + + +:::info +See all the [functions that can be overrided here](https://supertokens.com/docs/auth-react/modules/recipe_session.html#RecipeInterface) +::: + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUISession.init({ + // highlight-start + override: { + functions: (originalImplementation) => { + return { + ...originalImplementation, + + // we will only be overriding the function for checking + // if a session exists + doesSessionExist: async function (input) { + // TODO: some custom logic + + // or call the default behaviour as show below + return originalImplementation.doesSessionExist(input); + } + } + } + } + // highlight-end + }) + ] +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from 'supertokens-web-js'; +import Session from 'supertokens-web-js/recipe/session'; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + Session.init({ + // highlight-start + override: { + functions: (originalImplementation) => { + return { + ...originalImplementation, + doesSessionExist: async function (input) { + // TODO: some custom logic + + // or call the default behaviour as show below + return originalImplementation.doesSessionExist(input); + }, + // ... + // TODO: override more functions + } + } + } + // highlight-end + }), + ], +}); +``` + + + - `originalImplementation` is an object that contains functions that has the original implementation for this recipe. It can be used in your functions as a way to use the SuperTokens' default behaviour. diff --git a/v2/session/advanced-customizations/frontend-hooks/handle-event.mdx b/v2/session/advanced-customizations/frontend-hooks/handle-event.mdx index fa3b8c04e..a4013a16c 100644 --- a/v2/session/advanced-customizations/frontend-hooks/handle-event.mdx +++ b/v2/session/advanced-customizations/frontend-hooks/handle-event.mdx @@ -59,6 +59,91 @@ Session.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUISession.init({ + onHandleEvent: (context) => { + if (context.action === "SIGN_OUT") { + // called when the user clicks on sign out + } else if (context.action === "REFRESH_SESSION") { + // called with refreshing a session + // NOTE: This is an undeterministic event + } else if (context.action === "UNAUTHORISED") { + // called when the user doesn't have a valid session but made a request that requires one + // NOTE: This event can fire multiple times + + if (context.sessionExpiredOrRevoked) { + // the sessionExpiredOrRevoked property is set to true if the current call cleared the session from storage + // this happens only once, even if multiple tabs sharing the same session are open, making it useful for analytics purposes + } + } else if (context.action === "SESSION_CREATED") { + // Called when session is created - post login / sign up. + } else if (context.action === "ACCESS_TOKEN_PAYLOAD_UPDATED") { + // This is called when the access token payload has been updated + } else if (context.action === "API_INVALID_CLAIM") { + // This is called when the access token payload has an invalid claim + // as per one of the validators on the frontend + } else if (context.action === "SESSION_ALREADY_EXISTS") { + // called when a user visits the login / sign up page with a valid session + // in this case, they are usually redirected to the main app + } + } +}) +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from "supertokens-web-js"; +import Session from "supertokens-web-js/recipe/session"; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + Session.init({ + onHandleEvent: (context) => { + if (context.action === "SIGN_OUT") { + // called when the user clicks on sign out + } else if (context.action === "REFRESH_SESSION") { + // called with refreshing a session + // NOTE: This is an undeterministic event + } else if (context.action === "UNAUTHORISED") { + // called when the user doesn't have a valid session but made a request that requires one + // NOTE: This event can fire multiple times + + if (context.sessionExpiredOrRevoked) { + // the sessionExpiredOrRevoked property is set to true if the current call cleared the session from storage + // this happens only once, even if multiple tabs sharing the same session are open, making it useful for analytics purposes + } + } else if (context.action === "SESSION_CREATED") { + // Called when session is created - post login / sign up. + } else if (context.action === "ACCESS_TOKEN_PAYLOAD_UPDATED") { + // This is called when the access token payload has been updated + } else if (context.action === "API_INVALID_CLAIM") { + // This is called when the access token payload has an invalid claim + // as per one of the validators + } else if (context.action === "SESSION_ALREADY_EXISTS") { + // called when a user visits the login / sign up page with a valid session + // in this case, they are usually redirected to the main app + } + } + }), + ], +}) +``` + + + diff --git a/v2/session/advanced-customizations/frontend-hooks/pre-api.mdx b/v2/session/advanced-customizations/frontend-hooks/pre-api.mdx index a68a8565e..41ff02208 100644 --- a/v2/session/advanced-customizations/frontend-hooks/pre-api.mdx +++ b/v2/session/advanced-customizations/frontend-hooks/pre-api.mdx @@ -49,6 +49,71 @@ Session.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUISession.init({ + preAPIHook: async (context) => { + let url = context.url; + + // is the fetch config object that contains the header, body etc.. + let requestInit = context.requestInit; + + let action = context.action; + if (action === "SIGN_OUT") { + + } else if (action === "REFRESH_SESSION") { + + } + return { + requestInit, url + }; + } +}) +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from "supertokens-web-js"; +import Session from "supertokens-web-js/recipe/session"; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + Session.init({ + preAPIHook: async (context) => { + let url = context.url; + + // is the fetch config object that contains the header, body etc.. + let requestInit = context.requestInit; + + let action = context.action; + if (action === "SIGN_OUT") { + + } else if (action === "REFRESH_SESSION") { + + } + return { + requestInit, url + }; + } + }), + ], +}) +``` + + + diff --git a/v2/session/common-customizations/changing-base-path/api-base-path.mdx b/v2/session/common-customizations/changing-base-path/api-base-path.mdx index f7a1a28f7..04d981956 100644 --- a/v2/session/common-customizations/changing-base-path/api-base-path.mdx +++ b/v2/session/common-customizations/changing-base-path/api-base-path.mdx @@ -112,6 +112,45 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +supertokensUIInit({ + appInfo: { + appName: "yourAppName", + apiDomain: "yourApi", + websiteDomain: "yourWebsite", + // highlight-next-line + apiBasePath: "/api/v3/auth" + }, + recipeList: [], +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +// this goes in the root of your frontend app +import SuperTokens from "supertokens-web-js"; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + // highlight-next-line + apiBasePath: "/api/v3/auth", + appName: "...", + }, + recipeList: [/* ... */], +}); +``` + + + diff --git a/v2/session/common-customizations/changing-base-path/website-base-path.mdx b/v2/session/common-customizations/changing-base-path/website-base-path.mdx index 0795a935f..3e3e959bd 100644 --- a/v2/session/common-customizations/changing-base-path/website-base-path.mdx +++ b/v2/session/common-customizations/changing-base-path/website-base-path.mdx @@ -2,6 +2,7 @@ id: website-base-path title: Website Base Path hide_title: true +show_ui_switcher: true --- @@ -9,6 +10,7 @@ hide_title: true import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" import BackendSDKTabs from "/src/components/tabs/BackendSDKTabs" import BackendSDKCasing from "/src/components/BackendSDKCasing" import TabItem from '@theme/TabItem'; @@ -16,6 +18,10 @@ import TabItem from '@theme/TabItem'; # Website Base Path ## Step 1) Front End Change + + + + Since the beginning of this guide, you probably noticed that all the front-end routes for SuperTokens widget are prefixed by `/auth`. You can change this value in the `init` function by setting websiteBasePath. @@ -39,8 +45,36 @@ SuperTokens.init({ + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +supertokensUIInit({ + appInfo: { + appName: "yourAppName", + apiDomain: "yourApi", + websiteDomain: "yourWebsite", + // highlight-next-line + websiteBasePath: "/authentication" + }, + recipeList: [], +}); +``` + + + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + ## Step 2) Back End Change diff --git a/v2/session/common-customizations/sessions/claims/access-token-payload.mdx b/v2/session/common-customizations/sessions/claims/access-token-payload.mdx index 718acaf18..b1e59cb4e 100644 --- a/v2/session/common-customizations/sessions/claims/access-token-payload.mdx +++ b/v2/session/common-customizations/sessions/claims/access-token-payload.mdx @@ -1111,7 +1111,7 @@ async function someFunc() { ```tsx -import Session from 'supertokens-auth-react/recipe/session'; +import Session from 'supertokens-web-js/recipe/session'; async function someFunc() { if (await Session.doesSessionExist()) { diff --git a/v2/session/common-customizations/sessions/claims/claim-validators.mdx b/v2/session/common-customizations/sessions/claims/claim-validators.mdx index 8ffe6e207..2a7b59a42 100644 --- a/v2/session/common-customizations/sessions/claims/claim-validators.mdx +++ b/v2/session/common-customizations/sessions/claims/claim-validators.mdx @@ -856,8 +856,8 @@ Now whenever you wrap your component with the `` wrapper, SuperToke ```tsx -import SuperTokens from "supertokens-auth-react"; -import Session, { BooleanClaim } from 'supertokens-auth-react/recipe/session'; +import SuperTokens from "supertokens-web-js"; +import Session, { BooleanClaim } from 'supertokens-web-js/recipe/session'; const SecondFactorClaim = new BooleanClaim({ id: "2fa-completed", @@ -870,7 +870,6 @@ SuperTokens.init({ appInfo: { apiDomain: "...", appName: "...", - websiteDomain: "..." }, recipeList: [ //... @@ -894,7 +893,7 @@ SuperTokens.init({ Now you can protect your frontend routes by using the `Session.validateClaims` function as shown below: ```tsx -import Session, { BooleanClaim } from "supertokens-auth-react/recipe/session"; +import Session, { BooleanClaim } from "supertokens-web-js/recipe/session"; const SecondFactorClaim = new BooleanClaim({ id: "2fa-completed", @@ -2286,8 +2285,8 @@ Unlike using the `overrideGlobalClaimValidators` prop, the `useClaimValue` funct ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { @@ -2330,8 +2329,8 @@ async function shouldLoadRoute(): Promise { If you want to have more complex access control, you can get the roles list from the session as follows, and check the list yourself: ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { diff --git a/v2/session/common-customizations/sessions/disable-interception.mdx b/v2/session/common-customizations/sessions/disable-interception.mdx index 86082e96c..dd7eba4f5 100644 --- a/v2/session/common-customizations/sessions/disable-interception.mdx +++ b/v2/session/common-customizations/sessions/disable-interception.mdx @@ -58,6 +58,63 @@ Session.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUISession.init({ + override: { + functions: (oI) => { + return { + ...oI, + shouldDoInterceptionBasedOnUrl: (url, apiDomain, sessionTokenBackendDomain) => { + try { + let urlObj = new URL(url); + if (!urlObj.pathname.startsWith("/auth")) { + return false; + } + } catch (ignored) { } + return oI.shouldDoInterceptionBasedOnUrl(url, apiDomain, sessionTokenBackendDomain); + } + } + } + } +}) +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import Session from "supertokens-web-js/recipe/session"; + +Session.init({ + override: { + functions: (oI) => { + return { + ...oI, + shouldDoInterceptionBasedOnUrl: (url, apiDomain, sessionTokenBackendDomain) => { + try { + let urlObj = new URL(url); + if (!urlObj.pathname.startsWith("/auth")) { + return false; + } + } catch (ignored) { } + return oI.shouldDoInterceptionBasedOnUrl(url, apiDomain, sessionTokenBackendDomain); + } + } + } + } +}) +``` + + + diff --git a/v2/session/common-customizations/sessions/in-iframe.mdx b/v2/session/common-customizations/sessions/in-iframe.mdx index c7c068656..8cac1a3ca 100644 --- a/v2/session/common-customizations/sessions/in-iframe.mdx +++ b/v2/session/common-customizations/sessions/in-iframe.mdx @@ -69,6 +69,65 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; +declare let cookieHandler: any // typecheck-only, removed from output +declare let windowHandler: any // typecheck-only, removed from output + +supertokensUIInit({ + cookieHandler, + windowHandler, + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUISession.init({ + // highlight-start + tokenTransferMethod: "header", + isInIframe: true + // highlight-end + }) + ] +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from "supertokens-web-js"; +import Session from "supertokens-web-js/recipe/session"; +declare let cookieHandler: any // typecheck-only, removed from output +declare let windowHandler: any // typecheck-only, removed from output + +SuperTokens.init({ + cookieHandler, + windowHandler, + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + Session.init({ + // highlight-start + tokenTransferMethod: "header", + isInIframe: true + // highlight-end + }) + ], +}) +``` + + + @@ -84,8 +143,12 @@ SuperTokens.init({ ```tsx import SuperTokens from "supertokens-web-js"; import Session from "supertokens-web-js/recipe/session"; +declare let cookieHandler: any // typecheck-only, removed from output +declare let windowHandler: any // typecheck-only, removed from output SuperTokens.init({ + cookieHandler, + windowHandler, appInfo: { apiDomain: "...", appName: "...", @@ -107,7 +170,11 @@ SuperTokens.init({ ```tsx import supertokens from "supertokens-web-js-script"; import supertokensSession from "supertokens-web-js-script/recipe/session"; +declare let cookieHandler: any // typecheck-only, removed from output +declare let windowHandler: any // typecheck-only, removed from output supertokens.init({ + cookieHandler, + windowHandler, appInfo: { apiDomain: "...", appName: "...", diff --git a/v2/session/common-customizations/sessions/multiple-api-endpoints.mdx b/v2/session/common-customizations/sessions/multiple-api-endpoints.mdx index acabbe9f8..27cc1dc46 100644 --- a/v2/session/common-customizations/sessions/multiple-api-endpoints.mdx +++ b/v2/session/common-customizations/sessions/multiple-api-endpoints.mdx @@ -241,6 +241,51 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. +```tsx +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUISession.init({ + // highlight-next-line + sessionTokenBackendDomain: ".example.com" + }) + ] +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from 'supertokens-web-js'; +import Session from 'supertokens-web-js/recipe/session'; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + Session.init({ + sessionTokenBackendDomain: ".example.com" + }), + ], +}); +``` + + + diff --git a/v2/session/common-customizations/sessions/protecting-frontend-routes.mdx b/v2/session/common-customizations/sessions/protecting-frontend-routes.mdx index 13b1829bc..232bba79f 100644 --- a/v2/session/common-customizations/sessions/protecting-frontend-routes.mdx +++ b/v2/session/common-customizations/sessions/protecting-frontend-routes.mdx @@ -123,7 +123,7 @@ function MyDashboardComponent(props: any) { You can use the `doesSessionExist` function to check if a session exists in all your routes. ```tsx -import Session from 'supertokens-auth-react/recipe/session'; +import Session from 'supertokens-web-js/recipe/session'; async function doesSessionExist() { if (await Session.doesSessionExist()) { @@ -211,8 +211,8 @@ function ProtectedComponent() { ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { @@ -255,8 +255,8 @@ async function shouldLoadRoute(): Promise { If you want to have more complex access control, you can get the roles list from the session as follows, and check the list yourself: ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { diff --git a/v2/session/common-customizations/sessions/revoke-session.mdx b/v2/session/common-customizations/sessions/revoke-session.mdx index ffa1e8107..4eb5801bc 100644 --- a/v2/session/common-customizations/sessions/revoke-session.mdx +++ b/v2/session/common-customizations/sessions/revoke-session.mdx @@ -66,7 +66,7 @@ The [`signOut` method](https://supertokens.com/docs/web-js/modules/recipe_sessio ```tsx // highlight-next-line -import Session from "supertokens-auth-react/recipe/session"; +import Session from "supertokens-web-js/recipe/session"; async function logout () { // highlight-next-line diff --git a/v2/session/common-customizations/sessions/share-session-across-sub-domains.mdx b/v2/session/common-customizations/sessions/share-session-across-sub-domains.mdx index 9c95085ab..b0f863386 100644 --- a/v2/session/common-customizations/sessions/share-session-across-sub-domains.mdx +++ b/v2/session/common-customizations/sessions/share-session-across-sub-domains.mdx @@ -58,6 +58,56 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + // ... + // this should be equal to the domain where the user will see the login UI + apiDomain: "...", + appName: "...", + websiteDomain: "https://example.com" + }, + recipeList: [ + supertokensUISession.init({ + // highlight-next-line + sessionTokenFrontendDomain: ".example.com" + }) + ] +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from "supertokens-web-js"; +import Session from "supertokens-web-js/recipe/session"; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + Session.init({ + // highlight-start + sessionTokenFrontendDomain: ".example.com" + // highlight-end + }), + ], +}) +``` + + + :::caution diff --git a/v2/session/common-customizations/sessions/ssr.mdx b/v2/session/common-customizations/sessions/ssr.mdx index 268e74d03..da3f38224 100644 --- a/v2/session/common-customizations/sessions/ssr.mdx +++ b/v2/session/common-customizations/sessions/ssr.mdx @@ -83,7 +83,7 @@ export function AttemptRefresh(props: any) { ```tsx -import Session from 'supertokens-auth-react/recipe/session'; +import Session from 'supertokens-web-js/recipe/session'; function attemptRefresh() { Session.attemptRefreshingSession().then(success => { diff --git a/v2/session/common-customizations/sessions/token-transfer-method.mdx b/v2/session/common-customizations/sessions/token-transfer-method.mdx index d07b73456..05bf214db 100644 --- a/v2/session/common-customizations/sessions/token-transfer-method.mdx +++ b/v2/session/common-customizations/sessions/token-transfer-method.mdx @@ -71,6 +71,54 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUISession.init({ + // highlight-next-line + tokenTransferMethod: "header" // or "cookie" + }) + ] +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from "supertokens-web-js"; +import Session from "supertokens-web-js/recipe/session"; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + Session.init({ + // highlight-next-line + tokenTransferMethod: "header" // or "cookie" + }) + ], +}) +``` + + + diff --git a/v2/session/common-customizations/sessions/with-jwt/read-jwt.mdx b/v2/session/common-customizations/sessions/with-jwt/read-jwt.mdx index c81b227c0..34035905c 100644 --- a/v2/session/common-customizations/sessions/with-jwt/read-jwt.mdx +++ b/v2/session/common-customizations/sessions/with-jwt/read-jwt.mdx @@ -435,7 +435,7 @@ async function getJWT() { ```tsx -import Session from 'supertokens-auth-react/recipe/session'; +import Session from 'supertokens-web-js/recipe/session'; async function getJWT() { if (await Session.doesSessionExist()) { diff --git a/v2/session/troubleshooting/how-to-troubleshoot.mdx b/v2/session/troubleshooting/how-to-troubleshoot.mdx index 41507a865..901aaa4d7 100644 --- a/v2/session/troubleshooting/how-to-troubleshoot.mdx +++ b/v2/session/troubleshooting/how-to-troubleshoot.mdx @@ -132,6 +132,45 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + // highlight-next-line + enableDebugLogs: true, + // @ts-ignore + appInfo: { /*...*/ }, + // @ts-ignore + recipeList: [/*...*/] +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from 'supertokens-web-js'; +import Session from 'supertokens-web-js/recipe/session'; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + Session.init(), + ], + // highlight-next-line + enableDebugLogs: true, +}); +``` + + + diff --git a/v2/src/components/api/authReact.ts b/v2/src/components/api/authReact.ts new file mode 100644 index 000000000..f9f0e2168 --- /dev/null +++ b/v2/src/components/api/authReact.ts @@ -0,0 +1,14 @@ +import { API_URL } from "../constants"; +import * as httpNetworking from "../httpNetworking"; + +const URL = API_URL + "/frontend/auth-react"; +const VERSION = 0; + +export default async function getURI(): Promise<{ uri: string }> { + let options: httpNetworking.GETRequestConfig = { + timeout: 50000, + }; + + let response = (await httpNetworking.simpleGETRequest(URL, options, VERSION)).data; + return response; +} diff --git a/v2/src/components/prebuiltuiInjector/index.tsx b/v2/src/components/prebuiltuiInjector/index.tsx new file mode 100644 index 000000000..f7295ff16 --- /dev/null +++ b/v2/src/components/prebuiltuiInjector/index.tsx @@ -0,0 +1,78 @@ +import React, { PropsWithChildren } from "react"; +import { recursiveMap } from "../utils"; +import getURI from "../api/authReact"; +import { MOCK_ENABLED } from "../constants"; + + +type State = { + uri: string | undefined +}; + +export default class PrebuiltUIInjector extends React.PureComponent, State> { + + isUnmounting = false; + + constructor(props: PropsWithChildren<{}>) { + super(props); + this.state = { + uri: undefined + }; + } + + render() { + let result; + if (this.state.uri !== undefined) { + let uri = this.state.uri; + result = recursiveMap(this.props.children, (c: any) => { + if (typeof c === "string") { + c = c.split("^{jsdeliver_prebuiltui}").join(uri) + } + return c; + }); + } else { + result = recursiveMap(this.props.children, (c: any) => { + if (typeof c === "string") { + c = c.split("^{jsdeliver_prebuiltui}").join("") + } + return c; + }); + } + + return result; + } + + async componentDidMount() { + if (typeof window != 'undefined') { + if (MOCK_ENABLED) { + if (this.isUnmounting) { + return; + } + this.setState(oldState => { + return { + ...oldState, + uri: "https://cdn.jsdelivr.net/gh/supertokens/prebuiltui@vX.Y.Z/build/static/js/main.test.js" + }; + }) + } else { + try { + let uri = await getURI(); + if (this.isUnmounting) { + return; + } + this.setState(oldState => { + return { + ...oldState, + uri: uri.uri + }; + }) + } catch (err) { + console.error(err); + } + } + } + } + + componentWillUnmount() { + this.isUnmounting = true; + } +} \ No newline at end of file diff --git a/v2/src/components/tabs/FrontendPreBuiltUITabs.tsx b/v2/src/components/tabs/FrontendPreBuiltUITabs.tsx index ff93ffef5..e7bfe32a2 100644 --- a/v2/src/components/tabs/FrontendPreBuiltUITabs.tsx +++ b/v2/src/components/tabs/FrontendPreBuiltUITabs.tsx @@ -2,10 +2,8 @@ import React from "react"; let Tabs = require("@theme/Tabs").default; let TabItem = require("@theme/TabItem").default; import { childContainsTabItemWithValue } from "./utils"; -import { recursiveMapAllChildren } from "../utils"; -import AngularUIImplementation from "../reusableSnippets/angularUIImplementation"; import VueUIImplementation from "../reusableSnippets/vueUIImplementation"; -import { Answer } from "../question" +import { recursiveMapAllChildren } from "../utils"; const copyTabIdentifier = "~COPY-TABS="; @@ -17,9 +15,9 @@ export default function FrontendPreBuiltUITabs(props: any) { ]; if (props.showMobileTab !== undefined) { - values.push({ - label: "Mobile", - value: "mobile", + values.push({ + label: "Mobile", + value: "mobile", }); } @@ -72,29 +70,7 @@ function DefaultReactJSTabItem() { } function DefaultAngularTabItem() { - return ( - -
-
-
- - - - - - - Important -
-
-
- SuperTokens does not provide non-React UI components. So we will be using the supertokens-auth-react SDK and will inject the React components to show the UI. Therefore, the code snippet below refers to the supertokens-auth-react SDK. -
-
-
- ~COPY-TABS=reactjs -
- - ); + throw new Error("Should never come here cause we add angular tab item all the time"); } function DefaultVueTabItem() { diff --git a/v2/src/components/tabs/FrontendSDKTabs.tsx b/v2/src/components/tabs/FrontendSDKTabs.tsx index 5c15d66b9..e7d7d746c 100644 --- a/v2/src/components/tabs/FrontendSDKTabs.tsx +++ b/v2/src/components/tabs/FrontendSDKTabs.tsx @@ -71,38 +71,7 @@ function DefaultReactJSTabItem() { } function DefaultAngularTabItem() { - return ( - - - -
-
-
- - - - - - - Important -
-
-
- SuperTokens does not provide non-React UI components. So we will be using the supertokens-auth-react SDK and will inject the React components to show the UI. Therefore, the code snippet below refers to the supertokens-auth-react SDK. -
-
-
- ~COPY-TABS=reactjs -
- - -
- ~COPY-TABS=npm,vanillajs -
- - - - ); + throw new Error("Should never come here cause we add angular tab item all the time"); } function DefaultVueTabItem() { diff --git a/v2/src/plugins/codeTypeChecking/index.js b/v2/src/plugins/codeTypeChecking/index.js index 9a264e33e..71d5c49d6 100644 --- a/v2/src/plugins/codeTypeChecking/index.js +++ b/v2/src/plugins/codeTypeChecking/index.js @@ -79,7 +79,7 @@ async function addCodeSnippetToEnv(mdFile, isSwiftEnabled) { } else if (currLineTrimmed === "```dart" || currLineTrimmed.startsWith("```dart ")) { currentCodeLanguage = "dart"; } else { - return rej(new Error(`UNABLE TO RECOGNISE LANGUAGE in file ${mdFile}.`)); + return rej(new Error(`UNABLE TO RECOGNISE LANGUAGE ${currLineTrimmed} in file ${mdFile}.`)); } } } @@ -373,6 +373,12 @@ Enabled: true, } codeSnippet = `export { }\n// Original: ${mdFile}\n${codeSnippet}`; // see https://www.aritsltd.com/blog/frontend-development/cannot-redeclare-block-scoped-variable-the-reason-behind-the-error-and-the-way-to-resolve-it/ + // vue requires use of ", ""); + } + let folderName = mdFile.replaceAll("~", "") + codeBlockCountInFile; await new Promise(async (res, rej) => { fs.mkdir('src/plugins/codeTypeChecking/jsEnv/snippets/' + folderName, { recursive: true }, async (err) => { @@ -602,6 +608,15 @@ function replaceCustomPlaceholdersInLine(child, exportedVariables) { continue; } + /** + * For snippets that contain supertokensUIInit, we add the dic id param parameter + */ + if (line.includes("supertokensUIInit(")) { + line = line.split("supertokensUIInit(").join("supertokensUIInit(\"supertokensui\", "); + newLines.push(line); + continue; + } + /** * For snippets that use v5 react-router-dom we use react-router-dom5 to import * If the import contains react-router-dom5 we replace it with react-router-dom for the final @@ -644,10 +659,10 @@ function replaceCustomPlaceholdersInLine(child, exportedVariables) { } /** - * For snippets that use supertokens-web-js as an HTML script we import supertokens-web-js-script for types. + * For snippets that use supertokens-web-js as an HTML script we import supertokens-web-js-script and supertokens-auth-react-script for types. * If the line contains this we skip adding the line */ - if (line.includes("supertokens-web-js-script")) { + if (line.includes("supertokens-web-js-script") || line.includes("supertokens-auth-react-script")) { continue; } diff --git a/v2/src/plugins/codeTypeChecking/jsEnv/package.json b/v2/src/plugins/codeTypeChecking/jsEnv/package.json index 949fb3043..2aef8ec8e 100644 --- a/v2/src/plugins/codeTypeChecking/jsEnv/package.json +++ b/v2/src/plugins/codeTypeChecking/jsEnv/package.json @@ -55,7 +55,8 @@ "react-router-dom5": "npm:react-router-dom@^5.3.0", "socket.io": "^4.6.1", "socketio": "^1.0.0", - "supertokens-auth-react": "^0.42.0", + "supertokens-auth-react": "^0.44.0", + "supertokens-auth-react-script": "github:supertokens/supertokens-auth-react#0.44", "supertokens-node": "^20.0.0", "supertokens-node7": "npm:supertokens-node@7.3", "supertokens-react-native": "^5.0.0", @@ -63,6 +64,7 @@ "supertokens-web-js-script": "github:supertokens/supertokens-web-js#0.12", "supertokens-website": "^20.0.1", "supertokens-website-script": "github:supertokens/supertokens-website#20.0", - "typescript": "^4.9.5" + "typescript": "^4.9.5", + "vue": "^3.4.35" } -} \ No newline at end of file +} diff --git a/v2/src/plugins/copyDocsAndCodeTypeChecking.js b/v2/src/plugins/copyDocsAndCodeTypeChecking.js index 941e767d7..b71db33e6 100644 --- a/v2/src/plugins/copyDocsAndCodeTypeChecking.js +++ b/v2/src/plugins/copyDocsAndCodeTypeChecking.js @@ -15,6 +15,70 @@ if (typeof String.prototype.replaceAll === "undefined") { } } +async function checkFrontendSDKRelatedDocs(mdPath) { + if (mdPath.includes("/change_me")) { + return + } + return new Promise((res, rej) => { + fs.readFile(mdPath, 'utf8', async (err, data) => { + // count the number of times or appears in the data + let count = (data.match(new RegExp('', 'g')) || []).length + (data.match(new RegExp('', 'g')) || []).length; + if (count > 0) { + // make sure that show_ui_switcher: true is also in the file + if (!mdPath.includes("pre-built-ui")) { // we do this cause the pre built UI section in the docs only talks about pre built Ui, so no custom switcher is needed for those pages. + if (data.indexOf("show_ui_switcher: true") === -1) { + rej(new Error("show_ui_switcher: true is not in the file: " + mdPath)); + } + } + + // get count of or appears in the data + let angularCount = (data.match(new RegExp('', 'g')) || []).length + (data.match(new RegExp('', 'g')) || []).length; + if (angularCount !== count) { + rej(new Error("The number of angular and reactjs tabs are not equal: " + mdPath)); + } + } + + // get the lines from the file which contain the string supertokens-auth-react-script + let lines = data.split("\n"); + let linesWithScript = lines.filter(line => line.includes("supertokens-auth-react-script")); + if (linesWithScript.length > 0) { + const ALLOWED_LINES = [ + `import {init as supertokensUIInit} from "supertokens-auth-react-script";`, + `import {init as supertokensUIInit} from "supertokens-auth-react-script"`, + `import supertokensUIMultitenancy from "supertokens-auth-react-script/recipe/multitenancy";`, + `import supertokensUIMultitenancy from "supertokens-auth-react-script/recipe/multitenancy"`, + `import supertokensUISession from "supertokens-auth-react-script/recipe/session";`, + `import supertokensUISession from "supertokens-auth-react-script/recipe/session"`, + `import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword";`, + `import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"`, + `import supertokensUIThirdParty from "supertokens-auth-react-script/recipe/thirdparty";`, + `import supertokensUIThirdParty from "supertokens-auth-react-script/recipe/thirdparty"`, + `import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless";`, + `import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless"`, + `import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification";`, + `import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"`, + `import supertokensUIMultiFactorAuth from "supertokens-auth-react-script/recipe/multifactorauth";`, + `import supertokensUIMultiFactorAuth from "supertokens-auth-react-script/recipe/multifactorauth"`, + `import supertokensUITOTP from "supertokens-auth-react-script/recipe/totp";`, + `import supertokensUITOTP from "supertokens-auth-react-script/recipe/totp"`, + `import supertokensUIUserRoles from "supertokens-auth-react-script/recipe/userroles";`, + `import supertokensUIUserRoles from "supertokens-auth-react-script/recipe/userroles"`, + `import supertokensUI from "supertokens-auth-react-script"`, + `import supertokensUI from "supertokens-auth-react-script";` + ] + + for (const line of linesWithScript) { + if (!ALLOWED_LINES.includes(line.trim())) { + rej(new Error("The line is not allowed: " + line + " in the file: " + mdPath)); + } + } + } + + res(); + }); + }); +} + module.exports = function (context, opts) { return { @@ -36,6 +100,12 @@ module.exports = function (context, opts) { origDocs.push(mdPath); } } + + // we check some extra conditions related to https://github.com/supertokens/docs/pull/822/ PR here + // which are not related to copy docs or code type checking, but this place is fine for it anyway: + for (const mdPath of results) { + await checkFrontendSDKRelatedDocs(mdPath); + } res(); }); }) diff --git a/v2/thirdparty/advanced-customizations/frontend-functions-override/usage.mdx b/v2/thirdparty/advanced-customizations/frontend-functions-override/usage.mdx index ef33b6c17..5e942fd6a 100644 --- a/v2/thirdparty/advanced-customizations/frontend-functions-override/usage.mdx +++ b/v2/thirdparty/advanced-customizations/frontend-functions-override/usage.mdx @@ -2,22 +2,27 @@ id: usage title: How to use hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # How to use ## Use the override config + + + + + + :::info See all the [functions that can be overrided here](https://supertokens.com/docs/auth-react/modules/recipe_thirdparty.html#RecipeInterface) ::: - - - ```tsx import SuperTokens from "supertokens-auth-react"; import ThirdParty from "supertokens-auth-react/recipe/thirdparty"; @@ -55,7 +60,62 @@ SuperTokens.init({ }); ``` - + + + +:::info +See all the [functions that can be overrided here](https://supertokens.com/docs/auth-react/modules/recipe_thirdparty.html#RecipeInterface) +::: + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIThirdParty from "supertokens-auth-react-script/recipe/thirdparty"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIThirdParty.init({ + // highlight-start + override: { + functions: (originalImplementation) => { + return { + ...originalImplementation, + + // we will only be overriding what happens when a user + // clicks the sign in or sign up button. + signInAndUp: async function (input) { + // TODO: some custom logic + + // or call the default behaviour as show below + return originalImplementation.signInAndUp(input); + }, + // ... + // TODO: override more functions + } + } + } + // highlight-end + }) + ] +}); +``` + + - `originalImplementation` is an object that contains functions that have the original implementation for this recipe. They can be used in your functions as a way to use the SuperTokens' default behaviour. -- In the above code snippet, we override the `signInAndUp` function of this recipe. This means that after the user is navigated back to the your app post auth (from the third party provider), your function will be called with the relevant `input` object. \ No newline at end of file +- In the above code snippet, we override the `signInAndUp` function of this recipe. This means that after the user is navigated back to the your app post auth (from the third party provider), your function will be called with the relevant `input` object. + + + + +:::caution +Not applicable since you need to build custom UI anyway, so when you call the functions from our SDK, or call the API directly, you can run pre / post logic in your own code. +::: + + + \ No newline at end of file diff --git a/v2/thirdparty/advanced-customizations/frontend-hooks/handle-event.mdx b/v2/thirdparty/advanced-customizations/frontend-hooks/handle-event.mdx index 8b3d954bd..e0b4e6719 100644 --- a/v2/thirdparty/advanced-customizations/frontend-hooks/handle-event.mdx +++ b/v2/thirdparty/advanced-customizations/frontend-hooks/handle-event.mdx @@ -2,16 +2,21 @@ id: handle-event title: Handle Event Hook hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Handle Event Hook + + + This function is called for various user actions. It can be used for logging, analytics or any side effect purposes (these are essentially fire and forget events). - + ```tsx @@ -34,9 +39,46 @@ ThirdParty.init({ } }) ``` + - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import supertokensUIThirdParty from "supertokens-auth-react-script/recipe/thirdparty"; + +supertokensUIThirdParty.init({ + onHandleEvent: (context) => { + if (context.action === "SUCCESS") { + if (context.createdNewSession) { + let user = context.user; + if (context.isNewRecipeUser && context.user.loginMethods.length === 1) { + // sign up success + } else { + // sign in success + } + } else { + // this is during linking a social account to an existing account + } + } + } +}) +``` + + + :::info -Also checkout the [session recipe hand event hook](/docs/session/advanced-customizations/frontend-hooks/handle-event). -::: \ No newline at end of file +Also checkout the [session recipe handle event hook](/docs/session/advanced-customizations/frontend-hooks/handle-event). +::: + + + + +:::caution +Not applicable since you need to build custom UI anyway, so when you call the functions from our SDK, or call the API directly, you can run pre / post logic in your own code. +::: + + + \ No newline at end of file diff --git a/v2/thirdparty/advanced-customizations/frontend-hooks/pre-api.mdx b/v2/thirdparty/advanced-customizations/frontend-hooks/pre-api.mdx index 9d46a6e2f..a699b4ae7 100644 --- a/v2/thirdparty/advanced-customizations/frontend-hooks/pre-api.mdx +++ b/v2/thirdparty/advanced-customizations/frontend-hooks/pre-api.mdx @@ -55,6 +55,41 @@ ThirdParty.init({ ``` + + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import supertokensUIThirdParty from "supertokens-auth-react-script/recipe/thirdparty"; + +supertokensUIThirdParty.init({ + preAPIHook: async (context) => { + let url = context.url; + + // is the fetch config object that contains the header, body etc.. + let requestInit = context.requestInit; + + let action = context.action; + if (action === "GET_AUTHORISATION_URL") { + + } else if (action === "THIRD_PARTY_SIGN_IN_UP") { + // Note: this could either be sign in or sign up. + // we don't know that at the time of the API call + // since all we have is the authorisation code from + // the social provider + } + + // events such as sign out are in the + // session recipe pre API hook (See the info box below) + return { + requestInit, url + }; + } +}) +``` + + diff --git a/v2/thirdparty/advanced-customizations/frontend-hooks/redirection-callback.mdx b/v2/thirdparty/advanced-customizations/frontend-hooks/redirection-callback.mdx index 09398a627..d48d24342 100644 --- a/v2/thirdparty/advanced-customizations/frontend-hooks/redirection-callback.mdx +++ b/v2/thirdparty/advanced-customizations/frontend-hooks/redirection-callback.mdx @@ -2,16 +2,21 @@ id: redirection-callback title: Redirection Callback Hook hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Redirection Callback Hook + + + This function is used to change where the user is redirected to post certain actions. For example, you can use this to redirect a user to a specific URL post sign in / up. If you're embedding the sign in / up components in a popup and wish to disable redirection entirely, simply return `null`. - + ```tsx @@ -48,6 +53,57 @@ SuperTokens.init({ ] }) ``` + - + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIThirdParty from "supertokens-auth-react-script/recipe/thirdparty"; + + +supertokensUIInit({ + appInfo: { + appName: "SuperTokens", + apiDomain: "http://localhost:3000", + websiteDomain: "http://localhost:3000", + }, + getRedirectionURL: async (context) => { + if (context.action === "SUCCESS" && context.newSessionCreated) { + // called on a successful sign in / up. Where should the user go next? + let redirectToPath = context.redirectToPath; + if (redirectToPath !== undefined) { + // we are navigating back to where the user was before they authenticated + return redirectToPath; + } + if (context.createdNewUser) { + // user signed up + return "/onboarding" + } else { + // user signed in + return "/dashboard" + } + } + // return undefined to let the default behaviour play out + return undefined; + }, + recipeList: [ + supertokensUIThirdParty.init(/* ... */) + ] +}) +``` + + + + + + + +:::caution +Not applicable since you need to build custom UI anyway, so you can redirect the user after calling our SDK functions / API. +::: + + + diff --git a/v2/thirdparty/advanced-customizations/react-component-override/usage.mdx b/v2/thirdparty/advanced-customizations/react-component-override/usage.mdx index 63503db20..36f87d9b6 100644 --- a/v2/thirdparty/advanced-customizations/react-component-override/usage.mdx +++ b/v2/thirdparty/advanced-customizations/react-component-override/usage.mdx @@ -1,25 +1,28 @@ --- id: usage title: How to use -hide_title: true +show_ui_switcher: true --- - -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" import {Answer} from "/src/components/question" import {Question}from "/src/components/question" # How to use + + + + + + + 1. You will have to use the `ThirdpartyComponentsOverrideProvider` or the `AuthRecipeComponentsOverrideContextProvider` component as shown below. make sure that it render the SuperTokens components inside this component. 2. [Pick a component](#finding-which-component-will-be-overridden) that you'd like to override by its key. 3. Supply a React component against the key you have picked. Your custom component will get the original component as a `prop`. -### Example - - - @@ -122,9 +125,6 @@ export default App; Please make sure that the file in which this config is specified is a `.tsx` or ` .jsx` file type. ::: - - - ## Finding which component will be overridden To do that, you should use React Developer Tools extension which provides a component tree inspector. @@ -152,3 +152,23 @@ const customComponent = ({ DefaultComponent, ...props }: { DefaultComponent: Rea ) } ``` + + + + +:::caution +Not applicable to non-react apps. You can disable the specific pre built UI component, and then build your own UI instead. +::: + + + + + + + +:::caution +Not applicable to custom UI +::: + + + \ No newline at end of file diff --git a/v2/thirdparty/common-customizations/changing-base-path/api-base-path.mdx b/v2/thirdparty/common-customizations/changing-base-path/api-base-path.mdx index f7a1a28f7..04d981956 100644 --- a/v2/thirdparty/common-customizations/changing-base-path/api-base-path.mdx +++ b/v2/thirdparty/common-customizations/changing-base-path/api-base-path.mdx @@ -112,6 +112,45 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +supertokensUIInit({ + appInfo: { + appName: "yourAppName", + apiDomain: "yourApi", + websiteDomain: "yourWebsite", + // highlight-next-line + apiBasePath: "/api/v3/auth" + }, + recipeList: [], +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +// this goes in the root of your frontend app +import SuperTokens from "supertokens-web-js"; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + // highlight-next-line + apiBasePath: "/api/v3/auth", + appName: "...", + }, + recipeList: [/* ... */], +}); +``` + + + diff --git a/v2/thirdparty/common-customizations/changing-base-path/website-base-path.mdx b/v2/thirdparty/common-customizations/changing-base-path/website-base-path.mdx index 0795a935f..3e3e959bd 100644 --- a/v2/thirdparty/common-customizations/changing-base-path/website-base-path.mdx +++ b/v2/thirdparty/common-customizations/changing-base-path/website-base-path.mdx @@ -2,6 +2,7 @@ id: website-base-path title: Website Base Path hide_title: true +show_ui_switcher: true --- @@ -9,6 +10,7 @@ hide_title: true import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" import BackendSDKTabs from "/src/components/tabs/BackendSDKTabs" import BackendSDKCasing from "/src/components/BackendSDKCasing" import TabItem from '@theme/TabItem'; @@ -16,6 +18,10 @@ import TabItem from '@theme/TabItem'; # Website Base Path ## Step 1) Front End Change + + + + Since the beginning of this guide, you probably noticed that all the front-end routes for SuperTokens widget are prefixed by `/auth`. You can change this value in the `init` function by setting websiteBasePath. @@ -39,8 +45,36 @@ SuperTokens.init({ + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +supertokensUIInit({ + appInfo: { + appName: "yourAppName", + apiDomain: "yourApi", + websiteDomain: "yourWebsite", + // highlight-next-line + websiteBasePath: "/authentication" + }, + recipeList: [], +}); +``` + + + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + ## Step 2) Back End Change diff --git a/v2/thirdparty/common-customizations/email-verification/about.mdx b/v2/thirdparty/common-customizations/email-verification/about.mdx index 12e146de8..38e945c5f 100644 --- a/v2/thirdparty/common-customizations/email-verification/about.mdx +++ b/v2/thirdparty/common-customizations/email-verification/about.mdx @@ -212,6 +212,54 @@ function App() { + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + // highlight-start + supertokensUIEmailVerification.init({ + mode: "REQUIRED", // or "OPTIONAL" + }), + // highlight-end + ], +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from "supertokens-web-js"; +import EmailVerification from "supertokens-web-js/recipe/emailverification"; +import Session from "supertokens-web-js/recipe/session"; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + // highlight-next-line + EmailVerification.init(), + Session.init(), + ], +}); +``` + + + :::important diff --git a/v2/thirdparty/common-customizations/email-verification/changing-style.mdx b/v2/thirdparty/common-customizations/email-verification/changing-style.mdx index 596a7ca00..de0cbe03c 100644 --- a/v2/thirdparty/common-customizations/email-verification/changing-style.mdx +++ b/v2/thirdparty/common-customizations/email-verification/changing-style.mdx @@ -2,19 +2,20 @@ id: changing-style title: Changing Style via CSS hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Changing Style via CSS -:::important -This is applicable to prebuilt UI only. -::: + + Updating the CSS allows you to change the UI of our components to meet your needs. @@ -30,7 +31,7 @@ Each stylable components contains `data-supertokens` attributes (in our example Let's add a `border` to our `link` elements. The syntax for styling is plain CSS. - + ```tsx @@ -62,7 +63,38 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailVerification.init({ + // highlight-start + style: ` + [data-supertokens~=link] { + border: 2px solid #0076ff; + border-radius: 5; + width: 30%; + margin: 0 auto; + } + `, + // highlight-end + }) + ] +}); +``` + + + The above will result in: @@ -72,7 +104,7 @@ The above will result in: By default, SuperTokens uses the Arial font. The best way to override this is to add a `font-family` styling to the `container` component in the recipe configuration. - + ```tsx @@ -101,13 +133,39 @@ SuperTokens.init({ }); ``` - + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailVerification.init({ + // highlight-start + style: ` + [data-supertokens~=container] { + font-family: cursive + } + ` + // highlight-end + }), + ] +}); +``` + + ### Using media queries You may want to have different CSS for different viewports. This can be achieved via media queries like this: - + ```tsx @@ -145,7 +203,44 @@ SuperTokens.init({ }); ``` - + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + // ... + supertokensUIEmailVerification.init({ + // ... + style: ` + [data-supertokens~=link] { + border: 2px solid #0076ff; + borderRadius: 5; + width: 30%; + margin: 0 auto; + } + + // highlight-start + @media (max-width: 440px) { + [data-supertokens~=link] { + width: 90%; + } + } + // highlight-end + `, + }), + ], +}); +``` + + ## Customising individual screens @@ -153,7 +248,7 @@ SuperTokens.init({ This screen is where the user is redirected if `mode` is set to `REQUIRED` and they visit a path that requires a verified email. - + ```tsx @@ -180,13 +275,38 @@ SuperTokens.init({ }); ``` - + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + supertokensUIEmailVerification.init({ + // highlight-start + sendVerifyEmailScreen: { + style: ` ... ` + } + // highlight-end + }) + ] +}); +``` + + ### Verify link clicked screen This is the screen shown to users that click the email verification link in the email. - + ```tsx @@ -213,4 +333,41 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + supertokensUIEmailVerification.init({ + // highlight-start + verifyEmailLinkClickedScreen: { + style: ` ... `, + } + // highlight-end + }) + ] +}); +``` + + + + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/thirdparty/common-customizations/email-verification/embed-in-page.mdx b/v2/thirdparty/common-customizations/email-verification/embed-in-page.mdx index 8f8a84e8d..d1f1445d2 100644 --- a/v2/thirdparty/common-customizations/email-verification/embed-in-page.mdx +++ b/v2/thirdparty/common-customizations/email-verification/embed-in-page.mdx @@ -2,20 +2,25 @@ id: embed-in-page title: Embed in a page hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" import BackendSDKTabs from "/src/components/tabs/BackendSDKTabs" # Embed in a page + + + ## Step 1: Disable the default implementation - + ```tsx @@ -42,11 +47,39 @@ SuperTokens.init({ If you navigate to `/auth/verify-email`, you should not see the widget anymore. - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailVerification.init({ + mode: "REQUIRED", + // highlight-start + disableDefaultUI: true + // highlight-end + }), + ] +}); +``` + +If you navigate to `/auth/verify-email`, you should not see the widget anymore. + + + ## Step 2: Render the component yourself - + Add the `EmailVerification` component in your app: @@ -68,7 +101,27 @@ class EmailVerificationPage extends React.Component { } ``` - + + + +:::caution +You will have to build your own UI instead. +::: + + + + + + + +## Step 1 & 2: Disable the pre built UI + +:::caution +Not applicable since you do not use our pre built UI +::: + + + ## Step 3: Changing the website path for the email verification UI (optional) @@ -208,7 +261,10 @@ init( ### Step B: On the frontend - + + + + ```tsx @@ -238,4 +294,45 @@ SuperTokens.init({ }) ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + supertokensUIEmailVerification.init({ + mode: "REQUIRED", + //highlight-start + + // The user will be taken to the custom path when they need to get their email verified. + getRedirectionURL: async (context) => { + if (context.action === "VERIFY_EMAIL") { + return "/custom-email-verification-path"; + }; + } + //highlight-end + }) + ] +}) +``` + + + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/thirdparty/common-customizations/email-verification/protecting-routes.mdx b/v2/thirdparty/common-customizations/email-verification/protecting-routes.mdx index d7d7a5ca0..e0bf31003 100644 --- a/v2/thirdparty/common-customizations/email-verification/protecting-routes.mdx +++ b/v2/thirdparty/common-customizations/email-verification/protecting-routes.mdx @@ -1114,8 +1114,8 @@ function ProtectedComponent() { ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { EmailVerificationClaim } from "supertokens-auth-react/recipe/emailverification"; +import Session from "supertokens-web-js/recipe/session"; +import { EmailVerificationClaim } from "supertokens-web-js/recipe/emailverification"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { diff --git a/v2/thirdparty/common-customizations/embed-sign-in-up-form.mdx b/v2/thirdparty/common-customizations/embed-sign-in-up-form.mdx index 079002559..2b2352073 100644 --- a/v2/thirdparty/common-customizations/embed-sign-in-up-form.mdx +++ b/v2/thirdparty/common-customizations/embed-sign-in-up-form.mdx @@ -16,12 +16,13 @@ import RRDVersionSubTabs from "/src/components/tabs/RRDVersionSubTabs" + + + ## Case 1: Rendering the Auth Widget in a page The following example shows the scenario where you have a dedicated route, such as `/auth`, for rendering the Auth Widget. Upon a successful login, the user will be automatically redirected to the return value of `getRedirectionURL` (defaulting to `/`). - - @@ -181,8 +182,6 @@ function MyAuthPage() { ``` - - In the above code snippet, we: @@ -199,8 +198,6 @@ When the user visits the `/auth` page, they will see the SignIn UI by default. T The following example shows the scenario where you have a dedicated route, such as `/auth`, for rendering the Auth Widget. However, upon a successful login, the user will see a logged in UI instead of getting redirected. - - @@ -417,8 +414,6 @@ function LandingPage() { ``` - - In the above code snippet, we wrap the logged-in component with `Session.SessionAuth` to validate all claims before displaying the logged-in UI. For instance, with email verification enabled, if a user's email is unverified, `Session.SessionAuth` redirects to the email verification page. @@ -430,8 +425,6 @@ In the above case, redirection may occur if a claim fails. For instance, in the The following example shows the scenario where you embed the Auth Widget in a popup, and upon successful login, you aim to close the popup. - - @@ -687,13 +680,22 @@ function AuthPopup() { ``` - - :::note In the above case, redirection may occur if a claim fails. For instance, in the case of an Email Verification claim, if the user's email is not verified, they will be redirected to the email verification page. To prevent redirection for failed claims, please contact us on [Discord](https://supertokens.com/discord) for assistance. ::: + + + + +:::caution +Not applicable to non-react apps. Please build your own custom UI instead. +::: + + + + diff --git a/v2/thirdparty/common-customizations/handling-signinup-success.mdx b/v2/thirdparty/common-customizations/handling-signinup-success.mdx index d22b33297..c421f17fe 100644 --- a/v2/thirdparty/common-customizations/handling-signinup-success.mdx +++ b/v2/thirdparty/common-customizations/handling-signinup-success.mdx @@ -60,6 +60,47 @@ Please refer to [this page](../advanced-customizations/frontend-hooks/handle-eve + + +This method allows you to fire events immediately after a successful sign in / up. For example to send analytics events post sign in / up. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIThirdParty from "supertokens-auth-react-script/recipe/thirdparty"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIThirdParty.init({ + // highlight-start + onHandleEvent: async (context) => { + if (context.action === "SUCCESS") { + if (context.isNewRecipeUser && context.user.loginMethods.length === 1) { + // TODO: Sign up + } else { + // TODO: Sign in + } + } + } + // highlight-end + }), + supertokensUISession.init() + ] +}); +``` + +:::info +Please refer to [this page](../advanced-customizations/frontend-hooks/handle-event) to learn more about the `onHandleEvent` hook. +::: + + + diff --git a/v2/thirdparty/common-customizations/multi-tenancy/common-domain-login.mdx b/v2/thirdparty/common-customizations/multi-tenancy/common-domain-login.mdx index 68f3018c5..4aa58784e 100644 --- a/v2/thirdparty/common-customizations/multi-tenancy/common-domain-login.mdx +++ b/v2/thirdparty/common-customizations/multi-tenancy/common-domain-login.mdx @@ -173,51 +173,6 @@ export const AuthPage = () => { - - - - -```tsx -import { useState } from "react"; -import { getRoutingComponent } from "supertokens-auth-react/ui"; -^{prebuiltuiimport} -import { useSessionContext } from "supertokens-auth-react/recipe/session"; - -export const AuthPage = () => { - const [inputTenantId, setInputTenantId] = useState(""); - const tenantId = localStorage.getItem("tenantId") ?? undefined; - const session = useSessionContext(); - - if (session.loading) { - return null; - } - - if ( - tenantId !== undefined || // if we have a tenantId stored - session.doesSessionExist === true || // or an active session (it'll contain the tenantId) - new URLSearchParams(location.search).has("tenantId") // or we are on a link (e.g.: email verification) that contains the tenantId - ) { - return getRoutingComponent([^{recipePreBuiltUINameCapitalLetters}]); - } else { - return ( -
{ - // this value will be read by SuperTokens as shown in the next steps. - localStorage.setItem("tenantId", inputTenantId); - }}> -

Enter your organisation's name:

- setInputTenantId(e.target.value)} /> -
- -
- ); - } -}; -``` - - - - - We render a simple UI which asks the user for their organisation's name. Their input will be treated as their tenant ID. - Once the user has submitted that form, we will store their input in localstorage. This value will be read later on (as shown below) by SuperTokens to render the right login method based on the saved tenantId. - In case the tenantID exists in localstorage, we render the SuperTokens UI as usual. @@ -233,6 +188,20 @@ We want to render the `AuthPage` component to show on `^{form_websiteBasePath}/* The `AuthPage` will replace the call to `getSuperTokensRoutesForReactRouterDom` or `getRoutingComponent` that you may have added to your app from the quick setup section. ::: + + + + +:::caution +No code snippet provided here, however, if you visit the auth component, you will see that we are rendering the pre built UI in the `"supertokensui"` `div` element on page load. The logic here needs to change to first check if the user has provided us with the tenantId. If they have, we render the SuperTokens UI as usual. If they have not, we render a simple UI which asks the user for their tenant id and save that in localstorage. + +Switch to the React code tab here to see how this is implemented in React, and a similar logic can be followed here. +::: + + + + + @@ -396,6 +365,50 @@ We also set the `usesDynamicLoginMethods` to `true` which tells SuperTokens that + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIMultitenancy from "supertokens-auth-react-script/recipe/multitenancy"; + +supertokensUIInit({ + appInfo: { + appName: "...", + apiDomain: "...", + websiteDomain: "...", + apiBasePath: "...", + websiteBasePath: "..." + }, + // highlight-next-line + usesDynamicLoginMethods: true, + recipeList: [ + // highlight-start + supertokensUIMultitenancy.init({ + override: { + functions: (oI) => { + return { + ...oI, + getTenantId: (input) => { + let tid = localStorage.getItem("tenantId"); + return tid === null ? undefined : tid; + } + } + } + } + }) + // highlight-end + // other recipes... + ] +}); +``` + +:::important +We also set the `usesDynamicLoginMethods` to `true` which tells SuperTokens that the login methods are dynamic (based on the tenantId). This means that on page load (of the login page), SuperTokens will first fetch the configured login methods for the tenantId and display the login UI based on the result of the API call. +::: + + + @@ -660,6 +673,42 @@ SuperTokens.init({ + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; +import supertokensUIMultitenancy from "supertokens-auth-react-script/recipe/multitenancy"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + // highlight-start + getRedirectionURL: async (context) => { + if (context.action === "SUCCESS" && context.newSessionCreated) { + let claimValue: string[] | undefined = await supertokensUISession.getClaimValue({ + claim: supertokensUIMultitenancy.AllowedDomainsClaim + }); + if (claimValue !== undefined) { + window.location.href = "https://" + claimValue[0]; + } else { + // there was no configured allowed domain for this user. Throw an error cause of + // misconfig or redirect to a default sub domain + } + } + return undefined; + }, + // highlight-end + recipeList: [ /* Recipe init here... */ ] +}); +``` + + + @@ -780,6 +829,68 @@ Above, in `Session.init` on the frontend, we add the `hasAccessToCurrentDomain` + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; +import supertokensMultitenancy from "supertokens-web-js-script/recipe/multitenancy"; + +supertokensUISession.init({ + override: { + functions: (oI) => ({ + ...oI, + getGlobalClaimValidators: ({ claimValidatorsAddedByOtherRecipes }) => [ + ...claimValidatorsAddedByOtherRecipes, + { + ...supertokensMultitenancy.AllowedDomainsClaim.validators.hasAccessToCurrentDomain(), + onFailureRedirection: async () => { + let claimValue = await supertokensUISession.getClaimValue({ + claim: supertokensMultitenancy.AllowedDomainsClaim, + }); + return "https://" + claimValue![0]; + }, + }, + ], + }), + }, +}) +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: +```tsx +import Session from 'supertokens-web-js/recipe/session'; +import { AllowedDomainsClaim } from 'supertokens-web-js/recipe/multitenancy'; + +Session.init({ + override: { + functions: (oI) => ({ + ...oI, + getGlobalClaimValidators: ({ claimValidatorsAddedByOtherRecipes }) => [ + ...claimValidatorsAddedByOtherRecipes, + { + ...AllowedDomainsClaim.validators.hasAccessToCurrentDomain(), + onFailureRedirection: async () => { + let claimValue = await Session.getClaimValue({ + claim: AllowedDomainsClaim, + }); + return "https://" + claimValue![0]; + }, + }, + ], + }), + }, +}) +``` + +Above, in `Session.init` on the frontend, we add the `hasAccessToCurrentDomain` claim validator to the global validators. This means, that [whenever we check protect a route](../sessions/protecting-frontend-routes), it will check if `hasAccessToCurrentDomain` has passed, and if not, SuperTokens will redirect to the user to their right sub domain (via the values set in the `AllowedDomainsClaim` session claim). + + + diff --git a/v2/thirdparty/common-customizations/multi-tenancy/sub-domain-login.mdx b/v2/thirdparty/common-customizations/multi-tenancy/sub-domain-login.mdx index 5243773c1..49d707da2 100644 --- a/v2/thirdparty/common-customizations/multi-tenancy/sub-domain-login.mdx +++ b/v2/thirdparty/common-customizations/multi-tenancy/sub-domain-login.mdx @@ -135,6 +135,48 @@ SuperTokens.init({ + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; +import supertokensUIMultitenancy from "supertokens-auth-react-script/recipe/multitenancy"; +supertokensUIInit({ + appInfo: { + appName: "^{form_appName}", + apiDomain: "^{form_apiDomain}", + websiteDomain: "^{form_websiteDomain}", + apiBasePath: "^{form_apiBasePath}", + websiteBasePath: "^{form_websiteBasePath}" + }, + // highlight-start + usesDynamicLoginMethods: true, + // highlight-end + recipeList: [ + // Other recipes... + supertokensUISession.init(), + // highlight-start + supertokensUIMultitenancy.init({ + override: { + functions: (oI) => { + return { + ...oI, + getTenantId: async () => { + // We treat the sub domain as the tenant ID + return window.location.host.split('.')[0] + } + } + } + }, + }) + // highlight-end + ] +}); +``` + + + @@ -493,6 +535,68 @@ Above, in `Session.init` on the frontend, we add the `hasAccessToCurrentDomain` + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; +import supertokensMultitenancy from "supertokens-web-js-script/recipe/multitenancy"; + +supertokensUISession.init({ + override: { + functions: (oI) => ({ + ...oI, + getGlobalClaimValidators: ({ claimValidatorsAddedByOtherRecipes }) => [ + ...claimValidatorsAddedByOtherRecipes, + { + ...supertokensMultitenancy.AllowedDomainsClaim.validators.hasAccessToCurrentDomain(), + onFailureRedirection: async () => { + let claimValue = await supertokensUISession.getClaimValue({ + claim: supertokensMultitenancy.AllowedDomainsClaim, + }); + return "https://" + claimValue![0]; + }, + }, + ], + }), + }, +}) +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: +```tsx +import Session from 'supertokens-web-js/recipe/session'; +import { AllowedDomainsClaim } from 'supertokens-web-js/recipe/multitenancy'; + +Session.init({ + override: { + functions: (oI) => ({ + ...oI, + getGlobalClaimValidators: ({ claimValidatorsAddedByOtherRecipes }) => [ + ...claimValidatorsAddedByOtherRecipes, + { + ...AllowedDomainsClaim.validators.hasAccessToCurrentDomain(), + onFailureRedirection: async () => { + let claimValue = await Session.getClaimValue({ + claim: AllowedDomainsClaim, + }); + return "https://" + claimValue![0]; + }, + }, + ], + }), + }, +}) +``` + +Above, in `Session.init` on the frontend, we add the `hasAccessToCurrentDomain` claim validator to the global validators. This means, that [whenever we check protect a route](../sessions/protecting-frontend-routes), it will check if `hasAccessToCurrentDomain` has passed, and if not, SuperTokens will redirect to the user to their right sub domain (via the values set in the `AllowedDomainsClaim` session claim). + + + diff --git a/v2/thirdparty/common-customizations/sessions/claims/access-token-payload.mdx b/v2/thirdparty/common-customizations/sessions/claims/access-token-payload.mdx index 828b6cb16..ac18be4b9 100644 --- a/v2/thirdparty/common-customizations/sessions/claims/access-token-payload.mdx +++ b/v2/thirdparty/common-customizations/sessions/claims/access-token-payload.mdx @@ -1111,7 +1111,7 @@ async function someFunc() { ```tsx -import Session from 'supertokens-auth-react/recipe/session'; +import Session from 'supertokens-web-js/recipe/session'; async function someFunc() { if (await Session.doesSessionExist()) { diff --git a/v2/thirdparty/common-customizations/sessions/claims/claim-validators.mdx b/v2/thirdparty/common-customizations/sessions/claims/claim-validators.mdx index 8ffe6e207..2a7b59a42 100644 --- a/v2/thirdparty/common-customizations/sessions/claims/claim-validators.mdx +++ b/v2/thirdparty/common-customizations/sessions/claims/claim-validators.mdx @@ -856,8 +856,8 @@ Now whenever you wrap your component with the `` wrapper, SuperToke ```tsx -import SuperTokens from "supertokens-auth-react"; -import Session, { BooleanClaim } from 'supertokens-auth-react/recipe/session'; +import SuperTokens from "supertokens-web-js"; +import Session, { BooleanClaim } from 'supertokens-web-js/recipe/session'; const SecondFactorClaim = new BooleanClaim({ id: "2fa-completed", @@ -870,7 +870,6 @@ SuperTokens.init({ appInfo: { apiDomain: "...", appName: "...", - websiteDomain: "..." }, recipeList: [ //... @@ -894,7 +893,7 @@ SuperTokens.init({ Now you can protect your frontend routes by using the `Session.validateClaims` function as shown below: ```tsx -import Session, { BooleanClaim } from "supertokens-auth-react/recipe/session"; +import Session, { BooleanClaim } from "supertokens-web-js/recipe/session"; const SecondFactorClaim = new BooleanClaim({ id: "2fa-completed", @@ -2286,8 +2285,8 @@ Unlike using the `overrideGlobalClaimValidators` prop, the `useClaimValue` funct ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { @@ -2330,8 +2329,8 @@ async function shouldLoadRoute(): Promise { If you want to have more complex access control, you can get the roles list from the session as follows, and check the list yourself: ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { diff --git a/v2/thirdparty/common-customizations/sessions/disable-interception.mdx b/v2/thirdparty/common-customizations/sessions/disable-interception.mdx index e1a878e6e..7d4a03d8a 100644 --- a/v2/thirdparty/common-customizations/sessions/disable-interception.mdx +++ b/v2/thirdparty/common-customizations/sessions/disable-interception.mdx @@ -58,6 +58,63 @@ Session.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUISession.init({ + override: { + functions: (oI) => { + return { + ...oI, + shouldDoInterceptionBasedOnUrl: (url, apiDomain, sessionTokenBackendDomain) => { + try { + let urlObj = new URL(url); + if (!urlObj.pathname.startsWith("/auth")) { + return false; + } + } catch (ignored) { } + return oI.shouldDoInterceptionBasedOnUrl(url, apiDomain, sessionTokenBackendDomain); + } + } + } + } +}) +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import Session from "supertokens-web-js/recipe/session"; + +Session.init({ + override: { + functions: (oI) => { + return { + ...oI, + shouldDoInterceptionBasedOnUrl: (url, apiDomain, sessionTokenBackendDomain) => { + try { + let urlObj = new URL(url); + if (!urlObj.pathname.startsWith("/auth")) { + return false; + } + } catch (ignored) { } + return oI.shouldDoInterceptionBasedOnUrl(url, apiDomain, sessionTokenBackendDomain); + } + } + } + } +}) +``` + + + diff --git a/v2/thirdparty/common-customizations/sessions/in-iframe.mdx b/v2/thirdparty/common-customizations/sessions/in-iframe.mdx index e43e2fa15..0589f4b94 100644 --- a/v2/thirdparty/common-customizations/sessions/in-iframe.mdx +++ b/v2/thirdparty/common-customizations/sessions/in-iframe.mdx @@ -69,6 +69,65 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; +declare let cookieHandler: any // typecheck-only, removed from output +declare let windowHandler: any // typecheck-only, removed from output + +supertokensUIInit({ + cookieHandler, + windowHandler, + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUISession.init({ + // highlight-start + tokenTransferMethod: "header", + isInIframe: true + // highlight-end + }) + ] +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from "supertokens-web-js"; +import Session from "supertokens-web-js/recipe/session"; +declare let cookieHandler: any // typecheck-only, removed from output +declare let windowHandler: any // typecheck-only, removed from output + +SuperTokens.init({ + cookieHandler, + windowHandler, + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + Session.init({ + // highlight-start + tokenTransferMethod: "header", + isInIframe: true + // highlight-end + }) + ], +}) +``` + + + @@ -84,8 +143,12 @@ SuperTokens.init({ ```tsx import SuperTokens from "supertokens-web-js"; import Session from "supertokens-web-js/recipe/session"; +declare let cookieHandler: any // typecheck-only, removed from output +declare let windowHandler: any // typecheck-only, removed from output SuperTokens.init({ + cookieHandler, + windowHandler, appInfo: { apiDomain: "...", appName: "...", @@ -107,7 +170,11 @@ SuperTokens.init({ ```tsx import supertokens from "supertokens-web-js-script"; import supertokensSession from "supertokens-web-js-script/recipe/session"; +declare let cookieHandler: any // typecheck-only, removed from output +declare let windowHandler: any // typecheck-only, removed from output supertokens.init({ + cookieHandler, + windowHandler, appInfo: { apiDomain: "...", appName: "...", diff --git a/v2/thirdparty/common-customizations/sessions/multiple-api-endpoints.mdx b/v2/thirdparty/common-customizations/sessions/multiple-api-endpoints.mdx index 2b9aae909..12d91616d 100644 --- a/v2/thirdparty/common-customizations/sessions/multiple-api-endpoints.mdx +++ b/v2/thirdparty/common-customizations/sessions/multiple-api-endpoints.mdx @@ -241,6 +241,51 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. +```tsx +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUISession.init({ + // highlight-next-line + sessionTokenBackendDomain: ".example.com" + }) + ] +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from 'supertokens-web-js'; +import Session from 'supertokens-web-js/recipe/session'; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + Session.init({ + sessionTokenBackendDomain: ".example.com" + }), + ], +}); +``` + + + diff --git a/v2/thirdparty/common-customizations/sessions/protecting-frontend-routes.mdx b/v2/thirdparty/common-customizations/sessions/protecting-frontend-routes.mdx index 13b1829bc..232bba79f 100644 --- a/v2/thirdparty/common-customizations/sessions/protecting-frontend-routes.mdx +++ b/v2/thirdparty/common-customizations/sessions/protecting-frontend-routes.mdx @@ -123,7 +123,7 @@ function MyDashboardComponent(props: any) { You can use the `doesSessionExist` function to check if a session exists in all your routes. ```tsx -import Session from 'supertokens-auth-react/recipe/session'; +import Session from 'supertokens-web-js/recipe/session'; async function doesSessionExist() { if (await Session.doesSessionExist()) { @@ -211,8 +211,8 @@ function ProtectedComponent() { ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { @@ -255,8 +255,8 @@ async function shouldLoadRoute(): Promise { If you want to have more complex access control, you can get the roles list from the session as follows, and check the list yourself: ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { diff --git a/v2/thirdparty/common-customizations/sessions/revoke-session.mdx b/v2/thirdparty/common-customizations/sessions/revoke-session.mdx index 9a84a64f8..012a72f96 100644 --- a/v2/thirdparty/common-customizations/sessions/revoke-session.mdx +++ b/v2/thirdparty/common-customizations/sessions/revoke-session.mdx @@ -66,7 +66,7 @@ The [`signOut` method](https://supertokens.com/docs/web-js/modules/recipe_sessio ```tsx // highlight-next-line -import Session from "supertokens-auth-react/recipe/session"; +import Session from "supertokens-web-js/recipe/session"; async function logout () { // highlight-next-line diff --git a/v2/thirdparty/common-customizations/sessions/share-session-across-sub-domains.mdx b/v2/thirdparty/common-customizations/sessions/share-session-across-sub-domains.mdx index 9c95085ab..b0f863386 100644 --- a/v2/thirdparty/common-customizations/sessions/share-session-across-sub-domains.mdx +++ b/v2/thirdparty/common-customizations/sessions/share-session-across-sub-domains.mdx @@ -58,6 +58,56 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + // ... + // this should be equal to the domain where the user will see the login UI + apiDomain: "...", + appName: "...", + websiteDomain: "https://example.com" + }, + recipeList: [ + supertokensUISession.init({ + // highlight-next-line + sessionTokenFrontendDomain: ".example.com" + }) + ] +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from "supertokens-web-js"; +import Session from "supertokens-web-js/recipe/session"; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + Session.init({ + // highlight-start + sessionTokenFrontendDomain: ".example.com" + // highlight-end + }), + ], +}) +``` + + + :::caution diff --git a/v2/thirdparty/common-customizations/sessions/ssr.mdx b/v2/thirdparty/common-customizations/sessions/ssr.mdx index 116901a02..863e5cb5b 100644 --- a/v2/thirdparty/common-customizations/sessions/ssr.mdx +++ b/v2/thirdparty/common-customizations/sessions/ssr.mdx @@ -83,7 +83,7 @@ export function AttemptRefresh(props: any) { ```tsx -import Session from 'supertokens-auth-react/recipe/session'; +import Session from 'supertokens-web-js/recipe/session'; function attemptRefresh() { Session.attemptRefreshingSession().then(success => { diff --git a/v2/thirdparty/common-customizations/sessions/token-transfer-method.mdx b/v2/thirdparty/common-customizations/sessions/token-transfer-method.mdx index d07b73456..05bf214db 100644 --- a/v2/thirdparty/common-customizations/sessions/token-transfer-method.mdx +++ b/v2/thirdparty/common-customizations/sessions/token-transfer-method.mdx @@ -71,6 +71,54 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUISession.init({ + // highlight-next-line + tokenTransferMethod: "header" // or "cookie" + }) + ] +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from "supertokens-web-js"; +import Session from "supertokens-web-js/recipe/session"; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + Session.init({ + // highlight-next-line + tokenTransferMethod: "header" // or "cookie" + }) + ], +}) +``` + + + diff --git a/v2/thirdparty/common-customizations/sessions/with-jwt/read-jwt.mdx b/v2/thirdparty/common-customizations/sessions/with-jwt/read-jwt.mdx index fe1b9a7e5..6406c10f2 100644 --- a/v2/thirdparty/common-customizations/sessions/with-jwt/read-jwt.mdx +++ b/v2/thirdparty/common-customizations/sessions/with-jwt/read-jwt.mdx @@ -435,7 +435,7 @@ async function getJWT() { ```tsx -import Session from 'supertokens-auth-react/recipe/session'; +import Session from 'supertokens-web-js/recipe/session'; async function getJWT() { if (await Session.doesSessionExist()) { diff --git a/v2/thirdparty/common-customizations/sign-in-and-up/built-in-providers.mdx b/v2/thirdparty/common-customizations/sign-in-and-up/built-in-providers.mdx index b1ac89d38..e66fffcea 100644 --- a/v2/thirdparty/common-customizations/sign-in-and-up/built-in-providers.mdx +++ b/v2/thirdparty/common-customizations/sign-in-and-up/built-in-providers.mdx @@ -62,6 +62,43 @@ SuperTokens.init({ }); ``` + + + + +Import and all the built in providers that you wish to show in the UI as shown below. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIThirdParty from "supertokens-auth-react-script/recipe/thirdparty"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIThirdParty.init({ + signInAndUpFeature: { + // highlight-start + providers: [ + supertokensUIThirdParty.Github.init(), + supertokensUIThirdParty.Google.init(), + supertokensUIThirdParty.Facebook.init(), + supertokensUIThirdParty.Apple.init(), + ], + // highlight-end + // ... + }, + // ... + }), + // ... + ] +}); +``` + @@ -108,6 +145,15 @@ SuperTokens.init({ ] }); ``` + + + + +:::caution +This is not possible for non react apps at the moment. Please use custom UI instead for the sign in form. +::: + + diff --git a/v2/thirdparty/common-customizations/sign-in-and-up/custom-providers.mdx b/v2/thirdparty/common-customizations/sign-in-and-up/custom-providers.mdx index f9861a33a..ee1e47137 100644 --- a/v2/thirdparty/common-customizations/sign-in-and-up/custom-providers.mdx +++ b/v2/thirdparty/common-customizations/sign-in-and-up/custom-providers.mdx @@ -69,6 +69,14 @@ SuperTokens.init({ ] }); ``` + + + + +:::caution +This is not possible for non react apps at the moment. Please use custom UI instead for the sign in form. +::: + diff --git a/v2/thirdparty/common-customizations/sign-in-and-up/toc-privacypolicy.mdx b/v2/thirdparty/common-customizations/sign-in-and-up/toc-privacypolicy.mdx index ae1ffaff3..380a49b86 100644 --- a/v2/thirdparty/common-customizations/sign-in-and-up/toc-privacypolicy.mdx +++ b/v2/thirdparty/common-customizations/sign-in-and-up/toc-privacypolicy.mdx @@ -2,20 +2,27 @@ id: toc-privacypolicy title: Terms of service & Privacy policy links hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" + + + +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Terms of service & Privacy policy links + + You can provide a Privacy policy and Terms of service link which will render the following text on the sign up page: - Provided both links: "By signing up, you agree to our [Terms of Service](./toc-privacypolicy) and [Privacy Policy](./toc-privacypolicy)" - Provided only Terms of service link: "By signing up, you agree to our [Terms of Service](./toc-privacypolicy)" - Provided only Privacy policy link: "By signing up, you agree to our [Privacy Policy](./toc-privacypolicy)" - + ```tsx @@ -27,10 +34,44 @@ SuperTokens.init({ appName: "...", websiteDomain: "..." }, + // highlight-start termsOfServiceLink: "https://example.com/terms-of-service", privacyPolicyLink: "https://example.com/privacy-policy", - recipeList: [ /* recipe list */] + // highlight-end + recipeList: [/* ... */] }); ``` - \ No newline at end of file + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + // highlight-start + termsOfServiceLink: "https://example.com/terms-of-service", + privacyPolicyLink: "https://example.com/privacy-policy", + // highlight-end + recipeList: [/* ... */] +}); +``` + + + + + + + +:::caution +Not applicable since you do not use our pre built UI. +::: + + + diff --git a/v2/thirdparty/common-customizations/styling/changing-colours.mdx b/v2/thirdparty/common-customizations/styling/changing-colours.mdx index b7a950cb4..1dcde3ccc 100644 --- a/v2/thirdparty/common-customizations/styling/changing-colours.mdx +++ b/v2/thirdparty/common-customizations/styling/changing-colours.mdx @@ -2,19 +2,24 @@ id: changing-colours title: Changing Colours hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Changing Colours + + + It is possible to update the default theme with your colours to make it fit perfectly with your website by defining a few css variables in the `style` property to the `ThirdParty.init` call. You have to specify the colors as RGB (see the following example), because we use the `rgb` and `rgba` functions to apply them. For example if your website uses a dark theme, here is how you can quickly customize it: - + ```tsx @@ -45,7 +50,39 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + // highlight-start + style: ` + [data-supertokens~=container] { + --palette-background: 51, 51, 51; + --palette-inputBackground: 41, 41, 41; + --palette-inputBorder: 41, 41, 41; + --palette-textTitle: 255, 255, 255; + --palette-textLabel: 255, 255, 255; + --palette-textPrimary: 255, 255, 255; + --palette-error: 173, 46, 46; + --palette-textInput: 169, 169, 169; + --palette-textLink: 169, 169, 169; + } + `, + // highlight-end + recipeList: [ /* ... */] +}); +``` + + Prebuilt UI with custom colors @@ -109,4 +146,14 @@ Changes to the palette will apply to all the UI components we provide. If you wa - Description: This value controls the color of the "Powered by SuperTokens" text on the bottom of sign-in/up pages - Default: ```173, 189, 196``` (heather grey) -Prebuilt UI SuperTokens label \ No newline at end of file +Prebuilt UI SuperTokens label + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/thirdparty/common-customizations/styling/changing-style.mdx b/v2/thirdparty/common-customizations/styling/changing-style.mdx index 6a717f70b..34e2bda33 100644 --- a/v2/thirdparty/common-customizations/styling/changing-style.mdx +++ b/v2/thirdparty/common-customizations/styling/changing-style.mdx @@ -2,13 +2,19 @@ id: changing-style title: Changing Style via CSS hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" + # Changing Style via CSS + + + Updating the CSS allows you to change the UI of our components to meet your needs. This section will guide you through an example of updating the look of headings. Note that the process can be applied to update any HTML tag from within SuperTokens components. @@ -27,7 +33,7 @@ Each stylable components contains `data-supertokens` attributes (in our example Let's customize elements with the `headerTitle` attribute. The syntax for styling is plain CSS. - + ```tsx @@ -58,7 +64,39 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIThirdParty from "supertokens-auth-react-script/recipe/thirdparty"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIThirdParty.init({ + // highlight-start + style: ` + [data-supertokens~=headerTitle { + border: 3px; + border-color: #000000; + border-style: solid; + } + ` + // highlight-end + }), + supertokensUISession.init() + ] +}); +``` + + The above will result in: @@ -68,7 +106,7 @@ The above will result in: By default, SuperTokens uses the Arial font. The best way to override this is to add a `font-family` styling to the `container` component in the recipe configuration. - + ```tsx @@ -89,13 +127,35 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + style: ` + [data-supertokens~=container] { + font-family: cursive; + } + `, + recipeList: [ /* ... */] +}); +``` + + ### Using media queries You may want to have different CSS for different viewports. This can be achieved via media queries like this: - + ```tsx @@ -131,13 +191,50 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIThirdParty from "supertokens-auth-react-script/recipe/thirdparty"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + // ... + recipeList: [ + supertokensUIThirdParty.init({ + style: ` + [data-supertokens~=headerTitle] { + border: 3px; + border-color: #000000; + border-style: solid; + } + + // highlight-start + @media (max-width: 440px) { + [data-supertokens~=headerTitle] { + border: 5px; + } + } + // highlight-end + ` + }), + ], +}); +``` + + ## Customising the Sign-Up / Sign-In form These are the screens shown when the user tries to log in or sign up for the application. - + ```tsx @@ -156,13 +253,33 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + style: `[data-supertokens~=authPage] { + ... + }`, + recipeList: [ /* ... */] +}); +``` + + ## Customizing the OAuth callback screen This screen is shown when the user returns to the application from the OAuth provider - + ```tsx @@ -189,4 +306,43 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIThirdParty from "supertokens-auth-react-script/recipe/thirdparty"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + supertokensUIThirdParty.init({ + // highlight-start + oAuthCallbackScreen: { + style: ` ... ` + } + // highlight-end + }), + supertokensUISession.init() + ] +}); +``` + + + + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/thirdparty/common-customizations/styling/shadow-dom.mdx b/v2/thirdparty/common-customizations/styling/shadow-dom.mdx index 8387f1aaf..eb9077930 100644 --- a/v2/thirdparty/common-customizations/styling/shadow-dom.mdx +++ b/v2/thirdparty/common-customizations/styling/shadow-dom.mdx @@ -2,13 +2,21 @@ id: shadow-dom title: Disable use of shadow DOM hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" + + + +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Disable use of shadow DOM + + + We use [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) to prevent CSS clashes between your CSS and the ones we provide. This guarantees that all our UI will render as expected. However, this has a few problems: @@ -17,7 +25,7 @@ However, this has a few problems: If you want to disable use of shadow dom, you can do so like: - + ```tsx @@ -31,12 +39,41 @@ SuperTokens.init({ }, // highlight-next-line useShadowDom: false, - recipeList: [ /* recipe list */] + recipeList: [/* ... */] +}); +``` + + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + // highlight-next-line + useShadowDom: false, + recipeList: [/* ... */] }); ``` - + :::caution If disabled, please be sure to check that our components render correctly - because your CSS might affect our components' UI (the other way around won't happen). -::: \ No newline at end of file +::: + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/thirdparty/common-customizations/translations.mdx b/v2/thirdparty/common-customizations/translations.mdx index d35aea28e..f3f598e31 100644 --- a/v2/thirdparty/common-customizations/translations.mdx +++ b/v2/thirdparty/common-customizations/translations.mdx @@ -2,16 +2,18 @@ id: translations title: Language Translation for the UI hide_title: true +show_ui_switcher: true --- - - -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs"; +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; -import NpmOrScriptTabs from "/src/components/tabs/NpmOrScriptTabs" +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Language Translation for the UI + + + You can translate the UI using two main methods: 1. You can override all displayed translation strings by providing translated versions for different languages (and even change the default English version). 2. You can provide a translation function to integrate supertokens with your preferred internationalization library. @@ -27,7 +29,7 @@ You can provide translations for each segment displayed in our UIs. - You can find the third party login UI keys [here](https://github.com/supertokens/supertokens-auth-react/blob/master/lib/ts/recipe/thirdparty/components/themes/translations.ts). ::: - + ```tsx @@ -72,13 +74,57 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +supertokensUIInit({ + // highlight-start + languageTranslations: { // This object contains all translation related options + translations: { // These are the displayed translation strings for each language + // The property names define the language code of the translations + en: { + // Here each key is a translation key and the value is the string that will be displayed + // Setting the value to undefined will either display the translation from the default language or the translation key + BRANDING_POWERED_BY_START: "We ❤️ ", + // If you added a custom label or placeholder you can also provide translation for them if necessary + // You can also use these to provide translations for your component overrides + MY_CUSTOM_LABEL: "Age", + }, + hu: { + BRANDING_POWERED_BY_START: "Sok szeretettel: ", + // This key is associated with an empty string by default, but you can override these as well. + BRANDING_POWERED_BY_END: " 😊", + } + }, + /* + * This optional property sets the default and fallback language. + * It can be any string that will be used to fetch translations from the above object. + * Defaults to "en" + */ + defaultLanguage: "hu", + }, + // highlight-end + appInfo: { + appName: "...", + apiDomain: "...", + websiteDomain: "...", + }, + recipeList: [ + // ... + ], +}); +``` + + ### Loading translations After initialization, you can provide additional translation data by calling the `SuperTokens.loadTranslation`. This can be useful if you are loading them asynchronously. - + ```tsx @@ -93,13 +139,27 @@ SuperTokens.loadTranslation({ }); ``` - + + + +```tsx +import supertokensUI from "supertokens-auth-react-script"; +// This method takes an object as a parameter, which is structured the same as above. +// This will be merged into the existing definitions, so any properties missing here won't remove them from the already loaded translations +supertokensUI.loadTranslation({ + en: { + BRANDING_POWERED_BY_END: " :)", + } +}); +``` + + ### Changing the current language You can update which translations store is displayed by calling the `SuperTokens.changeLanguage`. - + ```tsx @@ -108,7 +168,15 @@ import SuperTokens from "supertokens-auth-react"; SuperTokens.changeLanguage("hu"); ``` - + + + +```tsx +import supertokensUI from "supertokens-auth-react-script"; +supertokensUI.changeLanguage("hu"); +``` + + ## Using an internationalization library @@ -116,7 +184,7 @@ You can easily integrate SuperTokens with your internationalization library of c 1. Provide the translation function in `SuperTokens.init` - + ```tsx @@ -143,7 +211,33 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +supertokensUIInit({ + // highlight-start + languageTranslations: { + translationFunc: (key: string) => { + // The string returned by this function will be displayed + return key + "!"; + }, + }, + // highlight-end + appInfo: { + appName: "...", + apiDomain: "...", + websiteDomain: "...", + }, + recipeList: [ + // ... + ], +}); +``` + + 2. Call `SuperTokens.changeLanguage` or `SuperTokens.loadTranslation` to re-render the translated UI @@ -157,7 +251,7 @@ If the SDK can't find a segment in the current language's translation store, we The currently chosen language is stored in a cookie, this way it can be restored the next time the page loads. The domain of this cookie can be customized through the `currentLanguageCookieScope` option. This can be useful if you are running our SDK in multiple applications and want to share the language choice between sub-domains. - + ```tsx @@ -181,13 +275,36 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +supertokensUIInit({ + // highlight-start + languageTranslations: { + currentLanguageCookieScope: ".example.com", + }, + // highlight-end + appInfo: { + appName: "...", + apiDomain: "...", + websiteDomain: "...", + }, + recipeList: [ + // ... + ], +}); +``` + + ## Translations in component overrides The SDK also exports the `useTranslation` React hook you can use while overriding components. It returns a function that takes a translation segment key and returns it translated to the currently selected language. For more information on what translation keys you should use and the exact syntax, please see the original source code of the component you are overriding. - + ```tsx @@ -207,4 +324,23 @@ export const HeaderOverride = () => { ``` - + + + +:::caution +Not applicable for non react apps. +::: + + + + + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/thirdparty/pre-built-ui/auth-redirection.mdx b/v2/thirdparty/pre-built-ui/auth-redirection.mdx index 319295e7e..ed93e37c6 100644 --- a/v2/thirdparty/pre-built-ui/auth-redirection.mdx +++ b/v2/thirdparty/pre-built-ui/auth-redirection.mdx @@ -50,6 +50,47 @@ SuperTokens.init({ }); ``` + + + + +By default, the user is redirected the the `/` route on your website post login. To change this, you can use the `getRedirectionURL` function on the frontend as shown below: + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + // highlight-start + getRedirectionURL: async (context) => { + if (context.action === "SUCCESS" && context.newSessionCreated) { + if (context.redirectToPath !== undefined) { + // we are navigating back to where the user was before they authenticated + return context.redirectToPath; + } + if (context.createdNewUser) { + // user signed up + } else { + // user signed in + } + return "/dashboard"; + } + return undefined; + }, + // highlight-end + recipeList: [ /* Recipe list */] +}); +``` + + + + + The user will be redirected to the provided URL on: - Successful sign up. - Successful sign in. @@ -62,9 +103,6 @@ If you want to redirect the user to a different domain, then you can do so by fi Please refer to [this page](../advanced-customizations/frontend-hooks/redirection-callback) to learn more about the `getRedirectionURL` hook. ::: - - - ## Redirect user to the login page @@ -100,12 +138,10 @@ function NavBar () { -Use the `redirectToAuth({show?: "signin" | "signup", redirectBack?: boolean}?)` function to redirect the user to the login screen. For example, you may want to call this function when the user clicks on the login button. +Redirect the user to the `/auth` (this is the default path for the pre built UI) ```ts import { Component } from "@angular/core"; -// highlight-next-line -import { redirectToAuth } from "supertokens-auth-react"; @Component({ selector: 'nav-bar', @@ -120,20 +156,20 @@ import { redirectToAuth } from "supertokens-auth-react"; export class NavBarComponent { async onLogin () { // highlight-next-line - redirectToAuth(); + window.location.href = "/auth?show=signin&redirecToPath=" + encodeURIComponent(window.location.pathname); } } ``` -- Call `redirectToAuth({show: "signin"})` to take them to the sign in screen -- Call `redirectToAuth({show: "signup"})` to take them to the sign up screen -- If you do not want the user to be redirected to the current page post sign in, use `redirectToAuth({redirectBack: false})` +- Set `show=signin` to take them to the sign in screen +- Set `show=signup` to take them to the sign up screen +- Set `redirecToPath` to redirect the user to a specific page after they have signed in, or you can skip it to take them to the `/` route (which is the default one). -Use the `redirectToAuth({show?: "signin" | "signup", redirectBack?: boolean}?)` function to redirect the user to the login screen. For example, you may want to call this function when the user clicks on the login button. +Redirect the user to the `/auth` (this is the default path for the pre built UI) ```html ``` -- Call `redirectToAuth({show: "signin"})` to take them to the sign in screen -- Call `redirectToAuth({show: "signup"})` to take them to the sign up screen -- If you do not want the user to be redirected to the current page post sign in, use `redirectToAuth({redirectBack: false})` +- Set `show=signin` to take them to the sign in screen +- Set `show=signup` to take them to the sign up screen +- Set `redirecToPath` to redirect the user to a specific page after they have signed in, or you can skip it to take them to the `/` route (which is the default one). diff --git a/v2/thirdparty/pre-built-ui/enable-email-verification.mdx b/v2/thirdparty/pre-built-ui/enable-email-verification.mdx index af23b6e63..61cc6442a 100644 --- a/v2/thirdparty/pre-built-ui/enable-email-verification.mdx +++ b/v2/thirdparty/pre-built-ui/enable-email-verification.mdx @@ -213,6 +213,33 @@ function App() { + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + // highlight-start + supertokensUIEmailVerification.init({ + mode: "REQUIRED", // or "OPTIONAL" + }), + // highlight-end + supertokensUISession.init(), + ], +}); +``` + + + @@ -736,8 +763,8 @@ If all validations pass, we render the `props.children` component. ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { EmailVerificationClaim } from "supertokens-auth-react/recipe/emailverification"; +import Session from "supertokens-web-js/recipe/session"; +import { EmailVerificationClaim } from "supertokens-web-js/recipe/emailverification"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { diff --git a/v2/thirdparty/pre-built-ui/handling-session-tokens.mdx b/v2/thirdparty/pre-built-ui/handling-session-tokens.mdx index 6d37e05ca..11f2460fa 100644 --- a/v2/thirdparty/pre-built-ui/handling-session-tokens.mdx +++ b/v2/thirdparty/pre-built-ui/handling-session-tokens.mdx @@ -61,7 +61,15 @@ async function getToken(): Promise { -~COPY-TABS=reactjs +```tsx +import Session from "supertokens-web-js/recipe/session"; + +async function getToken(): Promise { + // highlight-next-line + const accessToken = await Session.getAccessToken(); + console.log(accessToken); +} +``` diff --git a/v2/thirdparty/pre-built-ui/securing-routes.mdx b/v2/thirdparty/pre-built-ui/securing-routes.mdx index 4df26e055..22d56941e 100644 --- a/v2/thirdparty/pre-built-ui/securing-routes.mdx +++ b/v2/thirdparty/pre-built-ui/securing-routes.mdx @@ -490,7 +490,7 @@ class App extends React.Component { You can use the `doesSessionExist` function to check if a session exists in all your routes. ```tsx -import Session from 'supertokens-auth-react/recipe/session'; +import Session from 'supertokens-web-js/recipe/session'; async function doesSessionExist() { if (await Session.doesSessionExist()) { diff --git a/v2/thirdparty/pre-built-ui/setup/frontend.mdx b/v2/thirdparty/pre-built-ui/setup/frontend.mdx index b3046e104..abd34c3ab 100644 --- a/v2/thirdparty/pre-built-ui/setup/frontend.mdx +++ b/v2/thirdparty/pre-built-ui/setup/frontend.mdx @@ -13,6 +13,7 @@ import {Question, Answer}from "/src/components/question" import AppInfoForm from "/src/components/appInfoForm" import RRDVersionSubTabs from "/src/components/tabs/RRDVersionSubTabs" import NpmVersionOrYarnSubTabs from "/src/components/tabs/NpmVersionOrYarnSubTabs" +import PreBuiltUIInjector from "/src/components/prebuiltuiInjector" # Frontend Integration @@ -70,58 +71,35 @@ yarn add supertokens-auth-react supertokens-web-js -:::important -SuperTokens does not provide Angular components for pre built UI, but, there are two ways of implementing SuperTokens in your Angular frontend: -- Load SuperTokens's pre-built React UI components in your Angular app. Continue following the guide for this flow. -- Build your own UI. Click [here](../../custom-ui/init/frontend) to learn more. -::: - -Start by installing the SuperTokens ReactJS SDK and React: +Start by installing the SuperTokens Web SDK: ```bash -npm i -s supertokens-auth-react +npm i -s supertokens-web-js ``` -:::important -SuperTokens does not provide Angular components for pre built UI, but, there are two ways of implementing SuperTokens in your Angular frontend: -- Load SuperTokens's pre-built React UI components in your Angular app. Continue following the guide for this flow. -- Build your own UI. Click [here](../../custom-ui/init/frontend) to learn more. -::: -Start by installing the SuperTokens ReactJS SDK and React: +Start by installing the SuperTokens Web SDK: ```bash -npm i -s supertokens-auth-react supertokens-web-js +npm i -s supertokens-web-js ``` -:::important -SuperTokens does not provide Angular components for pre built UI, but, there are two ways of implementing SuperTokens in your Angular frontend: -- Load SuperTokens's pre-built React UI components in your Angular app. Continue following the guide for this flow. -- Build your own UI. Click [here](../../custom-ui/init/frontend) to learn more. -::: -Start by installing the SuperTokens ReactJS SDK and React: +Start by installing the SuperTokens Web SDK: ```bash -yarn add supertokens-auth-react supertokens-web-js +yarn add supertokens-web-js ``` -You will also need to update `compilerOptions` in your `tsconfig.json` file with the following: - -```json title="tsconfig.json" -"jsx": "react", -"allowSyntheticDefaultImports": true, -``` - @@ -129,46 +107,30 @@ You will also need to update `compilerOptions` in your `tsconfig.json` file with -:::important -SuperTokens does not provide Vue components for pre built UI, but, there are two ways of implementing SuperTokens in your Vue frontend: -- Load SuperTokens's pre-built React UI components in your Vue app. Continue following the guide for this flow. -- Build your own UI. Click [here](../../custom-ui/init/frontend) to learn more. -::: - -Start by installing the SuperTokens ReactJS SDK and React: +Start by installing the SuperTokens web SDK: ```bash -npm i -s supertokens-auth-react +npm i -s supertokens-web-js ``` -:::important -SuperTokens does not provide Vue components for pre built UI, but, there are two ways of implementing SuperTokens in your Vue frontend: -- Load SuperTokens's pre-built React UI components in your Vue app. Continue following the guide for this flow. -- Build your own UI. Click [here](../../custom-ui/init/frontend) to learn more. -::: -Start by installing the SuperTokens ReactJS SDK and React: +Start by installing the SuperTokens web SDK: ```bash -npm i -s supertokens-auth-react supertokens-web-js +npm i -s supertokens-web-js ``` -:::important -SuperTokens does not provide Vue components for pre built UI, but, there are two ways of implementing SuperTokens in your Vue frontend: -- Load SuperTokens's pre-built React UI components in your Vue app. Continue following the guide for this flow. -- Build your own UI. Click [here](../../custom-ui/init/frontend) to learn more. -::: -Start by installing the SuperTokens ReactJS SDK and React: +Start by installing the SuperTokens web SDK: ```bash -yarn add supertokens-auth-react supertokens-web-js +yarn add supertokens-web-js ``` @@ -274,12 +236,14 @@ SuperTokens.init({ askForAPIDomain askForWebsiteDomain> -Before we initialize the `supertokens-auth-react` SDK let's see how we will use it in our Angular app + + +Before we initialize the `supertokens-web-js` SDK let's see how we will use it in our Angular app **Architecture** -- The `supertokens-auth-react` SDK is responsible for rendering the login UI, handling authentication flows and session management. -- Using `supertokens-auth-react`'s pre-built UI does not increase application's bundle size. React is only added to authentication-related routes. +- The `supertokens-web-js` SDK is responsible for session management and providing helper functions to check if a session exists, or validate the access token claims on the frontend (for example, to check for user roles before showing some UI). We will initialise this SDK on the root of your Angular app, so that all pages in your app can use it. +- We will create a `^{form_websiteBasePath}*` route in the Angular app which will render our pre built UI which will also need to be initialised, but only on that route. **Creating the `^{form_websiteBasePath}` route** @@ -289,104 +253,93 @@ Before we initialize the `supertokens-auth-react` SDK let's see how we will use ng generate module auth --route auth --module app.module ``` -- In your `auth` component folder create a react component `supertokensAuthComponent.tsx`. This component will be used to render appropriate UI when user visits the login page. - - ```tsx title="/app/auth/supertokensAuthComponent.tsx" - import * as React from "react"; - import * as SuperTokens from "supertokens-auth-react"; - import { canHandleRoute, getRoutingComponent } from "supertokens-auth-react/ui"; - ^{prebuiltuiimport} - - // highlight-start - class SuperTokensReactComponent extends React.Component { - override render() { - if (canHandleRoute([^{recipePreBuiltUINameCapitalLetters}])) { - return getRoutingComponent([^{recipePreBuiltUINameCapitalLetters}]); - } - return "Route not found"; - } - } - // highlight-end - - export default SuperTokensReactComponent; - ``` - -- Load `superTokensAuthComponent` in the `auth` angular component +- Add the following code to your `auth` angular component ```tsx title="/app/auth/auth.component.ts" - import { AfterViewInit, Component, OnDestroy } from "@angular/core"; - import * as React from "react"; - import * as ReactDOM from "react-dom"; - // @ts-ignore - import SuperTokensReactComponent from "./supertokensAuthComponent.tsx"; + import {init as supertokensUIInit} from "supertokens-auth-react-script"; + import supertokensUIThirdParty from "supertokens-auth-react-script/recipe/thirdparty"; + import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + import { Component, OnDestroy, AfterViewInit, Renderer2, Inject } from "@angular/core"; + import { DOCUMENT } from "@angular/common"; @Component({ selector: "app-auth", - template: '
', + template: '
', }) - export class AuthComponent implements AfterViewInit, OnDestroy { - title = "angularreactapp"; + export class AuthComponent implements OnDestroy, AfterViewInit { - public rootId = "rootId"; + constructor( + private renderer: Renderer2, + @Inject(DOCUMENT) private document: Document + ) { } - // highlight-start - // We use the ngAfterViewInit lifecycle hook to render the React component after the Angular component view gets initialized ngAfterViewInit() { - ReactDOM.render(React.createElement(SuperTokensReactComponent), document.getElementById(this.rootId)); + this.loadScript('^{jsdeliver_prebuiltui}'); } - // We use the ngOnDestroy lifecycle hook to unmount the React component when the Angular wrapper component is destroyed. ngOnDestroy() { - ReactDOM.unmountComponentAtNode(document.getElementById(this.rootId) as Element); + // Remove the script when the component is destroyed + const script = this.document.getElementById('supertokens-script'); + if (script) { + script.remove(); + } + } + + private loadScript(src: string) { + const script = this.renderer.createElement('script'); + script.type = 'text/javascript'; + script.src = src; + script.id = 'supertokens-script'; + script.onload = () => { + supertokensUIInit({ + appInfo: { + appName: "^{form_appName}", + apiDomain: "^{form_apiDomain}", + websiteDomain: "^{form_websiteDomain}", + apiBasePath: "^{form_apiBasePath}", + websiteBasePath: "^{form_websiteBasePath}" + }, + recipeList: [ + supertokensUIThirdParty.init({ + signInAndUpFeature: { + providers: [ + supertokensUIThirdParty.Github.init(), + supertokensUIThirdParty.Google.init(), + supertokensUIThirdParty.Facebook.init(), + supertokensUIThirdParty.Apple.init(), + ] + } + }), + supertokensUISession.init(), + ], + }); + } + this.renderer.appendChild(this.document.body, script); } - // highlight-end } ``` + - In the `loadScript` function, we provide the SuperTokens config for the UI. We add the session and social login recipes along with Github, Google, Facebook and Apple login buttons. -- Initialize the `supertokens-auth-react` SDK in your angular app's root component. This will provide session management across your entire application. - - ```tsx title="/app/app.component.ts " - import { Component } from "@angular/core"; - - import * as SuperTokens from "supertokens-auth-react"; - import * as ThirdParty from "supertokens-auth-react/recipe/thirdparty"; - import { Github, Google, Facebook, Apple } from "supertokens-auth-react/recipe/thirdparty"; - import Session from "supertokens-auth-react/recipe/session"; +- Initialize the `supertokens-web-js` SDK in your angular app's root component. This will provide session management across your entire application. + ```tsx title="/app/app.component.ts " + import SuperTokens from "supertokens-web-js"; + import Session from "supertokens-web-js/recipe/session"; + SuperTokens.init({ - // highlight-start appInfo: { appName: "^{form_appName}", apiDomain: "^{form_apiDomain}", - websiteDomain: "^{form_websiteDomain}", apiBasePath: "^{form_apiBasePath}", - websiteBasePath: "^{form_websiteBasePath}" }, recipeList: [ - ThirdParty.init({ - signInAndUpFeature: { - providers: [ - Github.init(), - Google.init(), - Facebook.init(), - Apple.init(), - ], - }, - }), Session.init(), ], - // highlight-end }); - - @Component({ - selector: "app-root", - template: "", - }) - export class AppComponent { - title = "^{form_appName}"; - } ``` + + @@ -398,98 +351,99 @@ Before we initialize the `supertokens-auth-react` SDK let's see how we will use askForAPIDomain askForWebsiteDomain> -Before we initialize the `supertokens-auth-react` SDK let's see how we will use it in our Vue app + + +Before we initialize the `supertokens-web-js` SDK let's see how we will use it in our Vue app **Architecture** -- The `supertokens-auth-react` SDK is responsible for rendering the login UI, handling authentication flows and session management. -- Using `supertokens-auth-react`'s pre-built UI does not increase application's bundle size. React is only added to authentication-related routes. +- The `supertokens-web-js` SDK is responsible for session management and providing helper functions to check if a session exists, or validate the access token claims on the frontend (for example, to check for user roles before showing some UI). We will initialise this SDK on the root of your Vue app, so that all pages in your app can use it. +- We will create a `^{form_websiteBasePath}*` route in the Vue app which will render our pre built UI which will also need to be initialised, but only on that route. **Creating the `^{form_websiteBasePath}` route** -- Create a new file `AuthView.vue`, this Vue component will be used to render the auth component - -- Create a React component `Supertokens.tsx`. This component will be used to render appropriate UI when user visits the login page. - - ```tsx title="/components/Supertokens.tsx" - import * as SuperTokens from "supertokens-auth-react"; - import { canHandleRoute, getRoutingComponent } from "supertokens-auth-react/ui"; - ^{prebuiltuiimport} - - // highlight-start - function SuperTokensReactComponent(props: any){ - if (canHandleRoute([^{recipePreBuiltUINameCapitalLetters}])) { - return getRoutingComponent([^{recipePreBuiltUINameCapitalLetters}]); - } - return "Route not found"; - } - // highlight-end - - export default SuperTokensReactComponent; - ``` - -- Load `SuperTokensReactComponent` in the `AuthView.vue` component - - ```html title="/views/AuthView.vue" +- Create a new file `AuthView.vue`, this Vue component will be used to render the auth component: + ```tsx + import {init as supertokensUIInit} from "supertokens-auth-react-script"; + import supertokensUIThirdParty from "supertokens-auth-react-script/recipe/thirdparty"; + import supertokensUISession from "supertokens-auth-react-script/recipe/session"; ``` + - In the `loadScript` function, we provide the SuperTokens config for the UI. We add the session and social login recipes along with Github, Google, Facebook and Apple login buttons. -- Initialize the `supertokens-auth-react` SDK in your Vue app's `main.ts` file. This will provide session management across your entire application. +- Initialize the `supertokens-web-js` SDK in your Vue app's `main.ts` file. This will provide session management across your entire application. ```tsx title="/main.ts " // @ts-ignore import { createApp } from "vue"; - import * as SuperTokens from "supertokens-auth-react"; - import * as ThirdParty from "supertokens-auth-react/recipe/thirdparty"; - import { Github, Google, Facebook, Apple } from "supertokens-auth-react/recipe/thirdparty"; - import Session from "supertokens-auth-react/recipe/session"; - + import SuperTokens from "supertokens-web-js"; + import Session from "supertokens-web-js/recipe/session"; // @ts-ignore import App from "./App.vue"; // @ts-ignore import router from "./router"; SuperTokens.init({ - // highlight-start appInfo: { appName: "^{form_appName}", apiDomain: "^{form_apiDomain}", - websiteDomain: "^{form_websiteDomain}", apiBasePath: "^{form_apiBasePath}", - websiteBasePath: "^{form_websiteBasePath}" }, recipeList: [ - ThirdParty.init({ - signInAndUpFeature: { - providers: [ - Github.init(), - Google.init(), - Facebook.init(), - Apple.init(), - ], - }, - }), Session.init(), ], - // highlight-end }); const app = createApp(App); @@ -497,8 +451,11 @@ Before we initialize the `supertokens-auth-react` SDK let's see how we will use app.use(router); app.mount("#app"); + ``` + + @@ -689,6 +646,8 @@ Update your Vue router so that all auth related requests load the `AuthView` com import { createRouter, createWebHistory } from "vue-router"; // @ts-ignore import HomeView from "../views/HomeView.vue"; +// @ts-ignore +import AuthView from "../views/AuthView.vue"; const router = createRouter({ // @ts-ignore @@ -702,8 +661,7 @@ const router = createRouter({ { path: "^{form_websiteBasePath}/:pathMatch(.*)*", name: "auth", - // @ts-ignore - component: () => import("../views/AuthView.vue"), + component: AuthView, }, ], }); diff --git a/v2/thirdparty/pre-built-ui/sign-out.mdx b/v2/thirdparty/pre-built-ui/sign-out.mdx index 8b25a1f07..799748faa 100644 --- a/v2/thirdparty/pre-built-ui/sign-out.mdx +++ b/v2/thirdparty/pre-built-ui/sign-out.mdx @@ -42,11 +42,11 @@ function NavBar() { -The [`signOut` method](https://supertokens.com/docs/auth-react/modules/recipe_session.html#signOut-1) revokes the session for the user. +The [`signOut` method](https://supertokens.com/docs/web-js/modules/recipe_session.html#signOut-1) revokes the session for the user. ```tsx // highlight-next-line -import Session from "supertokens-auth-react/recipe/session"; +import Session from "supertokens-web-js/recipe/session"; async function logout () { // highlight-next-line diff --git a/v2/thirdparty/troubleshooting/how-to-troubleshoot.mdx b/v2/thirdparty/troubleshooting/how-to-troubleshoot.mdx index 41507a865..901aaa4d7 100644 --- a/v2/thirdparty/troubleshooting/how-to-troubleshoot.mdx +++ b/v2/thirdparty/troubleshooting/how-to-troubleshoot.mdx @@ -132,6 +132,45 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + // highlight-next-line + enableDebugLogs: true, + // @ts-ignore + appInfo: { /*...*/ }, + // @ts-ignore + recipeList: [/*...*/] +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from 'supertokens-web-js'; +import Session from 'supertokens-web-js/recipe/session'; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + Session.init(), + ], + // highlight-next-line + enableDebugLogs: true, +}); +``` + + + diff --git a/v2/thirdparty/user-roles/protecting-routes.mdx b/v2/thirdparty/user-roles/protecting-routes.mdx index b3ea9478d..58c95e15f 100644 --- a/v2/thirdparty/user-roles/protecting-routes.mdx +++ b/v2/thirdparty/user-roles/protecting-routes.mdx @@ -1224,8 +1224,8 @@ function ProtectedComponent() { ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { @@ -1268,8 +1268,8 @@ async function shouldLoadRoute(): Promise { If you want to have more complex access control, you can get the roles list from the session as follows, and check the list yourself: ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { diff --git a/v2/thirdpartyemailpassword/advanced-customizations/frontend-functions-override/usage.mdx b/v2/thirdpartyemailpassword/advanced-customizations/frontend-functions-override/usage.mdx index e1f21d76c..3069ad3b0 100644 --- a/v2/thirdpartyemailpassword/advanced-customizations/frontend-functions-override/usage.mdx +++ b/v2/thirdpartyemailpassword/advanced-customizations/frontend-functions-override/usage.mdx @@ -2,22 +2,27 @@ id: usage title: How to use hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # How to use ## Use the override config + + + + + + :::info See all the [functions that can be overrided here](https://supertokens.com/docs/auth-react/modules/recipe_thirdpartyemailpassword.html#RecipeInterface) ::: - - - ```tsx import SuperTokens from "supertokens-auth-react"; import ThirdParty from "supertokens-auth-react/recipe/thirdparty"; @@ -78,7 +83,86 @@ SuperTokens.init({ }); ``` - + + + +:::info +See all the [functions that can be overrided here](https://supertokens.com/docs/auth-react/modules/recipe_thirdpartyemailpassword.html#RecipeInterface) +::: + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIThirdParty from "supertokens-auth-react-script/recipe/thirdparty"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailPassword.init({ + // highlight-start + override: { + functions: (originalImplementation) => { + return { + ...originalImplementation, + + // we will only be overriding what happens when a user + // clicks the sign up button. + signUp: async function (input) { + // TODO: some custom logic + + // or call the default behaviour as show below + return originalImplementation.signUp(input); + }, + // ... + // TODO: override more functions + } + } + } + // highlight-end + }), + supertokensUIThirdParty.init({ + // highlight-start + override: { + functions: (originalImplementation) => { + return { + ...originalImplementation, + + // we will only be overriding what happens when a user + // clicks the sign in or sign up button. + signInAndUp: async function (input) { + // TODO: some custom logic + + // or call the default behaviour as show below + return originalImplementation.signInAndUp(input); + }, + // ... + // TODO: override more functions + } + } + } + // highlight-end + }) + ] +}); +``` + + + - `originalImplementation` is an object that contains functions that have the original implementation for this recipe. They can be used in your functions as a way to use the SuperTokens' default behaviour. -- In the above code snippet, we override the `signInAndUp` function of the ThirdParty recipe and `signUp` of the EmailPassword recipe. This means that when the user clicks the sign up button in the UI, your function will be called with the relevant `input` object. \ No newline at end of file +- In the above code snippet, we override the `signInAndUp` function of the ThirdParty recipe and `signUp` of the EmailPassword recipe. This means that when the user clicks the sign up button in the UI, your function will be called with the relevant `input` object. + + + + +:::caution +Not applicable since you need to build custom UI anyway, so when you call the functions from our SDK, or call the API directly, you can run pre / post logic in your own code. +::: + + + diff --git a/v2/thirdpartyemailpassword/advanced-customizations/frontend-hooks/handle-event.mdx b/v2/thirdpartyemailpassword/advanced-customizations/frontend-hooks/handle-event.mdx index b30a09f4b..a27d7d0ec 100644 --- a/v2/thirdpartyemailpassword/advanced-customizations/frontend-hooks/handle-event.mdx +++ b/v2/thirdpartyemailpassword/advanced-customizations/frontend-hooks/handle-event.mdx @@ -2,16 +2,21 @@ id: handle-event title: Handle Event Hook hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Handle Event Hook + + + This function is called for various user actions. It can be used for logging, analytics or any side effect purposes (these are essentially fire and forget events). - + ```tsx @@ -57,8 +62,65 @@ ThirdParty.init({ }) ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import supertokensUIThirdParty from "supertokens-auth-react-script/recipe/thirdparty"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; + +supertokensUIEmailPassword.init({ + onHandleEvent: (context) => { + if (context.action === "PASSWORD_RESET_SUCCESSFUL") { + + } else if (context.action === "RESET_PASSWORD_EMAIL_SENT") { + + } else if (context.action === "SUCCESS") { + if (context.createdNewSession) { + let user = context.user; + if (context.isNewRecipeUser && context.user.loginMethods.length === 1) { + // sign up success + } else { + // sign in success + } + } else { + // during step up or second factor auth with email password + } + } + } +}) + +supertokensUIThirdParty.init({ + onHandleEvent: (context) => { + if (context.action === "SUCCESS") { + if (context.createdNewSession) { + let user = context.user; + if (context.isNewRecipeUser && context.user.loginMethods.length === 1) { + // sign up success + } else { + // sign in success + } + } else { + // during linking a social account to an existing account + } + } + } +}) +``` + + :::info Also checkout the [session recipe hand event hook](/docs/session/advanced-customizations/frontend-hooks/handle-event). -::: \ No newline at end of file +::: + + + + +:::caution +Not applicable since you need to build custom UI anyway, so when you call the functions from our SDK, or call the API directly, you can run pre / post logic in your own code. +::: + + + \ No newline at end of file diff --git a/v2/thirdpartyemailpassword/advanced-customizations/frontend-hooks/pre-api.mdx b/v2/thirdpartyemailpassword/advanced-customizations/frontend-hooks/pre-api.mdx index d7a3a19b9..ee177d684 100644 --- a/v2/thirdpartyemailpassword/advanced-customizations/frontend-hooks/pre-api.mdx +++ b/v2/thirdpartyemailpassword/advanced-customizations/frontend-hooks/pre-api.mdx @@ -83,6 +83,70 @@ EmailPassword.init({ ``` + + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import supertokensUIThirdParty from "supertokens-auth-react-script/recipe/thirdparty"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; + +supertokensUIThirdParty.init({ + preAPIHook: async (context) => { + let url = context.url; + let requestInit = context.requestInit; + + let action = context.action; + if (action === "GET_AUTHORISATION_URL") { + + } else if (action === "THIRD_PARTY_SIGN_IN_UP") { + // Note: this could either be sign in or sign up. + // we don't know that at the time of the API call + // since all we have is the authorisation code from + // the social provider + } + + // events such as sign out are in the + // session recipe pre API hook (See the info box below) + + return { + requestInit, url + }; + + } +}) + +supertokensUIEmailPassword.init({ + preAPIHook: async (context) => { + let url = context.url; + let requestInit = context.requestInit; + + let action = context.action; + if (action === "EMAIL_EXISTS") { + + } else if (action === "EMAIL_PASSWORD_SIGN_IN") { + + } else if (action === "EMAIL_PASSWORD_SIGN_UP") { + + } else if (action === "SEND_RESET_PASSWORD_EMAIL") { + + } else if (action === "SUBMIT_NEW_PASSWORD") { + + } + + // events such as sign out are in the + // session recipe pre API hook (See the info box below) + + return { + requestInit, url + }; + + } +}) +``` + + diff --git a/v2/thirdpartyemailpassword/advanced-customizations/frontend-hooks/redirection-callback.mdx b/v2/thirdpartyemailpassword/advanced-customizations/frontend-hooks/redirection-callback.mdx index 24eb91479..ed1671ab3 100644 --- a/v2/thirdpartyemailpassword/advanced-customizations/frontend-hooks/redirection-callback.mdx +++ b/v2/thirdpartyemailpassword/advanced-customizations/frontend-hooks/redirection-callback.mdx @@ -2,16 +2,21 @@ id: redirection-callback title: Redirection Callback Hook hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Redirection Callback Hook + + + This function is used to change where the user is redirected to post certain actions. For example, you can use this to redirect a user to a specific URL post sign in / up. If you're embedding the sign in / up components in a popup and wish to disable redirection entirely, simply return `null`. - + ```tsx @@ -59,4 +64,63 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; + +supertokensUIInit({ + appInfo: { + appName: "SuperTokens", + apiDomain: "http://localhost:3000", + websiteDomain: "http://localhost:3000" + }, + getRedirectionURL: async (context) => { + if (context.action === "SUCCESS" && context.newSessionCreated) { + // called on a successful sign in / up. Where should the user go next? + let redirectToPath = context.redirectToPath; + if (redirectToPath !== undefined) { + // we are navigating back to where the user was before they authenticated + return redirectToPath; + } + if (context.createdNewUser) { + // user signed up + return "/onboarding" + } else { + // user signed in + return "/dashboard" + } + } else if (context.action === "TO_AUTH") { + // called when the user is not authenticated and needs to be redirected to the auth page. + return "/auth"; + } + // return undefined to let the default behaviour play out + return undefined; + }, + recipeList: [ + supertokensUIEmailPassword.init({ + getRedirectionURL: async (context) => { + if (context.action === "RESET_PASSWORD") { + // called when the user clicked on the forgot password button + } + // return undefined to let the default behaviour play out + return undefined; + } + })] +}); +``` + + + + + + +:::caution +Not applicable since you need to build custom UI anyway, so you can redirect the user after calling our SDK functions / API. +::: + + + diff --git a/v2/thirdpartyemailpassword/advanced-customizations/react-component-override/usage.mdx b/v2/thirdpartyemailpassword/advanced-customizations/react-component-override/usage.mdx index e961af9ee..505fa158d 100644 --- a/v2/thirdpartyemailpassword/advanced-customizations/react-component-override/usage.mdx +++ b/v2/thirdpartyemailpassword/advanced-customizations/react-component-override/usage.mdx @@ -2,22 +2,27 @@ id: usage title: How to use hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" import {Answer} from "/src/components/question" import {Question}from "/src/components/question" # How to use + + + + + + 1. You will have to use the `ThirdpartyComponentsOverrideProvider`, `EmailPasswordComponentsOverrideProvider` or the `AuthRecipeComponentsOverrideContextProvider` component as shown below. make sure that it render the SuperTokens components inside this component. 2. [Pick a component](#finding-which-component-will-be-overridden) that you'd like to override by its key. 3. Supply a React component against the key you have picked. Your custom component will get the original component as a `prop`. -## Example - - @@ -142,9 +147,6 @@ export default App; Please make sure that the file in which this config is specified is a `.tsx` or ` .jsx` file type. ::: - - - ## Finding which component will be overridden To do that, you should use React Developer Tools extension which provides a component tree inspector. @@ -172,3 +174,23 @@ const customComponent = ({ DefaultComponent, ...props }: { DefaultComponent: Rea ) } ``` + + + + +:::caution +Not applicable to non-react apps. You can disable the specific pre built UI component, and then build your own UI instead. +::: + + + + + + + +:::caution +Not applicable to custom UI +::: + + + \ No newline at end of file diff --git a/v2/thirdpartyemailpassword/common-customizations/changing-base-path/api-base-path.mdx b/v2/thirdpartyemailpassword/common-customizations/changing-base-path/api-base-path.mdx index 7c2e33fed..4a77fa6c8 100644 --- a/v2/thirdpartyemailpassword/common-customizations/changing-base-path/api-base-path.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/changing-base-path/api-base-path.mdx @@ -112,6 +112,45 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +supertokensUIInit({ + appInfo: { + appName: "yourAppName", + apiDomain: "yourApi", + websiteDomain: "yourWebsite", + // highlight-next-line + apiBasePath: "/api/v3/auth" + }, + recipeList: [], +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +// this goes in the root of your frontend app +import SuperTokens from "supertokens-web-js"; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + // highlight-next-line + apiBasePath: "/api/v3/auth", + appName: "...", + }, + recipeList: [/* ... */], +}); +``` + + + diff --git a/v2/thirdpartyemailpassword/common-customizations/changing-base-path/website-base-path.mdx b/v2/thirdpartyemailpassword/common-customizations/changing-base-path/website-base-path.mdx index 0795a935f..3e3e959bd 100644 --- a/v2/thirdpartyemailpassword/common-customizations/changing-base-path/website-base-path.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/changing-base-path/website-base-path.mdx @@ -2,6 +2,7 @@ id: website-base-path title: Website Base Path hide_title: true +show_ui_switcher: true --- @@ -9,6 +10,7 @@ hide_title: true import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" import BackendSDKTabs from "/src/components/tabs/BackendSDKTabs" import BackendSDKCasing from "/src/components/BackendSDKCasing" import TabItem from '@theme/TabItem'; @@ -16,6 +18,10 @@ import TabItem from '@theme/TabItem'; # Website Base Path ## Step 1) Front End Change + + + + Since the beginning of this guide, you probably noticed that all the front-end routes for SuperTokens widget are prefixed by `/auth`. You can change this value in the `init` function by setting websiteBasePath. @@ -39,8 +45,36 @@ SuperTokens.init({ + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +supertokensUIInit({ + appInfo: { + appName: "yourAppName", + apiDomain: "yourApi", + websiteDomain: "yourWebsite", + // highlight-next-line + websiteBasePath: "/authentication" + }, + recipeList: [], +}); +``` + + + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + ## Step 2) Back End Change diff --git a/v2/thirdpartyemailpassword/common-customizations/disable-sign-up/emailpassword-changes.mdx b/v2/thirdpartyemailpassword/common-customizations/disable-sign-up/emailpassword-changes.mdx index b8ea86008..2e4730707 100644 --- a/v2/thirdpartyemailpassword/common-customizations/disable-sign-up/emailpassword-changes.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/disable-sign-up/emailpassword-changes.mdx @@ -142,6 +142,29 @@ SuperTokens.init({ + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + style: ` + [data-supertokens~=authPage] [data-supertokens~=headerSubtitle] { + display: none; + } + `, + recipeList: [ /* ... */] +}); +``` + + + diff --git a/v2/thirdpartyemailpassword/common-customizations/email-verification/about.mdx b/v2/thirdpartyemailpassword/common-customizations/email-verification/about.mdx index 12e146de8..38e945c5f 100644 --- a/v2/thirdpartyemailpassword/common-customizations/email-verification/about.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/email-verification/about.mdx @@ -212,6 +212,54 @@ function App() { + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + // highlight-start + supertokensUIEmailVerification.init({ + mode: "REQUIRED", // or "OPTIONAL" + }), + // highlight-end + ], +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from "supertokens-web-js"; +import EmailVerification from "supertokens-web-js/recipe/emailverification"; +import Session from "supertokens-web-js/recipe/session"; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + // highlight-next-line + EmailVerification.init(), + Session.init(), + ], +}); +``` + + + :::important diff --git a/v2/thirdpartyemailpassword/common-customizations/email-verification/changing-style.mdx b/v2/thirdpartyemailpassword/common-customizations/email-verification/changing-style.mdx index 596a7ca00..de0cbe03c 100644 --- a/v2/thirdpartyemailpassword/common-customizations/email-verification/changing-style.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/email-verification/changing-style.mdx @@ -2,19 +2,20 @@ id: changing-style title: Changing Style via CSS hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Changing Style via CSS -:::important -This is applicable to prebuilt UI only. -::: + + Updating the CSS allows you to change the UI of our components to meet your needs. @@ -30,7 +31,7 @@ Each stylable components contains `data-supertokens` attributes (in our example Let's add a `border` to our `link` elements. The syntax for styling is plain CSS. - + ```tsx @@ -62,7 +63,38 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailVerification.init({ + // highlight-start + style: ` + [data-supertokens~=link] { + border: 2px solid #0076ff; + border-radius: 5; + width: 30%; + margin: 0 auto; + } + `, + // highlight-end + }) + ] +}); +``` + + + The above will result in: @@ -72,7 +104,7 @@ The above will result in: By default, SuperTokens uses the Arial font. The best way to override this is to add a `font-family` styling to the `container` component in the recipe configuration. - + ```tsx @@ -101,13 +133,39 @@ SuperTokens.init({ }); ``` - + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailVerification.init({ + // highlight-start + style: ` + [data-supertokens~=container] { + font-family: cursive + } + ` + // highlight-end + }), + ] +}); +``` + + ### Using media queries You may want to have different CSS for different viewports. This can be achieved via media queries like this: - + ```tsx @@ -145,7 +203,44 @@ SuperTokens.init({ }); ``` - + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + // ... + supertokensUIEmailVerification.init({ + // ... + style: ` + [data-supertokens~=link] { + border: 2px solid #0076ff; + borderRadius: 5; + width: 30%; + margin: 0 auto; + } + + // highlight-start + @media (max-width: 440px) { + [data-supertokens~=link] { + width: 90%; + } + } + // highlight-end + `, + }), + ], +}); +``` + + ## Customising individual screens @@ -153,7 +248,7 @@ SuperTokens.init({ This screen is where the user is redirected if `mode` is set to `REQUIRED` and they visit a path that requires a verified email. - + ```tsx @@ -180,13 +275,38 @@ SuperTokens.init({ }); ``` - + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + supertokensUIEmailVerification.init({ + // highlight-start + sendVerifyEmailScreen: { + style: ` ... ` + } + // highlight-end + }) + ] +}); +``` + + ### Verify link clicked screen This is the screen shown to users that click the email verification link in the email. - + ```tsx @@ -213,4 +333,41 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + supertokensUIEmailVerification.init({ + // highlight-start + verifyEmailLinkClickedScreen: { + style: ` ... `, + } + // highlight-end + }) + ] +}); +``` + + + + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/thirdpartyemailpassword/common-customizations/email-verification/embed-in-page.mdx b/v2/thirdpartyemailpassword/common-customizations/email-verification/embed-in-page.mdx index 8f8a84e8d..7ceccdb63 100644 --- a/v2/thirdpartyemailpassword/common-customizations/email-verification/embed-in-page.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/email-verification/embed-in-page.mdx @@ -2,20 +2,25 @@ id: embed-in-page title: Embed in a page hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" import BackendSDKTabs from "/src/components/tabs/BackendSDKTabs" # Embed in a page + + + ## Step 1: Disable the default implementation - + ```tsx @@ -42,11 +47,39 @@ SuperTokens.init({ If you navigate to `/auth/verify-email`, you should not see the widget anymore. - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailVerification.init({ + mode: "REQUIRED", + // highlight-start + disableDefaultUI: true + // highlight-end + }), + ] +}); +``` + +If you navigate to `/auth/verify-email`, you should not see the widget anymore. + + + ## Step 2: Render the component yourself - + Add the `EmailVerification` component in your app: @@ -68,7 +101,27 @@ class EmailVerificationPage extends React.Component { } ``` - + + + +:::caution +You will have to build your own UI instead. +::: + + + + + + + +## Step 1 & 2: Disable the pre built UI + +:::caution +Not applicable since you do not use our pre built UI +::: + + + ## Step 3: Changing the website path for the email verification UI (optional) @@ -208,7 +261,10 @@ init( ### Step B: On the frontend - + + + + ```tsx @@ -238,4 +294,45 @@ SuperTokens.init({ }) ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + supertokensUIEmailVerification.init({ + mode: "REQUIRED", + //highlight-start + + // The user will be taken to the custom path when they need to get their email verified. + getRedirectionURL: async (context) => { + if (context.action === "VERIFY_EMAIL") { + return "/custom-email-verification-path"; + }; + } + //highlight-end + }) + ] +}) +``` + + + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + \ No newline at end of file diff --git a/v2/thirdpartyemailpassword/common-customizations/email-verification/protecting-routes.mdx b/v2/thirdpartyemailpassword/common-customizations/email-verification/protecting-routes.mdx index d7d7a5ca0..e0bf31003 100644 --- a/v2/thirdpartyemailpassword/common-customizations/email-verification/protecting-routes.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/email-verification/protecting-routes.mdx @@ -1114,8 +1114,8 @@ function ProtectedComponent() { ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { EmailVerificationClaim } from "supertokens-auth-react/recipe/emailverification"; +import Session from "supertokens-web-js/recipe/session"; +import { EmailVerificationClaim } from "supertokens-web-js/recipe/emailverification"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { diff --git a/v2/thirdpartyemailpassword/common-customizations/embed-sign-in-up-form.mdx b/v2/thirdpartyemailpassword/common-customizations/embed-sign-in-up-form.mdx index 6c40977e3..b197c8474 100644 --- a/v2/thirdpartyemailpassword/common-customizations/embed-sign-in-up-form.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/embed-sign-in-up-form.mdx @@ -16,12 +16,14 @@ import RRDVersionSubTabs from "/src/components/tabs/RRDVersionSubTabs" + + + + ## Case 1: Rendering the Auth Widget in a page The following example shows the scenario where you have a dedicated route, such as `/auth`, for rendering the Auth Widget. Upon a successful login, the user will be automatically redirected to the return value of `getRedirectionURL` (defaulting to `/`). - - @@ -187,8 +189,7 @@ function MyAuthPage() { ``` - - + In the above code snippet, we: @@ -205,8 +206,6 @@ When the user visits the `/auth` page, they will see the SignIn UI by default. T The following example shows the scenario where you have a dedicated route, such as `/auth`, for rendering the Auth Widget. However, upon a successful login, the user will see a logged in UI instead of getting redirected. - - @@ -429,8 +428,7 @@ function LandingPage() { ``` - - + In the above code snippet, we wrap the logged-in component with `Session.SessionAuth` to validate all claims before displaying the logged-in UI. For instance, with email verification enabled, if a user's email is unverified, `Session.SessionAuth` redirects to the email verification page. @@ -442,8 +440,6 @@ In the above case, redirection may occur if a claim fails. For instance, in the The following example shows the scenario where you embed the Auth Widget in a popup, and upon successful login, you aim to close the popup. - - @@ -705,21 +701,11 @@ function AuthPopup() { ``` - - :::note In the above case, redirection may occur if a claim fails. For instance, in the case of an Email Verification claim, if the user's email is not verified, they will be redirected to the email verification page. To prevent redirection for failed claims, please contact us on [Discord](https://supertokens.com/discord) for assistance. ::: - - - -This guide is not applicable for Custom UI. - - - - ## Rendering only email password / third party login instead of both There may be a case where you want to render just one of the login methods on a particular page. @@ -754,4 +740,23 @@ function MyAuthPage() { } ``` -The idea behind this is that we provide the `factors` prop to the `AuthPage`, which tells it that we only want to render the third party password UI. The `preBuiltUIList` prop is still required, and we pass in the `ThirdPartyPreBuiltUI` component to it. We could also pass in the `EmailPasswordPreBuiltUI` component to it as shown in the code blocks above, but it's not needed. \ No newline at end of file +The idea behind this is that we provide the `factors` prop to the `AuthPage`, which tells it that we only want to render the third party password UI. The `preBuiltUIList` prop is still required, and we pass in the `ThirdPartyPreBuiltUI` component to it. We could also pass in the `EmailPasswordPreBuiltUI` component to it as shown in the code blocks above, but it's not needed. + + + + + +:::caution +Not applicable to non-react apps. Please build your own custom UI instead. +::: + + + + + + + +This guide is not applicable for Custom UI. + + + \ No newline at end of file diff --git a/v2/thirdpartyemailpassword/common-customizations/handling-signinup-success.mdx b/v2/thirdpartyemailpassword/common-customizations/handling-signinup-success.mdx index bcbdc60f8..de08042e7 100644 --- a/v2/thirdpartyemailpassword/common-customizations/handling-signinup-success.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/handling-signinup-success.mdx @@ -78,6 +78,63 @@ Please refer to [this page](../advanced-customizations/frontend-hooks/handle-eve + + +This method allows you to fire events immediately after a successful sign in / up. For example to send analytics events post sign in / up. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIThirdParty from "supertokens-auth-react-script/recipe/thirdparty"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIThirdParty.init({ + // highlight-start + onHandleEvent: async (context) => { + if (context.action === "SUCCESS") { + let { id, emails } = context.user; + if (context.isNewRecipeUser && context.user.loginMethods.length === 1) { + // TODO: Sign up + } else { + // TODO: Sign in + } + } + } + // highlight-end + }), + supertokensUIEmailPassword.init({ + // highlight-start + onHandleEvent: async (context) => { + if (context.action === "SUCCESS") { + let { id, emails } = context.user; + if (context.isNewRecipeUser && context.user.loginMethods.length === 1) { + // TODO: Sign up + } else { + // TODO: Sign in + } + } + } + // highlight-end + }), + supertokensUISession.init() + ] +}); +``` + +:::info +Please refer to [this page](../advanced-customizations/frontend-hooks/handle-event) to learn more about the `onHandleEvent` hook. +::: + + + diff --git a/v2/thirdpartyemailpassword/common-customizations/multi-tenancy/common-domain-login.mdx b/v2/thirdpartyemailpassword/common-customizations/multi-tenancy/common-domain-login.mdx index 1d043bb9c..24259ee2c 100644 --- a/v2/thirdpartyemailpassword/common-customizations/multi-tenancy/common-domain-login.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/multi-tenancy/common-domain-login.mdx @@ -173,51 +173,6 @@ export const AuthPage = () => { - - - - -```tsx -import { useState } from "react"; -import { getRoutingComponent } from "supertokens-auth-react/ui"; -^{prebuiltuiimport} -import { useSessionContext } from "supertokens-auth-react/recipe/session"; - -export const AuthPage = () => { - const [inputTenantId, setInputTenantId] = useState(""); - const tenantId = localStorage.getItem("tenantId") ?? undefined; - const session = useSessionContext(); - - if (session.loading) { - return null; - } - - if ( - tenantId !== undefined || // if we have a tenantId stored - session.doesSessionExist === true || // or an active session (it'll contain the tenantId) - new URLSearchParams(location.search).has("tenantId") // or we are on a link (e.g.: email verification) that contains the tenantId - ) { - return getRoutingComponent([^{recipePreBuiltUINameCapitalLetters}]); - } else { - return ( -
{ - // this value will be read by SuperTokens as shown in the next steps. - localStorage.setItem("tenantId", inputTenantId); - }}> -

Enter your organisation's name:

- setInputTenantId(e.target.value)} /> -
- -
- ); - } -}; -``` - - - - - We render a simple UI which asks the user for their organisation's name. Their input will be treated as their tenant ID. - Once the user has submitted that form, we will store their input in localstorage. This value will be read later on (as shown below) by SuperTokens to render the right login method based on the saved tenantId. - In case the tenantID exists in localstorage, we render the SuperTokens UI as usual. @@ -233,6 +188,20 @@ We want to render the `AuthPage` component to show on `^{form_websiteBasePath}/* The `AuthPage` will replace the call to `getSuperTokensRoutesForReactRouterDom` or `getRoutingComponent` that you may have added to your app from the quick setup section. ::: + + + + +:::caution +No code snippet provided here, however, if you visit the auth component, you will see that we are rendering the pre built UI in the `"supertokensui"` `div` element on page load. The logic here needs to change to first check if the user has provided us with the tenantId. If they have, we render the SuperTokens UI as usual. If they have not, we render a simple UI which asks the user for their tenant id and save that in localstorage. + +Switch to the React code tab here to see how this is implemented in React, and a similar logic can be followed here. +::: + + + + + @@ -400,6 +369,50 @@ We also set the `usesDynamicLoginMethods` to `true` which tells SuperTokens that + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIMultitenancy from "supertokens-auth-react-script/recipe/multitenancy"; + +supertokensUIInit({ + appInfo: { + appName: "...", + apiDomain: "...", + websiteDomain: "...", + apiBasePath: "...", + websiteBasePath: "..." + }, + // highlight-next-line + usesDynamicLoginMethods: true, + recipeList: [ + // highlight-start + supertokensUIMultitenancy.init({ + override: { + functions: (oI) => { + return { + ...oI, + getTenantId: (input) => { + let tid = localStorage.getItem("tenantId"); + return tid === null ? undefined : tid; + } + } + } + } + }) + // highlight-end + // other recipes... + ] +}); +``` + +:::important +We also set the `usesDynamicLoginMethods` to `true` which tells SuperTokens that the login methods are dynamic (based on the tenantId). This means that on page load (of the login page), SuperTokens will first fetch the configured login methods for the tenantId and display the login UI based on the result of the API call. +::: + + + @@ -664,6 +677,42 @@ SuperTokens.init({ + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; +import supertokensUIMultitenancy from "supertokens-auth-react-script/recipe/multitenancy"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + // highlight-start + getRedirectionURL: async (context) => { + if (context.action === "SUCCESS" && context.newSessionCreated) { + let claimValue: string[] | undefined = await supertokensUISession.getClaimValue({ + claim: supertokensUIMultitenancy.AllowedDomainsClaim + }); + if (claimValue !== undefined) { + window.location.href = "https://" + claimValue[0]; + } else { + // there was no configured allowed domain for this user. Throw an error cause of + // misconfig or redirect to a default sub domain + } + } + return undefined; + }, + // highlight-end + recipeList: [ /* Recipe init here... */ ] +}); +``` + + + @@ -785,6 +834,68 @@ Above, in `Session.init` on the frontend, we add the `hasAccessToCurrentDomain` + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; +import supertokensMultitenancy from "supertokens-web-js-script/recipe/multitenancy"; + +supertokensUISession.init({ + override: { + functions: (oI) => ({ + ...oI, + getGlobalClaimValidators: ({ claimValidatorsAddedByOtherRecipes }) => [ + ...claimValidatorsAddedByOtherRecipes, + { + ...supertokensMultitenancy.AllowedDomainsClaim.validators.hasAccessToCurrentDomain(), + onFailureRedirection: async () => { + let claimValue = await supertokensUISession.getClaimValue({ + claim: supertokensMultitenancy.AllowedDomainsClaim, + }); + return "https://" + claimValue![0]; + }, + }, + ], + }), + }, +}) +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: +```tsx +import Session from 'supertokens-web-js/recipe/session'; +import { AllowedDomainsClaim } from 'supertokens-web-js/recipe/multitenancy'; + +Session.init({ + override: { + functions: (oI) => ({ + ...oI, + getGlobalClaimValidators: ({ claimValidatorsAddedByOtherRecipes }) => [ + ...claimValidatorsAddedByOtherRecipes, + { + ...AllowedDomainsClaim.validators.hasAccessToCurrentDomain(), + onFailureRedirection: async () => { + let claimValue = await Session.getClaimValue({ + claim: AllowedDomainsClaim, + }); + return "https://" + claimValue![0]; + }, + }, + ], + }), + }, +}) +``` + +Above, in `Session.init` on the frontend, we add the `hasAccessToCurrentDomain` claim validator to the global validators. This means, that [whenever we check protect a route](../sessions/protecting-frontend-routes), it will check if `hasAccessToCurrentDomain` has passed, and if not, SuperTokens will redirect to the user to their right sub domain (via the values set in the `AllowedDomainsClaim` session claim). + + + diff --git a/v2/thirdpartyemailpassword/common-customizations/multi-tenancy/sub-domain-login.mdx b/v2/thirdpartyemailpassword/common-customizations/multi-tenancy/sub-domain-login.mdx index f7169ffe3..471f6f14d 100644 --- a/v2/thirdpartyemailpassword/common-customizations/multi-tenancy/sub-domain-login.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/multi-tenancy/sub-domain-login.mdx @@ -134,6 +134,48 @@ SuperTokens.init({ + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; +import supertokensUIMultitenancy from "supertokens-auth-react-script/recipe/multitenancy"; +supertokensUIInit({ + appInfo: { + appName: "^{form_appName}", + apiDomain: "^{form_apiDomain}", + websiteDomain: "^{form_websiteDomain}", + apiBasePath: "^{form_apiBasePath}", + websiteBasePath: "^{form_websiteBasePath}" + }, + // highlight-start + usesDynamicLoginMethods: true, + // highlight-end + recipeList: [ + // Other recipes... + supertokensUISession.init(), + // highlight-start + supertokensUIMultitenancy.init({ + override: { + functions: (oI) => { + return { + ...oI, + getTenantId: async () => { + // We treat the sub domain as the tenant ID + return window.location.host.split('.')[0] + } + } + } + }, + }) + // highlight-end + ] +}); +``` + + + @@ -496,6 +538,68 @@ Above, in `Session.init` on the frontend, we add the `hasAccessToCurrentDomain` + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; +import supertokensMultitenancy from "supertokens-web-js-script/recipe/multitenancy"; + +supertokensUISession.init({ + override: { + functions: (oI) => ({ + ...oI, + getGlobalClaimValidators: ({ claimValidatorsAddedByOtherRecipes }) => [ + ...claimValidatorsAddedByOtherRecipes, + { + ...supertokensMultitenancy.AllowedDomainsClaim.validators.hasAccessToCurrentDomain(), + onFailureRedirection: async () => { + let claimValue = await supertokensUISession.getClaimValue({ + claim: supertokensMultitenancy.AllowedDomainsClaim, + }); + return "https://" + claimValue![0]; + }, + }, + ], + }), + }, +}) +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: +```tsx +import Session from 'supertokens-web-js/recipe/session'; +import { AllowedDomainsClaim } from 'supertokens-web-js/recipe/multitenancy'; + +Session.init({ + override: { + functions: (oI) => ({ + ...oI, + getGlobalClaimValidators: ({ claimValidatorsAddedByOtherRecipes }) => [ + ...claimValidatorsAddedByOtherRecipes, + { + ...AllowedDomainsClaim.validators.hasAccessToCurrentDomain(), + onFailureRedirection: async () => { + let claimValue = await Session.getClaimValue({ + claim: AllowedDomainsClaim, + }); + return "https://" + claimValue![0]; + }, + }, + ], + }), + }, +}) +``` + +Above, in `Session.init` on the frontend, we add the `hasAccessToCurrentDomain` claim validator to the global validators. This means, that [whenever we check protect a route](../sessions/protecting-frontend-routes), it will check if `hasAccessToCurrentDomain` has passed, and if not, SuperTokens will redirect to the user to their right sub domain (via the values set in the `AllowedDomainsClaim` session claim). + + + diff --git a/v2/thirdpartyemailpassword/common-customizations/password-managers.mdx b/v2/thirdpartyemailpassword/common-customizations/password-managers.mdx index 8ff8073f3..eb8a91d71 100644 --- a/v2/thirdpartyemailpassword/common-customizations/password-managers.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/password-managers.mdx @@ -2,13 +2,20 @@ id: password-managers title: Password managers hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" + + + +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" -# Password managers +# Password managers + + Styling encapsulation relies on the ["shadow DOM" browser feature](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM). @@ -16,7 +23,7 @@ Unfortunately, password managers such as Dashlane, LastPass, OnePassword, etc do Therefore, if you would like to make sure that your end users can use their password managers, you will have to disable shadow DOM. - + ```tsx @@ -32,8 +39,26 @@ SuperTokens.init({ recipeList: [ /* ... */] }); ``` + + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + useShadowDom: false, + recipeList: [ /* ... */] +}); +``` + - + Demo of a password manager working with prebuilt UI when shadow DOM is disabled @@ -42,3 +67,13 @@ SuperTokens.init({ - SuperTokens uses a special attribute to define its styling so disabling shadow DOM should not impact the rest of your application's styles. On the other hand, when disabling Shadow DOM, make sure to verify that your CSS does not impact how SuperTokens UI is rendered. - Shadow DOM will always be disabled with Internet Explorer since it does not support it. Similarly, if you intend to support Internet Explorer for your application make sure to verify how SuperTokens UI is rendered. ::: + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/thirdpartyemailpassword/common-customizations/reset-password/embed-in-page.mdx b/v2/thirdpartyemailpassword/common-customizations/reset-password/embed-in-page.mdx index 40a01c19a..1496984af 100644 --- a/v2/thirdpartyemailpassword/common-customizations/reset-password/embed-in-page.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/reset-password/embed-in-page.mdx @@ -2,20 +2,25 @@ id: embed-in-page title: Embed in a page hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" import BackendSDKTabs from "/src/components/tabs/BackendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Embed in a page + + + ## Step 1: Disable the default implementation - + ```tsx @@ -40,7 +45,34 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailPassword.init({ + // highlight-start + resetPasswordUsingTokenFeature: { + disableDefaultUI: true + }, + // highlight-end + }), + ] +}); +``` + + + If you navigate to `/auth/reset-password`, you should not see the widget anymore. @@ -49,7 +81,7 @@ If you navigate to `/auth/reset-password`, you should not see the widget anymore Add the `ResetPasswordUsingToken` component in your app: - + ```tsx @@ -68,7 +100,27 @@ class ResetPasswordPage extends React.Component { } ``` - + + + +:::caution +You will have to build your own UI for this. +::: + + + + + + + +## Step 1 & 2: Disable the pre built UI. + +:::caution +Not applicable since you do not use our pre built UI. +::: + + + ## Step 3: Changing the website path for reset password UI (optional) @@ -205,7 +257,10 @@ init( ### Step B: On the frontend - + + + + ```tsx @@ -233,5 +288,47 @@ SuperTokens.init({ ] }) ``` + + + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + supertokensUIEmailPassword.init({ + //highlight-start + + // The user will be taken to the custom path when they click on forgot password. + getRedirectionURL: async (context) => { + if (context.action === "RESET_PASSWORD") { + return "/custom-reset-password-path"; + }; + } + //highlight-end + }) + ] +}) +``` + - \ No newline at end of file + + + + + +:::caution +Not applicable since you do not use our pre built UI. +::: + + + \ No newline at end of file diff --git a/v2/thirdpartyemailpassword/common-customizations/sessions/claims/access-token-payload.mdx b/v2/thirdpartyemailpassword/common-customizations/sessions/claims/access-token-payload.mdx index 828b6cb16..ac18be4b9 100644 --- a/v2/thirdpartyemailpassword/common-customizations/sessions/claims/access-token-payload.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/sessions/claims/access-token-payload.mdx @@ -1111,7 +1111,7 @@ async function someFunc() { ```tsx -import Session from 'supertokens-auth-react/recipe/session'; +import Session from 'supertokens-web-js/recipe/session'; async function someFunc() { if (await Session.doesSessionExist()) { diff --git a/v2/thirdpartyemailpassword/common-customizations/sessions/claims/claim-validators.mdx b/v2/thirdpartyemailpassword/common-customizations/sessions/claims/claim-validators.mdx index 8ffe6e207..2a7b59a42 100644 --- a/v2/thirdpartyemailpassword/common-customizations/sessions/claims/claim-validators.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/sessions/claims/claim-validators.mdx @@ -856,8 +856,8 @@ Now whenever you wrap your component with the `` wrapper, SuperToke ```tsx -import SuperTokens from "supertokens-auth-react"; -import Session, { BooleanClaim } from 'supertokens-auth-react/recipe/session'; +import SuperTokens from "supertokens-web-js"; +import Session, { BooleanClaim } from 'supertokens-web-js/recipe/session'; const SecondFactorClaim = new BooleanClaim({ id: "2fa-completed", @@ -870,7 +870,6 @@ SuperTokens.init({ appInfo: { apiDomain: "...", appName: "...", - websiteDomain: "..." }, recipeList: [ //... @@ -894,7 +893,7 @@ SuperTokens.init({ Now you can protect your frontend routes by using the `Session.validateClaims` function as shown below: ```tsx -import Session, { BooleanClaim } from "supertokens-auth-react/recipe/session"; +import Session, { BooleanClaim } from "supertokens-web-js/recipe/session"; const SecondFactorClaim = new BooleanClaim({ id: "2fa-completed", @@ -2286,8 +2285,8 @@ Unlike using the `overrideGlobalClaimValidators` prop, the `useClaimValue` funct ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { @@ -2330,8 +2329,8 @@ async function shouldLoadRoute(): Promise { If you want to have more complex access control, you can get the roles list from the session as follows, and check the list yourself: ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { diff --git a/v2/thirdpartyemailpassword/common-customizations/sessions/disable-interception.mdx b/v2/thirdpartyemailpassword/common-customizations/sessions/disable-interception.mdx index e1a878e6e..7d4a03d8a 100644 --- a/v2/thirdpartyemailpassword/common-customizations/sessions/disable-interception.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/sessions/disable-interception.mdx @@ -58,6 +58,63 @@ Session.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUISession.init({ + override: { + functions: (oI) => { + return { + ...oI, + shouldDoInterceptionBasedOnUrl: (url, apiDomain, sessionTokenBackendDomain) => { + try { + let urlObj = new URL(url); + if (!urlObj.pathname.startsWith("/auth")) { + return false; + } + } catch (ignored) { } + return oI.shouldDoInterceptionBasedOnUrl(url, apiDomain, sessionTokenBackendDomain); + } + } + } + } +}) +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import Session from "supertokens-web-js/recipe/session"; + +Session.init({ + override: { + functions: (oI) => { + return { + ...oI, + shouldDoInterceptionBasedOnUrl: (url, apiDomain, sessionTokenBackendDomain) => { + try { + let urlObj = new URL(url); + if (!urlObj.pathname.startsWith("/auth")) { + return false; + } + } catch (ignored) { } + return oI.shouldDoInterceptionBasedOnUrl(url, apiDomain, sessionTokenBackendDomain); + } + } + } + } +}) +``` + + + diff --git a/v2/thirdpartyemailpassword/common-customizations/sessions/in-iframe.mdx b/v2/thirdpartyemailpassword/common-customizations/sessions/in-iframe.mdx index e43e2fa15..0589f4b94 100644 --- a/v2/thirdpartyemailpassword/common-customizations/sessions/in-iframe.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/sessions/in-iframe.mdx @@ -69,6 +69,65 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; +declare let cookieHandler: any // typecheck-only, removed from output +declare let windowHandler: any // typecheck-only, removed from output + +supertokensUIInit({ + cookieHandler, + windowHandler, + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUISession.init({ + // highlight-start + tokenTransferMethod: "header", + isInIframe: true + // highlight-end + }) + ] +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from "supertokens-web-js"; +import Session from "supertokens-web-js/recipe/session"; +declare let cookieHandler: any // typecheck-only, removed from output +declare let windowHandler: any // typecheck-only, removed from output + +SuperTokens.init({ + cookieHandler, + windowHandler, + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + Session.init({ + // highlight-start + tokenTransferMethod: "header", + isInIframe: true + // highlight-end + }) + ], +}) +``` + + + @@ -84,8 +143,12 @@ SuperTokens.init({ ```tsx import SuperTokens from "supertokens-web-js"; import Session from "supertokens-web-js/recipe/session"; +declare let cookieHandler: any // typecheck-only, removed from output +declare let windowHandler: any // typecheck-only, removed from output SuperTokens.init({ + cookieHandler, + windowHandler, appInfo: { apiDomain: "...", appName: "...", @@ -107,7 +170,11 @@ SuperTokens.init({ ```tsx import supertokens from "supertokens-web-js-script"; import supertokensSession from "supertokens-web-js-script/recipe/session"; +declare let cookieHandler: any // typecheck-only, removed from output +declare let windowHandler: any // typecheck-only, removed from output supertokens.init({ + cookieHandler, + windowHandler, appInfo: { apiDomain: "...", appName: "...", diff --git a/v2/thirdpartyemailpassword/common-customizations/sessions/multiple-api-endpoints.mdx b/v2/thirdpartyemailpassword/common-customizations/sessions/multiple-api-endpoints.mdx index acabbe9f8..27cc1dc46 100644 --- a/v2/thirdpartyemailpassword/common-customizations/sessions/multiple-api-endpoints.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/sessions/multiple-api-endpoints.mdx @@ -241,6 +241,51 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. +```tsx +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUISession.init({ + // highlight-next-line + sessionTokenBackendDomain: ".example.com" + }) + ] +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from 'supertokens-web-js'; +import Session from 'supertokens-web-js/recipe/session'; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + Session.init({ + sessionTokenBackendDomain: ".example.com" + }), + ], +}); +``` + + + diff --git a/v2/thirdpartyemailpassword/common-customizations/sessions/protecting-frontend-routes.mdx b/v2/thirdpartyemailpassword/common-customizations/sessions/protecting-frontend-routes.mdx index 13b1829bc..232bba79f 100644 --- a/v2/thirdpartyemailpassword/common-customizations/sessions/protecting-frontend-routes.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/sessions/protecting-frontend-routes.mdx @@ -123,7 +123,7 @@ function MyDashboardComponent(props: any) { You can use the `doesSessionExist` function to check if a session exists in all your routes. ```tsx -import Session from 'supertokens-auth-react/recipe/session'; +import Session from 'supertokens-web-js/recipe/session'; async function doesSessionExist() { if (await Session.doesSessionExist()) { @@ -211,8 +211,8 @@ function ProtectedComponent() { ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { @@ -255,8 +255,8 @@ async function shouldLoadRoute(): Promise { If you want to have more complex access control, you can get the roles list from the session as follows, and check the list yourself: ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { diff --git a/v2/thirdpartyemailpassword/common-customizations/sessions/revoke-session.mdx b/v2/thirdpartyemailpassword/common-customizations/sessions/revoke-session.mdx index 9a84a64f8..012a72f96 100644 --- a/v2/thirdpartyemailpassword/common-customizations/sessions/revoke-session.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/sessions/revoke-session.mdx @@ -66,7 +66,7 @@ The [`signOut` method](https://supertokens.com/docs/web-js/modules/recipe_sessio ```tsx // highlight-next-line -import Session from "supertokens-auth-react/recipe/session"; +import Session from "supertokens-web-js/recipe/session"; async function logout () { // highlight-next-line diff --git a/v2/thirdpartyemailpassword/common-customizations/sessions/share-session-across-sub-domains.mdx b/v2/thirdpartyemailpassword/common-customizations/sessions/share-session-across-sub-domains.mdx index 9c95085ab..b0f863386 100644 --- a/v2/thirdpartyemailpassword/common-customizations/sessions/share-session-across-sub-domains.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/sessions/share-session-across-sub-domains.mdx @@ -58,6 +58,56 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + // ... + // this should be equal to the domain where the user will see the login UI + apiDomain: "...", + appName: "...", + websiteDomain: "https://example.com" + }, + recipeList: [ + supertokensUISession.init({ + // highlight-next-line + sessionTokenFrontendDomain: ".example.com" + }) + ] +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from "supertokens-web-js"; +import Session from "supertokens-web-js/recipe/session"; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + Session.init({ + // highlight-start + sessionTokenFrontendDomain: ".example.com" + // highlight-end + }), + ], +}) +``` + + + :::caution diff --git a/v2/thirdpartyemailpassword/common-customizations/sessions/ssr.mdx b/v2/thirdpartyemailpassword/common-customizations/sessions/ssr.mdx index 116901a02..863e5cb5b 100644 --- a/v2/thirdpartyemailpassword/common-customizations/sessions/ssr.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/sessions/ssr.mdx @@ -83,7 +83,7 @@ export function AttemptRefresh(props: any) { ```tsx -import Session from 'supertokens-auth-react/recipe/session'; +import Session from 'supertokens-web-js/recipe/session'; function attemptRefresh() { Session.attemptRefreshingSession().then(success => { diff --git a/v2/thirdpartyemailpassword/common-customizations/sessions/token-transfer-method.mdx b/v2/thirdpartyemailpassword/common-customizations/sessions/token-transfer-method.mdx index d07b73456..05bf214db 100644 --- a/v2/thirdpartyemailpassword/common-customizations/sessions/token-transfer-method.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/sessions/token-transfer-method.mdx @@ -71,6 +71,54 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUISession.init({ + // highlight-next-line + tokenTransferMethod: "header" // or "cookie" + }) + ] +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from "supertokens-web-js"; +import Session from "supertokens-web-js/recipe/session"; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + Session.init({ + // highlight-next-line + tokenTransferMethod: "header" // or "cookie" + }) + ], +}) +``` + + + diff --git a/v2/thirdpartyemailpassword/common-customizations/sessions/with-jwt/read-jwt.mdx b/v2/thirdpartyemailpassword/common-customizations/sessions/with-jwt/read-jwt.mdx index fe1b9a7e5..6406c10f2 100644 --- a/v2/thirdpartyemailpassword/common-customizations/sessions/with-jwt/read-jwt.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/sessions/with-jwt/read-jwt.mdx @@ -435,7 +435,7 @@ async function getJWT() { ```tsx -import Session from 'supertokens-auth-react/recipe/session'; +import Session from 'supertokens-web-js/recipe/session'; async function getJWT() { if (await Session.doesSessionExist()) { diff --git a/v2/thirdpartyemailpassword/common-customizations/signin-form/customising-each-form-field.mdx b/v2/thirdpartyemailpassword/common-customizations/signin-form/customising-each-form-field.mdx index 1fc7d728f..1153a2e2f 100644 --- a/v2/thirdpartyemailpassword/common-customizations/signin-form/customising-each-form-field.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/signin-form/customising-each-form-field.mdx @@ -70,6 +70,40 @@ SuperTokens.init({ }); ``` + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailPassword.init({ + signInAndUpFeature: { + signInForm: { + // highlight-start + formFields: [{ + id: "email", + label: "customFieldName", + placeholder: "Custom value" + }] + } + // highlight-end + } + }), + supertokensUISession.init() + ] +}); +``` + Prebuilt form UI with custom labels and placeholder @@ -118,6 +152,40 @@ SuperTokens.init({ }); ``` + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailPassword.init({ + signInAndUpFeature: { + signInForm: { + formFields: [{ + id: "email", + label: "Your Email", + // highlight-start + getDefaultValue: () => "john.doe@gmail.com" + // highlight-end + }] + } + } + }), + supertokensUISession.init() + ] +}); +``` + Prebuilt signin form UI with default values for fields @@ -177,6 +245,41 @@ SuperTokens.init({ }); ``` + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailPassword.init({ + signInAndUpFeature: { + signInForm: { + formFields: [{ + id: "email", + label: "Your Email", + placeholder: "Email", + // highlight-start + nonOptionalErrorMsg: "Please add your email" + // highlight-end + }] + } + } + }), + supertokensUISession.init() + ] +}); +``` + Prebuilt form UI with custom error message diff --git a/v2/thirdpartyemailpassword/common-customizations/signup-form/adding-fields.mdx b/v2/thirdpartyemailpassword/common-customizations/signup-form/adding-fields.mdx index f8280b1e0..48dca5cc3 100644 --- a/v2/thirdpartyemailpassword/common-customizations/signup-form/adding-fields.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/signup-form/adding-fields.mdx @@ -182,6 +182,49 @@ SuperTokens.init({ }); ``` + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailPassword.init({ + signInAndUpFeature: { + // highlight-start + signUpForm: { + formFields: [{ + id: "name", + label: "Full name", + placeholder: "First name and last name" + }, { + id: "age", + label: "Your age", + placeholder: "How old are you?", + }, { + id: "country", + label: "Your country", + placeholder: "Where do you live?", + optional: true + }] + } + // highlight-end + } + }), + supertokensUISession.init() + ] +}); +``` + Prebuilt form UI with extra custom fields diff --git a/v2/thirdpartyemailpassword/common-customizations/signup-form/built-in-providers.mdx b/v2/thirdpartyemailpassword/common-customizations/signup-form/built-in-providers.mdx index b1ac89d38..e66fffcea 100644 --- a/v2/thirdpartyemailpassword/common-customizations/signup-form/built-in-providers.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/signup-form/built-in-providers.mdx @@ -62,6 +62,43 @@ SuperTokens.init({ }); ``` + + + + +Import and all the built in providers that you wish to show in the UI as shown below. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIThirdParty from "supertokens-auth-react-script/recipe/thirdparty"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIThirdParty.init({ + signInAndUpFeature: { + // highlight-start + providers: [ + supertokensUIThirdParty.Github.init(), + supertokensUIThirdParty.Google.init(), + supertokensUIThirdParty.Facebook.init(), + supertokensUIThirdParty.Apple.init(), + ], + // highlight-end + // ... + }, + // ... + }), + // ... + ] +}); +``` + @@ -108,6 +145,15 @@ SuperTokens.init({ ] }); ``` + + + + +:::caution +This is not possible for non react apps at the moment. Please use custom UI instead for the sign in form. +::: + + diff --git a/v2/thirdpartyemailpassword/common-customizations/signup-form/custom-providers.mdx b/v2/thirdpartyemailpassword/common-customizations/signup-form/custom-providers.mdx index f9861a33a..ee1e47137 100644 --- a/v2/thirdpartyemailpassword/common-customizations/signup-form/custom-providers.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/signup-form/custom-providers.mdx @@ -69,6 +69,14 @@ SuperTokens.init({ ] }); ``` + + + + +:::caution +This is not possible for non react apps at the moment. Please use custom UI instead for the sign in form. +::: + diff --git a/v2/thirdpartyemailpassword/common-customizations/signup-form/customising-each-form-field.mdx b/v2/thirdpartyemailpassword/common-customizations/signup-form/customising-each-form-field.mdx index 569fda65c..36175967c 100644 --- a/v2/thirdpartyemailpassword/common-customizations/signup-form/customising-each-form-field.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/signup-form/customising-each-form-field.mdx @@ -70,6 +70,40 @@ SuperTokens.init({ }); ``` + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword" +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailPassword.init({ + signInAndUpFeature: { + signUpForm: { + // highlight-start + formFields: [{ + id: "email", + label: "customFieldName", + placeholder: "Custom value" + }] + } + // highlight-end + } + }), + supertokensUISession.init() + ] +}); +``` + Prebuilt form UI with custom labels and placeholder @@ -129,6 +163,46 @@ SuperTokens.init({ ``` + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword" +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailPassword.init({ + signInAndUpFeature: { + signUpForm: { + formFields: [{ + id: "email", + label: "Your Email", + // highlight-start + getDefaultValue: () => "john.doe@gmail.com" + // highlight-end + }, { + id: "name", + label: "Full name", + // highlight-start + getDefaultValue: () => "John Doe", + // highlight-end + }] + } + } + }), + supertokensUISession.init() + ] +}); +``` + + Prebuilt form UI with default values for fields @@ -195,6 +269,48 @@ SuperTokens.init({ }); ``` + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword" +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailPassword.init({ + signInAndUpFeature: { + signUpForm: { + formFields: [{ + id: "email", + label: "Your Email", + placeholder: "Email", + // highlight-start + nonOptionalErrorMsg: "Please add your email" + // highlight-end + }, { + id: "name", + label: "Full name", + placeholder: "Name", + // highlight-start + nonOptionalErrorMsg: "Full name is required", + // highlight-end + }] + } + } + }), + supertokensUISession.init() + ] +}); +``` + Prebuilt form UI with custom error message @@ -313,6 +429,14 @@ SuperTokens.init({ ] }); ``` + + + + +:::caution +This is not applicable for non React apps. You will have to create your own custom UI instead. +::: + @@ -423,6 +547,17 @@ export default App; + + + +:::caution + +This is not applicable for non React apps. You will have to create your own custom UI instead. + +::: + + + Prebuilt form UI with custom components diff --git a/v2/thirdpartyemailpassword/common-customizations/signup-form/field-validators.mdx b/v2/thirdpartyemailpassword/common-customizations/signup-form/field-validators.mdx index 036331016..c69059e95 100644 --- a/v2/thirdpartyemailpassword/common-customizations/signup-form/field-validators.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/signup-form/field-validators.mdx @@ -87,6 +87,59 @@ SuperTokens.init({ }); ``` + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword" + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailPassword.init({ + signInAndUpFeature: { + signUpForm: { + formFields: [{ + id: "name", + label: "Full name", + placeholder: "First name and last name" + }, { + id: "age", + label: "Your age", + placeholder: "How old are you?", + optional: true, + + /* Validation method to make sure that age is above 18 */ + // highlight-start + validate: async (value) => { + if (parseInt(value) > 18) { + return undefined; // means that there is no error + } + return "You must be over 18 to register"; + } + // highlight-end + + }, { + id: "country", + label: "Your country", + placeholder: "Where do you live?", + optional: true + }] + } + } + }), + // other recipes.. + ] +}); +``` + + Here is what happens if someone tries to register with an age of 17: @@ -308,6 +361,48 @@ SuperTokens.init({ }); ``` + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailPassword.init({ + signInAndUpFeature: { + signUpForm: { + formFields: [{ + // highlight-start + id: "email", + label: "...", + validate: async (value) => { + // Your own validation returning a string or undefined if no errors. + return "..."; + } + }, { + id: "password", + label: "...", + validate: async (value) => { + // Your own validation returning a string or undefined if no errors. + return "..."; + } + // highlight-end + }] + } + } + }) + ] +}); +``` + diff --git a/v2/thirdpartyemailpassword/common-customizations/signup-form/toc-privacypolicy.mdx b/v2/thirdpartyemailpassword/common-customizations/signup-form/toc-privacypolicy.mdx index 25f97f805..380a49b86 100644 --- a/v2/thirdpartyemailpassword/common-customizations/signup-form/toc-privacypolicy.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/signup-form/toc-privacypolicy.mdx @@ -2,19 +2,27 @@ id: toc-privacypolicy title: Terms of service & Privacy policy links hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" + + + +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Terms of service & Privacy policy links + + + You can provide a Privacy policy and Terms of service link which will render the following text on the sign up page: - Provided both links: "By signing up, you agree to our [Terms of Service](./toc-privacypolicy) and [Privacy Policy](./toc-privacypolicy)" - Provided only Terms of service link: "By signing up, you agree to our [Terms of Service](./toc-privacypolicy)" - Provided only Privacy policy link: "By signing up, you agree to our [Privacy Policy](./toc-privacypolicy)" - + ```tsx @@ -26,10 +34,44 @@ SuperTokens.init({ appName: "...", websiteDomain: "..." }, + // highlight-start + termsOfServiceLink: "https://example.com/terms-of-service", + privacyPolicyLink: "https://example.com/privacy-policy", + // highlight-end + recipeList: [/* ... */] +}); +``` + + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + // highlight-start termsOfServiceLink: "https://example.com/terms-of-service", privacyPolicyLink: "https://example.com/privacy-policy", - recipeList: [ /* ... */] + // highlight-end + recipeList: [/* ... */] }); ``` + - \ No newline at end of file + + + + + +:::caution +Not applicable since you do not use our pre built UI. +::: + + + diff --git a/v2/thirdpartyemailpassword/common-customizations/styling/changing-colours.mdx b/v2/thirdpartyemailpassword/common-customizations/styling/changing-colours.mdx index b810c72ad..83502b07d 100644 --- a/v2/thirdpartyemailpassword/common-customizations/styling/changing-colours.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/styling/changing-colours.mdx @@ -2,19 +2,25 @@ id: changing-colours title: Changing Colours hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" + # Changing Colours + + + It is possible to update the default theme with your colours to make it fit perfectly with your website by defining a few css variables in the `style` property to the `ThirdPartyEmailPassword.init` call. You have to specify the colors as RGB (see the following example), because we use the `rgb` and `rgba` functions to apply them. For example if your website uses a dark theme, here is how you can quickly customize it: - + ```tsx @@ -45,7 +51,39 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + // highlight-start + style: ` + [data-supertokens~=container] { + --palette-background: 51, 51, 51; + --palette-inputBackground: 41, 41, 41; + --palette-inputBorder: 41, 41, 41; + --palette-textTitle: 255, 255, 255; + --palette-textLabel: 255, 255, 255; + --palette-textPrimary: 255, 255, 255; + --palette-error: 173, 46, 46; + --palette-textInput: 169, 169, 169; + --palette-textLink: 169, 169, 169; + } + `, + // highlight-end + recipeList: [ /* ... */] +}); +``` + + Prebuilt form with custom colors @@ -146,4 +184,14 @@ Changes to the palette will apply to all the UI components we provide. If you wa - Description: This value controls the color of the "Powered by SuperTokens" text on the bottom of sign-in/up pages - Default: ```173, 189, 196``` (heather grey) -Prebuilt form SuperTokens label \ No newline at end of file +Prebuilt form SuperTokens label + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/thirdpartyemailpassword/common-customizations/styling/changing-style.mdx b/v2/thirdpartyemailpassword/common-customizations/styling/changing-style.mdx index b6fd22912..be6f7542d 100644 --- a/v2/thirdpartyemailpassword/common-customizations/styling/changing-style.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/styling/changing-style.mdx @@ -2,13 +2,18 @@ id: changing-style title: Changing Style via CSS hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Changing Style via CSS + + + Updating the CSS allows you to change the UI of our components to meet your needs. This section will guide you through an example of updating the look of buttons. Note that the process can be applied to update any HTML tag from within SuperTokens components. @@ -27,7 +32,7 @@ Each stylable components contains `data-supertokens` attributes (in our example Let's customize elements with the `button` attribute. The syntax for styling is plain CSS. - + ```tsx @@ -53,7 +58,34 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + // highlight-start + style: ` + [data-supertokens~=button] { + background-color: #252571; + border: 0px; + width: 30%; + margin: 0 auto; + } + `, + // highlight-end + recipeList: [ /* ... */] +}); +``` + + The above will result in: @@ -63,7 +95,7 @@ The above will result in: By default, SuperTokens uses the Arial font. The best way to override this is to add a `font-family` styling to the `container` component in the recipe configuration. - + ```tsx @@ -84,13 +116,35 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + style: ` + [data-supertokens~=container] { + font-family: cursive; + } + `, + recipeList: [ /* ... */] +}); +``` + + ### Using media queries You may want to have different CSS for different viewports. This can be achieved via media queries like this: - + ```tsx @@ -120,13 +174,44 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + style: ` + [data-supertokens~=button] { + background-color: #252571; + border: 0px; + width: 30%; + margin: 0 auto; + } + + @media (max-width: 440px) { + [data-supertokens~=button] { + width: 90%; + } + } + `, + recipeList: [ /* ... */], +}); +``` + + ## Customising the Sign-Up / Sign-In form These are the screens shown when the user tries to log in or sign up for the application. - + ```tsx @@ -145,13 +230,33 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + style: `[data-supertokens~=authPage] { + ... + }`, + recipeList: [ /* ... */] +}); +``` + + ## Customizing the OAuth callback screen This screen is shown when the user returns to the application from the OAuth provider - + ```tsx @@ -178,7 +283,35 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIThirdParty from "supertokens-auth-react-script/recipe/thirdparty"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + supertokensUIThirdParty.init({ + // highlight-start + oAuthCallbackScreen: { + style: ` ... ` + } + // highlight-end + }), + supertokensUISession.init() + ] +}); +``` + + ## Customising the Password Reset forms @@ -186,7 +319,7 @@ SuperTokens.init({ This form is shown when the user clicks on "forgot password" in the sign in form. - + ```tsx @@ -215,14 +348,44 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + supertokensUIEmailPassword.init({ + // highlight-start + resetPasswordUsingTokenFeature: { + enterEmailForm: { + style: ` ... ` + } + } + // highlight-end + }), + supertokensUISession.init() + ] +}); +``` + + ### Submit new password form This screen is shown when the user clicks the password reset link on their email - to enter their new password - + ```tsx @@ -251,4 +414,44 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + supertokensUIEmailPassword.init({ + // highlight-start + resetPasswordUsingTokenFeature: { + submitNewPasswordForm: { + style: ` ... ` + } + } + // highlight-end + }), + supertokensUISession.init() + ] +}); +``` + + + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/thirdpartyemailpassword/common-customizations/styling/shadow-dom.mdx b/v2/thirdpartyemailpassword/common-customizations/styling/shadow-dom.mdx index 1dae32f57..eb9077930 100644 --- a/v2/thirdpartyemailpassword/common-customizations/styling/shadow-dom.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/styling/shadow-dom.mdx @@ -2,22 +2,30 @@ id: shadow-dom title: Disable use of shadow DOM hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" + + + +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Disable use of shadow DOM + + + We use [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) to prevent CSS clashes between your CSS and the ones we provide. This guarantees that all our UI will render as expected. However, this has a few problems: - You cannot override our CSS using your CSS (though you can [use JS to do that](./changing-style)). -- Password managers may not work for your end users. +- Password managers may not work for your end user. If you want to disable use of shadow dom, you can do so like: - + ```tsx @@ -29,13 +37,43 @@ SuperTokens.init({ appName: "...", websiteDomain: "..." }, + // highlight-next-line useShadowDom: false, - recipeList: [ /* ... */] + recipeList: [/* ... */] }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + // highlight-next-line + useShadowDom: false, + recipeList: [/* ... */] +}); +``` + + :::caution If disabled, please be sure to check that our components render correctly - because your CSS might affect our components' UI (the other way around won't happen). -::: \ No newline at end of file +::: + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/thirdpartyemailpassword/common-customizations/translations.mdx b/v2/thirdpartyemailpassword/common-customizations/translations.mdx index 7604af158..59128523b 100644 --- a/v2/thirdpartyemailpassword/common-customizations/translations.mdx +++ b/v2/thirdpartyemailpassword/common-customizations/translations.mdx @@ -2,16 +2,18 @@ id: translations title: Language Translation for the UI hide_title: true +show_ui_switcher: true --- - - -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs"; +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; -import NpmOrScriptTabs from "/src/components/tabs/NpmOrScriptTabs" +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Language Translation for the UI + + + You can translate the UI using two main methods: 1. You can override all displayed translation strings by providing translated versions for different languages (and even change the default English version). 2. You can provide a translation function to integrate supertokens with your preferred internationalization library. @@ -28,7 +30,7 @@ You can provide translations for each segment displayed in our UIs. - You can find the third party login UI keys [here](https://github.com/supertokens/supertokens-auth-react/blob/master/lib/ts/recipe/thirdparty/components/themes/translations.ts). ::: - + ```tsx @@ -73,13 +75,57 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +supertokensUIInit({ + // highlight-start + languageTranslations: { // This object contains all translation related options + translations: { // These are the displayed translation strings for each language + // The property names define the language code of the translations + en: { + // Here each key is a translation key and the value is the string that will be displayed + // Setting the value to undefined will either display the translation from the default language or the translation key + BRANDING_POWERED_BY_START: "We ❤️ ", + // If you added a custom label or placeholder you can also provide translation for them if necessary + // You can also use these to provide translations for your component overrides + MY_CUSTOM_LABEL: "Age", + }, + hu: { + BRANDING_POWERED_BY_START: "Sok szeretettel: ", + // This key is associated with an empty string by default, but you can override these as well. + BRANDING_POWERED_BY_END: " 😊", + } + }, + /* + * This optional property sets the default and fallback language. + * It can be any string that will be used to fetch translations from the above object. + * Defaults to "en" + */ + defaultLanguage: "hu", + }, + // highlight-end + appInfo: { + appName: "...", + apiDomain: "...", + websiteDomain: "...", + }, + recipeList: [ + // ... + ], +}); +``` + + ### Loading translations After initialization, you can provide additional translation data by calling the `SuperTokens.loadTranslation`. This can be useful if you are loading them asynchronously. - + ```tsx @@ -94,13 +140,27 @@ SuperTokens.loadTranslation({ }); ``` - + + + +```tsx +import supertokensUI from "supertokens-auth-react-script"; +// This method takes an object as a parameter, which is structured the same as above. +// This will be merged into the existing definitions, so any properties missing here won't remove them from the already loaded translations +supertokensUI.loadTranslation({ + en: { + BRANDING_POWERED_BY_END: " :)", + } +}); +``` + + ### Changing the current language You can update which translations store is displayed by calling the `SuperTokens.changeLanguage`. - + ```tsx @@ -109,7 +169,15 @@ import SuperTokens from "supertokens-auth-react"; SuperTokens.changeLanguage("hu"); ``` - + + + +```tsx +import supertokensUI from "supertokens-auth-react-script"; +supertokensUI.changeLanguage("hu"); +``` + + ## Using an internationalization library @@ -117,7 +185,7 @@ You can easily integrate SuperTokens with your internationalization library of c 1. Provide the translation function in `SuperTokens.init` - + ```tsx @@ -144,7 +212,33 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +supertokensUIInit({ + // highlight-start + languageTranslations: { + translationFunc: (key: string) => { + // The string returned by this function will be displayed + return key + "!"; + }, + }, + // highlight-end + appInfo: { + appName: "...", + apiDomain: "...", + websiteDomain: "...", + }, + recipeList: [ + // ... + ], +}); +``` + + 2. Call `SuperTokens.changeLanguage` or `SuperTokens.loadTranslation` to re-render the translated UI @@ -158,7 +252,7 @@ If the SDK can't find a segment in the current language's translation store, we The currently chosen language is stored in a cookie, this way it can be restored the next time the page loads. The domain of this cookie can be customized through the `currentLanguageCookieScope` option. This can be useful if you are running our SDK in multiple applications and want to share the language choice between sub-domains. - + ```tsx @@ -182,13 +276,36 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +supertokensUIInit({ + // highlight-start + languageTranslations: { + currentLanguageCookieScope: ".example.com", + }, + // highlight-end + appInfo: { + appName: "...", + apiDomain: "...", + websiteDomain: "...", + }, + recipeList: [ + // ... + ], +}); +``` + + ## Translations in component overrides The SDK also exports the `useTranslation` React hook you can use while overriding components. It returns a function that takes a translation segment key and returns it translated to the currently selected language. For more information on what translation keys you should use and the exact syntax, please see the original source code of the component you are overriding. - + ```tsx @@ -208,4 +325,22 @@ export const HeaderOverride = () => { ``` - + + + +:::caution +Not applicable for non react apps. +::: + + + + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/thirdpartyemailpassword/pre-built-ui/auth-redirection.mdx b/v2/thirdpartyemailpassword/pre-built-ui/auth-redirection.mdx index 1d9265bda..e93c3f38b 100644 --- a/v2/thirdpartyemailpassword/pre-built-ui/auth-redirection.mdx +++ b/v2/thirdpartyemailpassword/pre-built-ui/auth-redirection.mdx @@ -50,6 +50,47 @@ SuperTokens.init({ }); ``` + + + + +By default, the user is redirected the the `/` route on your website post login. To change this, you can use the `getRedirectionURL` function on the frontend as shown below: + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + // highlight-start + getRedirectionURL: async (context) => { + if (context.action === "SUCCESS" && context.newSessionCreated) { + if (context.redirectToPath !== undefined) { + // we are navigating back to where the user was before they authenticated + return context.redirectToPath; + } + if (context.createdNewUser) { + // user signed up + } else { + // user signed in + } + return "/dashboard"; + } + return undefined; + }, + // highlight-end + recipeList: [ /* Recipe list */] +}); +``` + + + + + The user will be redirected to the provided URL on: - Successful sign up. - Successful sign in. @@ -62,9 +103,6 @@ If you want to redirect the user to a different domain, then you can do so by fi Please refer to [this page](../advanced-customizations/frontend-hooks/redirection-callback) to learn more about the `getRedirectionURL` hook. ::: - - - ## Redirect user to the login page @@ -100,12 +138,10 @@ function NavBar () { -Use the `redirectToAuth({show?: "signin" | "signup", redirectBack?: boolean}?)` function to redirect the user to the login screen. For example, you may want to call this function when the user clicks on the login button. +Redirect the user to the `/auth` (this is the default path for the pre built UI) ```ts import { Component } from "@angular/core"; -// highlight-next-line -import { redirectToAuth } from "supertokens-auth-react"; @Component({ selector: 'nav-bar', @@ -120,20 +156,20 @@ import { redirectToAuth } from "supertokens-auth-react"; export class NavBarComponent { async onLogin () { // highlight-next-line - redirectToAuth(); + window.location.href = "/auth?show=signin&redirecToPath=" + encodeURIComponent(window.location.pathname); } } ``` -- Call `redirectToAuth({show: "signin"})` to take them to the sign in screen -- Call `redirectToAuth({show: "signup"})` to take them to the sign up screen -- If you do not want the user to be redirected to the current page post sign in, use `redirectToAuth({redirectBack: false})` +- Set `show=signin` to take them to the sign in screen +- Set `show=signup` to take them to the sign up screen +- Set `redirecToPath` to redirect the user to a specific page after they have signed in, or you can skip it to take them to the `/` route (which is the default one). -Use the `redirectToAuth({show?: "signin" | "signup", redirectBack?: boolean}?)` function to redirect the user to the login screen. For example, you may want to call this function when the user clicks on the login button. +Redirect the user to the `/auth` (this is the default path for the pre built UI) ```html ``` -- Call `redirectToAuth({show: "signin"})` to take them to the sign in screen -- Call `redirectToAuth({show: "signup"})` to take them to the sign up screen -- If you do not want the user to be redirected to the current page post sign in, use `redirectToAuth({redirectBack: false})` +- Set `show=signin` to take them to the sign in screen +- Set `show=signup` to take them to the sign up screen +- Set `redirecToPath` to redirect the user to a specific page after they have signed in, or you can skip it to take them to the `/` route (which is the default one). @@ -195,6 +229,26 @@ SuperTokens.init({ }); ``` + + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + // highlight-next-line + defaultToSignUp: true, + recipeList: [ /* ... */] +}); +``` + diff --git a/v2/thirdpartyemailpassword/pre-built-ui/enable-email-verification.mdx b/v2/thirdpartyemailpassword/pre-built-ui/enable-email-verification.mdx index af23b6e63..61cc6442a 100644 --- a/v2/thirdpartyemailpassword/pre-built-ui/enable-email-verification.mdx +++ b/v2/thirdpartyemailpassword/pre-built-ui/enable-email-verification.mdx @@ -213,6 +213,33 @@ function App() { + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + // highlight-start + supertokensUIEmailVerification.init({ + mode: "REQUIRED", // or "OPTIONAL" + }), + // highlight-end + supertokensUISession.init(), + ], +}); +``` + + + @@ -736,8 +763,8 @@ If all validations pass, we render the `props.children` component. ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { EmailVerificationClaim } from "supertokens-auth-react/recipe/emailverification"; +import Session from "supertokens-web-js/recipe/session"; +import { EmailVerificationClaim } from "supertokens-web-js/recipe/emailverification"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { diff --git a/v2/thirdpartyemailpassword/pre-built-ui/handling-session-tokens.mdx b/v2/thirdpartyemailpassword/pre-built-ui/handling-session-tokens.mdx index 6d37e05ca..11f2460fa 100644 --- a/v2/thirdpartyemailpassword/pre-built-ui/handling-session-tokens.mdx +++ b/v2/thirdpartyemailpassword/pre-built-ui/handling-session-tokens.mdx @@ -61,7 +61,15 @@ async function getToken(): Promise { -~COPY-TABS=reactjs +```tsx +import Session from "supertokens-web-js/recipe/session"; + +async function getToken(): Promise { + // highlight-next-line + const accessToken = await Session.getAccessToken(); + console.log(accessToken); +} +``` diff --git a/v2/thirdpartyemailpassword/pre-built-ui/securing-routes.mdx b/v2/thirdpartyemailpassword/pre-built-ui/securing-routes.mdx index d8b92d8a7..c4eece720 100644 --- a/v2/thirdpartyemailpassword/pre-built-ui/securing-routes.mdx +++ b/v2/thirdpartyemailpassword/pre-built-ui/securing-routes.mdx @@ -490,7 +490,7 @@ class App extends React.Component { You can use the `doesSessionExist` function to check if a session exists in all your routes. ```tsx -import Session from 'supertokens-auth-react/recipe/session'; +import Session from 'supertokens-web-js/recipe/session'; async function doesSessionExist() { if (await Session.doesSessionExist()) { diff --git a/v2/thirdpartyemailpassword/pre-built-ui/setup/frontend.mdx b/v2/thirdpartyemailpassword/pre-built-ui/setup/frontend.mdx index 4a8630bf0..03e0bc0f9 100644 --- a/v2/thirdpartyemailpassword/pre-built-ui/setup/frontend.mdx +++ b/v2/thirdpartyemailpassword/pre-built-ui/setup/frontend.mdx @@ -13,6 +13,7 @@ import {Question, Answer}from "/src/components/question" import AppInfoForm from "/src/components/appInfoForm" import RRDVersionSubTabs from "/src/components/tabs/RRDVersionSubTabs" import NpmVersionOrYarnSubTabs from "/src/components/tabs/NpmVersionOrYarnSubTabs" +import PreBuiltUIInjector from "/src/components/prebuiltuiInjector" # Frontend Integration @@ -70,58 +71,35 @@ yarn add supertokens-auth-react supertokens-web-js -:::important -SuperTokens does not provide Angular components for pre built UI, but, there are two ways of implementing SuperTokens in your Angular frontend: -- Load SuperTokens's pre-built React UI components in your Angular app. Continue following the guide for this flow. -- Build your own UI. Click [here](../../custom-ui/init/frontend) to learn more. -::: - -Start by installing the SuperTokens ReactJS SDK and React: +Start by installing the SuperTokens Web SDK: ```bash -npm i -s supertokens-auth-react +npm i -s supertokens-web-js ``` -:::important -SuperTokens does not provide Angular components for pre built UI, but, there are two ways of implementing SuperTokens in your Angular frontend: -- Load SuperTokens's pre-built React UI components in your Angular app. Continue following the guide for this flow. -- Build your own UI. Click [here](../../custom-ui/init/frontend) to learn more. -::: -Start by installing the SuperTokens ReactJS SDK and React: +Start by installing the SuperTokens Web SDK: ```bash -npm i -s supertokens-auth-react supertokens-web-js +npm i -s supertokens-web-js ``` -:::important -SuperTokens does not provide Angular components for pre built UI, but, there are two ways of implementing SuperTokens in your Angular frontend: -- Load SuperTokens's pre-built React UI components in your Angular app. Continue following the guide for this flow. -- Build your own UI. Click [here](../../custom-ui/init/frontend) to learn more. -::: -Start by installing the SuperTokens ReactJS SDK and React: +Start by installing the SuperTokens Web SDK: ```bash -yarn add supertokens-auth-react supertokens-web-js +yarn add supertokens-web-js ``` -You will also need to update `compilerOptions` in your `tsconfig.json` file with the following: - -```json title="tsconfig.json" -"jsx": "react", -"allowSyntheticDefaultImports": true, -``` - @@ -129,46 +107,30 @@ You will also need to update `compilerOptions` in your `tsconfig.json` file with -:::important -SuperTokens does not provide Vue components for pre built UI, but, there are two ways of implementing SuperTokens in your Vue frontend: -- Load SuperTokens's pre-built React UI components in your Vue app. Continue following the guide for this flow. -- Build your own UI. Click [here](../../custom-ui/init/frontend) to learn more. -::: - -Start by installing the SuperTokens ReactJS SDK and React: +Start by installing the SuperTokens web SDK: ```bash -npm i -s supertokens-auth-react +npm i -s supertokens-web-js ``` -:::important -SuperTokens does not provide Vue components for pre built UI, but, there are two ways of implementing SuperTokens in your Vue frontend: -- Load SuperTokens's pre-built React UI components in your Vue app. Continue following the guide for this flow. -- Build your own UI. Click [here](../../custom-ui/init/frontend) to learn more. -::: -Start by installing the SuperTokens ReactJS SDK and React: +Start by installing the SuperTokens web SDK: ```bash -npm i -s supertokens-auth-react supertokens-web-js +npm i -s supertokens-web-js ``` -:::important -SuperTokens does not provide Vue components for pre built UI, but, there are two ways of implementing SuperTokens in your Vue frontend: -- Load SuperTokens's pre-built React UI components in your Vue app. Continue following the guide for this flow. -- Build your own UI. Click [here](../../custom-ui/init/frontend) to learn more. -::: -Start by installing the SuperTokens ReactJS SDK and React: +Start by installing the SuperTokens web SDK: ```bash -yarn add supertokens-auth-react supertokens-web-js +yarn add supertokens-web-js ``` @@ -260,12 +222,14 @@ class App extends React.Component { askForAPIDomain askForWebsiteDomain> -Before we initialize the `supertokens-auth-react` SDK let's see how we will use it in our Angular app + + +Before we initialize the `supertokens-web-js` SDK let's see how we will use it in our Angular app **Architecture** -- The `supertokens-auth-react` SDK is responsible for rendering the login UI, handling authentication flows and session management. -- Using `supertokens-auth-react`'s pre-built UI does not increase application's bundle size. React is only added to authentication-related routes. +- The `supertokens-web-js` SDK is responsible for session management and providing helper functions to check if a session exists, or validate the access token claims on the frontend (for example, to check for user roles before showing some UI). We will initialise this SDK on the root of your Angular app, so that all pages in your app can use it. +- We will create a `^{form_websiteBasePath}*` route in the Angular app which will render our pre built UI which will also need to be initialised, but only on that route. **Creating the `^{form_websiteBasePath}` route** @@ -275,106 +239,95 @@ Before we initialize the `supertokens-auth-react` SDK let's see how we will use ng generate module auth --route auth --module app.module ``` -- In your `auth` component folder create a react component `supertokensAuthComponent.tsx`. This component will be used to render appropriate UI when user visits the login page. - - ```tsx title="/app/auth/supertokensAuthComponent.tsx" - import * as React from "react"; - import * as SuperTokens from "supertokens-auth-react"; - import { canHandleRoute, getRoutingComponent } from "supertokens-auth-react/ui"; - ^{prebuiltuiimport} - - // highlight-start - class SuperTokensReactComponent extends React.Component { - override render() { - if (canHandleRoute([^{recipePreBuiltUINameCapitalLetters}])) { - return getRoutingComponent([^{recipePreBuiltUINameCapitalLetters}]); - } - return "Route not found"; - } - } - // highlight-end - - export default SuperTokensReactComponent; - ``` - -- Load `superTokensAuthComponent` in the `auth` angular component +- Add the following code to your `auth` angular component ```tsx title="/app/auth/auth.component.ts" - import { AfterViewInit, Component, OnDestroy } from "@angular/core"; - import * as React from "react"; - import * as ReactDOM from "react-dom"; - // @ts-ignore - import SuperTokensReactComponent from "./supertokensAuthComponent.tsx"; + import {init as supertokensUIInit} from "supertokens-auth-react-script"; + import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; + import supertokensUIThirdParty from "supertokens-auth-react-script/recipe/thirdparty"; + import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + import { Component, OnDestroy, AfterViewInit, Renderer2, Inject } from "@angular/core"; + import { DOCUMENT } from "@angular/common"; @Component({ selector: "app-auth", - template: '
', + template: '
', }) - export class AuthComponent implements AfterViewInit, OnDestroy { - title = "angularreactapp"; + export class AuthComponent implements OnDestroy, AfterViewInit { - public rootId = "rootId"; + constructor( + private renderer: Renderer2, + @Inject(DOCUMENT) private document: Document + ) { } - // highlight-start - // We use the ngAfterViewInit lifecycle hook to render the React component after the Angular component view gets initialized ngAfterViewInit() { - ReactDOM.render(React.createElement(SuperTokensReactComponent), document.getElementById(this.rootId)); + this.loadScript('^{jsdeliver_prebuiltui}'); } - // We use the ngOnDestroy lifecycle hook to unmount the React component when the Angular wrapper component is destroyed. ngOnDestroy() { - ReactDOM.unmountComponentAtNode(document.getElementById(this.rootId) as Element); + // Remove the script when the component is destroyed + const script = this.document.getElementById('supertokens-script'); + if (script) { + script.remove(); + } + } + + private loadScript(src: string) { + const script = this.renderer.createElement('script'); + script.type = 'text/javascript'; + script.src = src; + script.id = 'supertokens-script'; + script.onload = () => { + supertokensUIInit({ + appInfo: { + appName: "^{form_appName}", + apiDomain: "^{form_apiDomain}", + websiteDomain: "^{form_websiteDomain}", + apiBasePath: "^{form_apiBasePath}", + websiteBasePath: "^{form_websiteBasePath}" + }, + recipeList: [ + supertokensUIEmailPassword.init(), + supertokensUIThirdParty.init({ + signInAndUpFeature: { + providers: [ + supertokensUIThirdParty.Github.init(), + supertokensUIThirdParty.Google.init(), + supertokensUIThirdParty.Facebook.init(), + supertokensUIThirdParty.Apple.init(), + ] + } + }), + supertokensUISession.init(), + ], + }); + } + this.renderer.appendChild(this.document.body, script); } - // highlight-end } ``` + - In the `loadScript` function, we provide the SuperTokens config for the UI. We add the emailpassword, session and social login recipes along with Github, Google, Facebook and Apple login buttons. -- Initialize the `supertokens-auth-react` SDK in your angular app's root component. This will provide session management across your entire application. +- Initialize the `supertokens-web-js` SDK in your angular app's root component. This will provide session management across your entire application. - ```tsx title="/app/app.component.ts " - import { Component } from "@angular/core"; - - import * as SuperTokens from "supertokens-auth-react"; - import * as ThirdParty from "supertokens-auth-react/recipe/thirdparty"; - import { Github, Google, Facebook, Apple } from "supertokens-auth-react/recipe/thirdparty"; - import EmailPassword from "supertokens-auth-react/recipe/emailpassword"; - import Session from "supertokens-auth-react/recipe/session"; + ```tsx title="/app/app.component.ts " + import SuperTokens from "supertokens-web-js"; + import Session from "supertokens-web-js/recipe/session"; SuperTokens.init({ - // highlight-start appInfo: { appName: "^{form_appName}", apiDomain: "^{form_apiDomain}", - websiteDomain: "^{form_websiteDomain}", apiBasePath: "^{form_apiBasePath}", - websiteBasePath: "^{form_websiteBasePath}" }, recipeList: [ - ThirdParty.init({ - signInAndUpFeature: { - providers: [ - Github.init(), - Google.init(), - Facebook.init(), - Apple.init(), - ], - }, - }), - EmailPassword.init(), Session.init(), ], - // highlight-end }); - - @Component({ - selector: "app-root", - template: "", - }) - export class AppComponent { - title = "^{form_appName}"; - } ``` + + @@ -386,100 +339,101 @@ Before we initialize the `supertokens-auth-react` SDK let's see how we will use askForAPIDomain askForWebsiteDomain> -Before we initialize the `supertokens-auth-react` SDK let's see how we will use it in our Vue app + + +Before we initialize the `supertokens-web-js` SDK let's see how we will use it in our Vue app **Architecture** -- The `supertokens-auth-react` SDK is responsible for rendering the login UI, handling authentication flows and session management. -- Using `supertokens-auth-react`'s pre-built UI does not increase application's bundle size. React is only added to authentication-related routes. +- The `supertokens-web-js` SDK is responsible for session management and providing helper functions to check if a session exists, or validate the access token claims on the frontend (for example, to check for user roles before showing some UI). We will initialise this SDK on the root of your Vue app, so that all pages in your app can use it. +- We will create a `^{form_websiteBasePath}*` route in the Vue app which will render our pre built UI which will also need to be initialised, but only on that route. **Creating the `^{form_websiteBasePath}` route** -- Create a new file `AuthView.vue`, this Vue component will be used to render the auth component - -- Create a react component `Supertokens.tsx`. This component will be used to render appropriate UI when user visits the login page. - - ```tsx title="/components/Supertokens.tsx" - import * as SuperTokens from "supertokens-auth-react"; - import { canHandleRoute, getRoutingComponent } from "supertokens-auth-react/ui"; - ^{prebuiltuiimport} - - // highlight-start - function SuperTokensReactComponent(props: any) { - if (canHandleRoute([^{recipePreBuiltUINameCapitalLetters}])) { - return getRoutingComponent([^{recipePreBuiltUINameCapitalLetters}]); - } - return "Route not found"; - } - // highlight-end - - export default SuperTokensReactComponent; - ``` - -- Load `SuperTokensReactComponent` in the `AuthView.vue` component - - ```html title="/views/AuthView.vue" +- Create a new file `AuthView.vue`, this Vue component will be used to render the auth component: + ```tsx + import {init as supertokensUIInit} from "supertokens-auth-react-script"; + import supertokensUIThirdParty from "supertokens-auth-react-script/recipe/thirdparty"; + import supertokensUIEmailPassword from "supertokens-auth-react-script/recipe/emailpassword"; + import supertokensUISession from "supertokens-auth-react-script/recipe/session"; ``` + - In the `loadScript` function, we provide the SuperTokens config for the UI. We add the emailpassword, session and social login recipes along with Github, Google, Facebook and Apple login buttons. -- Initialize the `supertokens-auth-react` SDK in your Vue app's `main.ts` file. This will provide session management across your entire application. +- Initialize the `supertokens-web-js` SDK in your Vue app's `main.ts` file. This will provide session management across your entire application. ```tsx title="/main.ts " // @ts-ignore import { createApp } from "vue"; - import * as SuperTokens from "supertokens-auth-react"; - import * as ThirdParty from "supertokens-auth-react/recipe/thirdparty"; - import { Github, Google, Facebook, Apple } from "supertokens-auth-react/recipe/thirdparty"; - import EmailPassword from "supertokens-auth-react/recipe/emailpassword"; - import Session from "supertokens-auth-react/recipe/session"; - + import SuperTokens from "supertokens-web-js"; + import Session from "supertokens-web-js/recipe/session"; // @ts-ignore import App from "./App.vue"; // @ts-ignore import router from "./router"; SuperTokens.init({ - // highlight-start appInfo: { appName: "^{form_appName}", apiDomain: "^{form_apiDomain}", - websiteDomain: "^{form_websiteDomain}", apiBasePath: "^{form_apiBasePath}", - websiteBasePath: "^{form_websiteBasePath}" }, recipeList: [ - ThirdParty.init({ - signInAndUpFeature: { - providers: [ - Github.init(), - Google.init(), - Facebook.init(), - Apple.init(), - ], - }, - }), - EmailPassword.init(), Session.init(), ], - // highlight-end }); const app = createApp(App); @@ -487,8 +441,11 @@ Before we initialize the `supertokens-auth-react` SDK let's see how we will use app.use(router); app.mount("#app"); + ``` + + @@ -679,6 +636,8 @@ Update your Vue router so that all auth related requests load the `AuthView` com import { createRouter, createWebHistory } from "vue-router"; // @ts-ignore import HomeView from "../views/HomeView.vue"; +// @ts-ignore +import AuthView from "../views/AuthView.vue"; const router = createRouter({ // @ts-ignore @@ -692,8 +651,7 @@ const router = createRouter({ { path: "^{form_websiteBasePath}/:pathMatch(.*)*", name: "auth", - // @ts-ignore - component: () => import("../views/AuthView.vue"), + component: AuthView, }, ], }); diff --git a/v2/thirdpartyemailpassword/pre-built-ui/sign-out.mdx b/v2/thirdpartyemailpassword/pre-built-ui/sign-out.mdx index 750ed84b2..3bbbefe35 100644 --- a/v2/thirdpartyemailpassword/pre-built-ui/sign-out.mdx +++ b/v2/thirdpartyemailpassword/pre-built-ui/sign-out.mdx @@ -42,11 +42,11 @@ function NavBar() { -The [`signOut` method](https://supertokens.com/docs/auth-react/modules/recipe_session.html#signOut-1) revokes the session for the user. +The [`signOut` method](https://supertokens.com/docs/web-js/modules/recipe_session.html#signOut-1) revokes the session for the user. ```tsx // highlight-next-line -import Session from "supertokens-auth-react/recipe/session"; +import Session from "supertokens-web-js/recipe/session"; async function logout () { // highlight-next-line diff --git a/v2/thirdpartyemailpassword/troubleshooting/how-to-troubleshoot.mdx b/v2/thirdpartyemailpassword/troubleshooting/how-to-troubleshoot.mdx index 41507a865..901aaa4d7 100644 --- a/v2/thirdpartyemailpassword/troubleshooting/how-to-troubleshoot.mdx +++ b/v2/thirdpartyemailpassword/troubleshooting/how-to-troubleshoot.mdx @@ -132,6 +132,45 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + // highlight-next-line + enableDebugLogs: true, + // @ts-ignore + appInfo: { /*...*/ }, + // @ts-ignore + recipeList: [/*...*/] +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from 'supertokens-web-js'; +import Session from 'supertokens-web-js/recipe/session'; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + Session.init(), + ], + // highlight-next-line + enableDebugLogs: true, +}); +``` + + + diff --git a/v2/thirdpartyemailpassword/user-roles/protecting-routes.mdx b/v2/thirdpartyemailpassword/user-roles/protecting-routes.mdx index b3ea9478d..58c95e15f 100644 --- a/v2/thirdpartyemailpassword/user-roles/protecting-routes.mdx +++ b/v2/thirdpartyemailpassword/user-roles/protecting-routes.mdx @@ -1224,8 +1224,8 @@ function ProtectedComponent() { ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { @@ -1268,8 +1268,8 @@ async function shouldLoadRoute(): Promise { If you want to have more complex access control, you can get the roles list from the session as follows, and check the list yourself: ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { diff --git a/v2/thirdpartypasswordless/advanced-customizations/frontend-functions-override/usage.mdx b/v2/thirdpartypasswordless/advanced-customizations/frontend-functions-override/usage.mdx index 4272234f6..ed7ef4567 100644 --- a/v2/thirdpartypasswordless/advanced-customizations/frontend-functions-override/usage.mdx +++ b/v2/thirdpartypasswordless/advanced-customizations/frontend-functions-override/usage.mdx @@ -2,21 +2,27 @@ id: usage title: How to use hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # How to use ## Use the override config + + + + + + :::info See all the [functions that can be overrided here](https://supertokens.com/docs/auth-react/modules/recipe_thirdpartypasswordless.html#RecipeInterface) ::: - - ```tsx import SuperTokens from "supertokens-auth-react"; @@ -75,7 +81,83 @@ SuperTokens.init({ }); ``` - + + + +:::info +See all the [functions that can be overrided here](https://supertokens.com/docs/auth-react/modules/recipe_thirdpartypasswordless.html#RecipeInterface) +::: + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless"; +import supertokensUIThirdParty from "supertokens-auth-react-script/recipe/thirdparty"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIThirdParty.init({ + //highlight-start + override: { + functions: (originalImplementation) => { + return { + ...originalImplementation, + signInAndUp: async function (input) { + // TODO: some custom logic + + // or call the default behaviour as show below + return originalImplementation.signInAndUp(input); + }, + // ... + // TODO: override more functions + } + } + } + //highlight-end + }), + supertokensUIPasswordless.init({ + contactMethod: "EMAIL", // This example will work with any contactMethod + //highlight-start + override: { + functions: (originalImplementation) => { + return { + ...originalImplementation, + // we will only be overriding what happens when a user + // enters the OTP or clicks on the magic link + consumeCode: async function (input) { + // TODO: some custom logic + + // or call the default behaviour as show below + return originalImplementation.consumeCode(input); + }, + // ... + // TODO: override more functions + } + } + } + //highlight-end + }) + ] +}); +``` + + - `originalImplementation` is an object that contain functions that have the original implementation for this recipe. They can be used in your functions as a way to use the SuperTokens' default behaviour. -- In the above code snippet, we override the `consumeCode` and the `signinup` function of the two recipes. This means that when the user clicks enters the OTP or clicks on the magic link or uses social login, your function will be called with the relevant `input` object. \ No newline at end of file +- In the above code snippet, we override the `consumeCode` and the `signinup` function of the two recipes. This means that when the user clicks enters the OTP or clicks on the magic link or uses social login, your function will be called with the relevant `input` object. + + + + +:::caution +Not applicable since you need to build custom UI anyway, so when you call the functions from our SDK, or call the API directly, you can run pre / post logic in your own code. +::: + + + diff --git a/v2/thirdpartypasswordless/advanced-customizations/frontend-hooks/handle-event.mdx b/v2/thirdpartypasswordless/advanced-customizations/frontend-hooks/handle-event.mdx index 23439e6ad..6a483d508 100644 --- a/v2/thirdpartypasswordless/advanced-customizations/frontend-hooks/handle-event.mdx +++ b/v2/thirdpartypasswordless/advanced-customizations/frontend-hooks/handle-event.mdx @@ -2,16 +2,21 @@ id: handle-event title: Handle Event Hook hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Handle Event Hook + + + This function is called for various user actions. It can be used for logging, analytics or any side effect purposes (these are essentially fire and forget events). - + ```tsx @@ -58,9 +63,68 @@ ThirdParty.init({ }) ``` + + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless"; +import supertokensUIThirdParty from "supertokens-auth-react-script/recipe/thirdparty"; + +supertokensUIPasswordless.init({ + contactMethod: "EMAIL", // This example will work with any contactMethod + onHandleEvent: (context) => { + if (context.action === "PASSWORDLESS_RESTART_FLOW") { + // TODO: + } else if (context.action === "PASSWORDLESS_CODE_SENT") { + // TODO: + } else if (context.action === "SUCCESS") { + if (context.createdNewSession) { + let user = context.user; + if (context.isNewRecipeUser && context.user.loginMethods.length === 1) { + // sign up success + } else { + // sign in success + } + } else { + // during second factor authentication + } + } + }, +}) + +supertokensUIThirdParty.init({ + onHandleEvent: (context) => { + if (context.action === "SUCCESS") { + if (context.createdNewSession) { + let user = context.user; + if (context.isNewRecipeUser && context.user.loginMethods.length === 1) { + // sign up success + } else { + // sign in success + } + } else { + // during linking a social account to an existing account + } + } + }, +}) +``` + + + + :::info Also checkout the [session recipe hand event hook](/docs/session/advanced-customizations/frontend-hooks/handle-event). ::: - - \ No newline at end of file + + + +:::caution +Not applicable since you need to build custom UI anyway, so when you call the functions from our SDK, or call the API directly, you can run pre / post logic in your own code. +::: + + + \ No newline at end of file diff --git a/v2/thirdpartypasswordless/advanced-customizations/frontend-hooks/pre-api.mdx b/v2/thirdpartypasswordless/advanced-customizations/frontend-hooks/pre-api.mdx index e64bc3947..f7ab25a93 100644 --- a/v2/thirdpartypasswordless/advanced-customizations/frontend-hooks/pre-api.mdx +++ b/v2/thirdpartypasswordless/advanced-customizations/frontend-hooks/pre-api.mdx @@ -84,6 +84,71 @@ ThirdParty.init({ ``` + + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless"; +import supertokensUIThirdParty from "supertokens-auth-react-script/recipe/thirdparty"; + +supertokensUIPasswordless.init({ + contactMethod: "EMAIL", // This example will work with any contactMethod. + preAPIHook: async (context) => { + let url = context.url; + + // is the fetch config object that contains the header, body etc.. + let requestInit = context.requestInit; + + let action = context.action; + if (action === "EMAIL_EXISTS") { + + } else if (action === "PASSWORDLESS_CONSUME_CODE") { + + } else if (action === "PASSWORDLESS_CREATE_CODE") { + + } else if (action === "PASSWORDLESS_RESEND_CODE") { + + } else if (action === "PHONE_NUMBER_EXISTS") { + + } + + // events such as sign out are in the + // session recipe pre API hook (See the info box below) + return { + requestInit, url + }; + } +}) + +supertokensUIThirdParty.init({ + preAPIHook: async (context) => { + let url = context.url; + let requestInit = context.requestInit; + + let action = context.action; + if (action === "GET_AUTHORISATION_URL") { + + } else if (action === "THIRD_PARTY_SIGN_IN_UP") { + // Note: this could either be sign in or sign up. + // we don't know that at the time of the API call + // since all we have is the authorisation code from + // the social provider + } + + // events such as sign out are in the + // session recipe pre API hook (See the info box below) + + return { + requestInit, url + }; + + } +}) +``` + + :::info diff --git a/v2/thirdpartypasswordless/advanced-customizations/frontend-hooks/redirection-callback.mdx b/v2/thirdpartypasswordless/advanced-customizations/frontend-hooks/redirection-callback.mdx index ef3bd16bb..73f9a563c 100644 --- a/v2/thirdpartypasswordless/advanced-customizations/frontend-hooks/redirection-callback.mdx +++ b/v2/thirdpartypasswordless/advanced-customizations/frontend-hooks/redirection-callback.mdx @@ -2,16 +2,21 @@ id: redirection-callback title: Redirection Callback Hook hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Redirection Callback Hook + + + This function is used to change where the user is redirected to post certain actions. For example, you can use this to redirect a user to a specific URL post sign in / up. If you're embedding the sign in / up components in a popup and wish to disable redirection entirely, simply return `null`. - + ```tsx @@ -46,4 +51,51 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + appName: "SuperTokens", + apiDomain: "http://localhost:3000", + websiteDomain: "http://localhost:3000" + }, + getRedirectionURL: async (context) => { + if (context.action === "SUCCESS" && context.newSessionCreated) { + // called on a successful sign in / up. Where should the user go next? + let redirectToPath = context.redirectToPath; + if (redirectToPath !== undefined) { + // we are navigating back to where the user was before they authenticated + return redirectToPath; + } + if (context.createdNewUser) { + // user signed up + return "/onboarding" + } else { + // user signed in + return "/dashboard" + } + } + // return undefined to let the default behaviour play out + return undefined; + }, + recipeList: [ /* ... */] +}); +``` + + + + + + +:::caution +Not applicable since you need to build custom UI anyway, so you can redirect the user after calling our SDK functions / API. +::: + + + + diff --git a/v2/thirdpartypasswordless/advanced-customizations/react-component-override/usage.mdx b/v2/thirdpartypasswordless/advanced-customizations/react-component-override/usage.mdx index a8ea188dd..4580fa137 100644 --- a/v2/thirdpartypasswordless/advanced-customizations/react-component-override/usage.mdx +++ b/v2/thirdpartypasswordless/advanced-customizations/react-component-override/usage.mdx @@ -2,22 +2,27 @@ id: usage title: How to use hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" import {Answer} from "/src/components/question" import {Question}from "/src/components/question" # How to use + + + + + + 1. You will have to use the `ThirdpartyComponentsOverrideProvider`, `PasswordlessComponentsOverrideProvider` or the `AuthRecipeComponentsOverrideContextProvider` component as shown below. make sure that it render the SuperTokens components inside this component. 2. [Pick a component](#finding-which-component-will-be-overridden) that you'd like to override by its key. 3. Supply a React component against the key you have picked. Your custom component will get the original component as a `prop`. -## Example - - @@ -142,8 +147,6 @@ export default App; Please make sure that the file in which this config is specified is a `.tsx` or ` .jsx` file type. ::: - - ## Finding which component will be overridden To do that, you should use React Developer Tools extension which provides a component tree inspector. @@ -185,4 +188,24 @@ function App() { ); } export default App; -``` \ No newline at end of file +``` + + + + +:::caution +Not applicable to non-react apps. You can disable the specific pre built UI component, and then build your own UI instead. +::: + + + + + + + +:::caution +Not applicable to custom UI +::: + + + \ No newline at end of file diff --git a/v2/thirdpartypasswordless/common-customizations/change-magic-link-url.mdx b/v2/thirdpartypasswordless/common-customizations/change-magic-link-url.mdx index bc2738af8..8f219e260 100644 --- a/v2/thirdpartypasswordless/common-customizations/change-magic-link-url.mdx +++ b/v2/thirdpartypasswordless/common-customizations/change-magic-link-url.mdx @@ -2,14 +2,16 @@ id: change-magic-link-url title: Changing the Magic Link URL hide_title: true +show_ui_switcher: true --- import BackendSDKTabs from "/src/components/tabs/BackendSDKTabs"; -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Changing the Magic Link URL @@ -147,7 +149,10 @@ init( ## Frontend change - + + + + When the user clicks the magic link, you need to render the `LinkClicked` component that exported by our SDK on that page. By default, this already happens on the `${websiteDomain}/${websiteBasePath}/verify` path. To change this, you need to: @@ -174,4 +179,34 @@ function CustomLinkClickedScreen () { ``` - \ No newline at end of file + + + +When the user clicks the magic link, you need to build your own UI on that page to handle the link clicked. You also need to disable the pre built UI that was provided by our SDK for the link clicked screen as shown below: + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless"; + +supertokensUIPasswordless.init({ + contactMethod: "EMAIL", // This example will work with any contactMethod + linkClickedScreenFeature: { + disableDefaultUI: true + }, +}); +``` + + + + + + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/thirdpartypasswordless/common-customizations/changing-base-path/api-base-path.mdx b/v2/thirdpartypasswordless/common-customizations/changing-base-path/api-base-path.mdx index f7a1a28f7..04d981956 100644 --- a/v2/thirdpartypasswordless/common-customizations/changing-base-path/api-base-path.mdx +++ b/v2/thirdpartypasswordless/common-customizations/changing-base-path/api-base-path.mdx @@ -112,6 +112,45 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +supertokensUIInit({ + appInfo: { + appName: "yourAppName", + apiDomain: "yourApi", + websiteDomain: "yourWebsite", + // highlight-next-line + apiBasePath: "/api/v3/auth" + }, + recipeList: [], +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +// this goes in the root of your frontend app +import SuperTokens from "supertokens-web-js"; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + // highlight-next-line + apiBasePath: "/api/v3/auth", + appName: "...", + }, + recipeList: [/* ... */], +}); +``` + + + diff --git a/v2/thirdpartypasswordless/common-customizations/changing-base-path/website-base-path.mdx b/v2/thirdpartypasswordless/common-customizations/changing-base-path/website-base-path.mdx index 0795a935f..3e3e959bd 100644 --- a/v2/thirdpartypasswordless/common-customizations/changing-base-path/website-base-path.mdx +++ b/v2/thirdpartypasswordless/common-customizations/changing-base-path/website-base-path.mdx @@ -2,6 +2,7 @@ id: website-base-path title: Website Base Path hide_title: true +show_ui_switcher: true --- @@ -9,6 +10,7 @@ hide_title: true import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" import BackendSDKTabs from "/src/components/tabs/BackendSDKTabs" import BackendSDKCasing from "/src/components/BackendSDKCasing" import TabItem from '@theme/TabItem'; @@ -16,6 +18,10 @@ import TabItem from '@theme/TabItem'; # Website Base Path ## Step 1) Front End Change + + + + Since the beginning of this guide, you probably noticed that all the front-end routes for SuperTokens widget are prefixed by `/auth`. You can change this value in the `init` function by setting websiteBasePath. @@ -39,8 +45,36 @@ SuperTokens.init({ + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +supertokensUIInit({ + appInfo: { + appName: "yourAppName", + apiDomain: "yourApi", + websiteDomain: "yourWebsite", + // highlight-next-line + websiteBasePath: "/authentication" + }, + recipeList: [], +}); +``` + + + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + ## Step 2) Back End Change diff --git a/v2/thirdpartypasswordless/common-customizations/email-verification/about.mdx b/v2/thirdpartypasswordless/common-customizations/email-verification/about.mdx index 12e146de8..38e945c5f 100644 --- a/v2/thirdpartypasswordless/common-customizations/email-verification/about.mdx +++ b/v2/thirdpartypasswordless/common-customizations/email-verification/about.mdx @@ -212,6 +212,54 @@ function App() { + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + // highlight-start + supertokensUIEmailVerification.init({ + mode: "REQUIRED", // or "OPTIONAL" + }), + // highlight-end + ], +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from "supertokens-web-js"; +import EmailVerification from "supertokens-web-js/recipe/emailverification"; +import Session from "supertokens-web-js/recipe/session"; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + // highlight-next-line + EmailVerification.init(), + Session.init(), + ], +}); +``` + + + :::important diff --git a/v2/thirdpartypasswordless/common-customizations/email-verification/changing-style.mdx b/v2/thirdpartypasswordless/common-customizations/email-verification/changing-style.mdx index 596a7ca00..de0cbe03c 100644 --- a/v2/thirdpartypasswordless/common-customizations/email-verification/changing-style.mdx +++ b/v2/thirdpartypasswordless/common-customizations/email-verification/changing-style.mdx @@ -2,19 +2,20 @@ id: changing-style title: Changing Style via CSS hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Changing Style via CSS -:::important -This is applicable to prebuilt UI only. -::: + + Updating the CSS allows you to change the UI of our components to meet your needs. @@ -30,7 +31,7 @@ Each stylable components contains `data-supertokens` attributes (in our example Let's add a `border` to our `link` elements. The syntax for styling is plain CSS. - + ```tsx @@ -62,7 +63,38 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailVerification.init({ + // highlight-start + style: ` + [data-supertokens~=link] { + border: 2px solid #0076ff; + border-radius: 5; + width: 30%; + margin: 0 auto; + } + `, + // highlight-end + }) + ] +}); +``` + + + The above will result in: @@ -72,7 +104,7 @@ The above will result in: By default, SuperTokens uses the Arial font. The best way to override this is to add a `font-family` styling to the `container` component in the recipe configuration. - + ```tsx @@ -101,13 +133,39 @@ SuperTokens.init({ }); ``` - + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailVerification.init({ + // highlight-start + style: ` + [data-supertokens~=container] { + font-family: cursive + } + ` + // highlight-end + }), + ] +}); +``` + + ### Using media queries You may want to have different CSS for different viewports. This can be achieved via media queries like this: - + ```tsx @@ -145,7 +203,44 @@ SuperTokens.init({ }); ``` - + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + // ... + supertokensUIEmailVerification.init({ + // ... + style: ` + [data-supertokens~=link] { + border: 2px solid #0076ff; + borderRadius: 5; + width: 30%; + margin: 0 auto; + } + + // highlight-start + @media (max-width: 440px) { + [data-supertokens~=link] { + width: 90%; + } + } + // highlight-end + `, + }), + ], +}); +``` + + ## Customising individual screens @@ -153,7 +248,7 @@ SuperTokens.init({ This screen is where the user is redirected if `mode` is set to `REQUIRED` and they visit a path that requires a verified email. - + ```tsx @@ -180,13 +275,38 @@ SuperTokens.init({ }); ``` - + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + supertokensUIEmailVerification.init({ + // highlight-start + sendVerifyEmailScreen: { + style: ` ... ` + } + // highlight-end + }) + ] +}); +``` + + ### Verify link clicked screen This is the screen shown to users that click the email verification link in the email. - + ```tsx @@ -213,4 +333,41 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + supertokensUIEmailVerification.init({ + // highlight-start + verifyEmailLinkClickedScreen: { + style: ` ... `, + } + // highlight-end + }) + ] +}); +``` + + + + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/thirdpartypasswordless/common-customizations/email-verification/embed-in-page.mdx b/v2/thirdpartypasswordless/common-customizations/email-verification/embed-in-page.mdx index 8f8a84e8d..d1f1445d2 100644 --- a/v2/thirdpartypasswordless/common-customizations/email-verification/embed-in-page.mdx +++ b/v2/thirdpartypasswordless/common-customizations/email-verification/embed-in-page.mdx @@ -2,20 +2,25 @@ id: embed-in-page title: Embed in a page hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" import BackendSDKTabs from "/src/components/tabs/BackendSDKTabs" # Embed in a page + + + ## Step 1: Disable the default implementation - + ```tsx @@ -42,11 +47,39 @@ SuperTokens.init({ If you navigate to `/auth/verify-email`, you should not see the widget anymore. - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIEmailVerification.init({ + mode: "REQUIRED", + // highlight-start + disableDefaultUI: true + // highlight-end + }), + ] +}); +``` + +If you navigate to `/auth/verify-email`, you should not see the widget anymore. + + + ## Step 2: Render the component yourself - + Add the `EmailVerification` component in your app: @@ -68,7 +101,27 @@ class EmailVerificationPage extends React.Component { } ``` - + + + +:::caution +You will have to build your own UI instead. +::: + + + + + + + +## Step 1 & 2: Disable the pre built UI + +:::caution +Not applicable since you do not use our pre built UI +::: + + + ## Step 3: Changing the website path for the email verification UI (optional) @@ -208,7 +261,10 @@ init( ### Step B: On the frontend - + + + + ```tsx @@ -238,4 +294,45 @@ SuperTokens.init({ }) ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + supertokensUIEmailVerification.init({ + mode: "REQUIRED", + //highlight-start + + // The user will be taken to the custom path when they need to get their email verified. + getRedirectionURL: async (context) => { + if (context.action === "VERIFY_EMAIL") { + return "/custom-email-verification-path"; + }; + } + //highlight-end + }) + ] +}) +``` + + + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/thirdpartypasswordless/common-customizations/email-verification/protecting-routes.mdx b/v2/thirdpartypasswordless/common-customizations/email-verification/protecting-routes.mdx index d7d7a5ca0..e0bf31003 100644 --- a/v2/thirdpartypasswordless/common-customizations/email-verification/protecting-routes.mdx +++ b/v2/thirdpartypasswordless/common-customizations/email-verification/protecting-routes.mdx @@ -1114,8 +1114,8 @@ function ProtectedComponent() { ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { EmailVerificationClaim } from "supertokens-auth-react/recipe/emailverification"; +import Session from "supertokens-web-js/recipe/session"; +import { EmailVerificationClaim } from "supertokens-web-js/recipe/emailverification"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { diff --git a/v2/thirdpartypasswordless/common-customizations/embed-sign-in-up-form.mdx b/v2/thirdpartypasswordless/common-customizations/embed-sign-in-up-form.mdx index 0a1635db5..c48e5907d 100644 --- a/v2/thirdpartypasswordless/common-customizations/embed-sign-in-up-form.mdx +++ b/v2/thirdpartypasswordless/common-customizations/embed-sign-in-up-form.mdx @@ -16,12 +16,13 @@ import RRDVersionSubTabs from "/src/components/tabs/RRDVersionSubTabs" + + + ## Case 1: Rendering the Auth Widget in a page The following example shows the scenario where you have a dedicated route, such as `/auth`, for rendering the Auth Widget. Upon a successful login, the user will be automatically redirected to the return value of `getRedirectionURL` (defaulting to `/`). - - @@ -181,8 +182,6 @@ function MyAuthPage() { ``` - - In the above code snippet, we: @@ -199,8 +198,6 @@ When the user visits the `/auth` page, they will see the SignIn UI by default. T The following example shows the scenario where you have a dedicated route, such as `/auth`, for rendering the Auth Widget. However, upon a successful login, the user will see a logged in UI instead of getting redirected. - - @@ -417,8 +414,6 @@ function LandingPage() { ``` - - In the above code snippet, we wrap the logged-in component with `Session.SessionAuth` to validate all claims before displaying the logged-in UI. For instance, with email verification enabled, if a user's email is unverified, `Session.SessionAuth` redirects to the email verification page. @@ -430,8 +425,6 @@ In the above case, redirection may occur if a claim fails. For instance, in the The following example shows the scenario where you embed the Auth Widget in a popup, and upon successful login, you aim to close the popup. - - @@ -687,21 +680,11 @@ function AuthPopup() { ``` - - :::note In the above case, redirection may occur if a claim fails. For instance, in the case of an Email Verification claim, if the user's email is not verified, they will be redirected to the email verification page. To prevent redirection for failed claims, please contact us on [Discord](https://supertokens.com/discord) for assistance. ::: - - - -This guide is not applicable for Custom UI. - - - - ## Rendering only passwordless / third party login instead of both There may be a case where you want to render just one of the login methods on a particular page. @@ -746,4 +729,23 @@ function MyAuthPage() { } ``` -The idea behind this is that we provide the `factors` prop to the `AuthPage`, which tells it that we only want to render the third party password UI. The `preBuiltUIList` prop is still required, and we pass in the `ThirdPartyPreBuiltUI` component to it. We could also pass in the `PasswordlessPreBuiltUI` component to it as shown in the code blocks above, but it's not needed. \ No newline at end of file +The idea behind this is that we provide the `factors` prop to the `AuthPage`, which tells it that we only want to render the third party password UI. The `preBuiltUIList` prop is still required, and we pass in the `ThirdPartyPreBuiltUI` component to it. We could also pass in the `PasswordlessPreBuiltUI` component to it as shown in the code blocks above, but it's not needed. + + + + + +:::caution +Not applicable to non-react apps. Please build your own custom UI instead. +::: + + + + + + + +This guide is not applicable for Custom UI. + + + \ No newline at end of file diff --git a/v2/thirdpartypasswordless/common-customizations/handling-signinup-success.mdx b/v2/thirdpartypasswordless/common-customizations/handling-signinup-success.mdx index bbbbe95de..9781093c0 100644 --- a/v2/thirdpartypasswordless/common-customizations/handling-signinup-success.mdx +++ b/v2/thirdpartypasswordless/common-customizations/handling-signinup-success.mdx @@ -85,6 +85,72 @@ Please refer to [this page](../advanced-customizations/frontend-hooks/handle-eve + + +This method allows you to fire events immediately after a successful sign in. For example to send analytics events post sign in. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless"; +import supertokensUIThirdParty from "supertokens-auth-react-script/recipe/thirdparty"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIPasswordless.init({ + contactMethod: "EMAIL_OR_PHONE", + + // highlight-start + onHandleEvent: async (context) => { + if (context.action === "PASSWORDLESS_RESTART_FLOW") { + // TODO: + } else if (context.action === "PASSWORDLESS_CODE_SENT") { + // TODO: + } else if (context.action === "SUCCESS") { + if (context.isNewRecipeUser && context.user.loginMethods.length === 1) { + if ("phoneNumber" in context.user) { + const { phoneNumber } = context.user; + } else { + const { emails } = context.user; + } + // TODO: Sign up + } else { + // TODO: Sign in + } + } + } + // highlight-end + }), + supertokensUIThirdParty.init({ + // highlight-start + onHandleEvent: async (context) => { + if (context.action === "SUCCESS") { + if (context.isNewRecipeUser && context.user.loginMethods.length === 1) { + // TODO: Sign up + } else { + // TODO: Sign in + } + } + } + // highlight-end + }), + supertokensUISession.init() + ] +}); +``` + +:::info +Please refer to [this page](../advanced-customizations/frontend-hooks/handle-event) to learn more about the `onHandleEvent` hook. +::: + + + diff --git a/v2/thirdpartypasswordless/common-customizations/multi-tenancy/common-domain-login.mdx b/v2/thirdpartypasswordless/common-customizations/multi-tenancy/common-domain-login.mdx index a3a62412a..2eea41b23 100644 --- a/v2/thirdpartypasswordless/common-customizations/multi-tenancy/common-domain-login.mdx +++ b/v2/thirdpartypasswordless/common-customizations/multi-tenancy/common-domain-login.mdx @@ -173,51 +173,6 @@ export const AuthPage = () => { - - - - -```tsx -import { useState } from "react"; -import { getRoutingComponent } from "supertokens-auth-react/ui"; -^{prebuiltuiimport} -import { useSessionContext } from "supertokens-auth-react/recipe/session"; - -export const AuthPage = () => { - const [inputTenantId, setInputTenantId] = useState(""); - const tenantId = localStorage.getItem("tenantId") ?? undefined; - const session = useSessionContext(); - - if (session.loading) { - return null; - } - - if ( - tenantId !== undefined || // if we have a tenantId stored - session.doesSessionExist === true || // or an active session (it'll contain the tenantId) - new URLSearchParams(location.search).has("tenantId") // or we are on a link (e.g.: email verification) that contains the tenantId - ) { - return getRoutingComponent([^{recipePreBuiltUINameCapitalLetters}]); - } else { - return ( -
{ - // this value will be read by SuperTokens as shown in the next steps. - localStorage.setItem("tenantId", inputTenantId); - }}> -

Enter your organisation's name:

- setInputTenantId(e.target.value)} /> -
- -
- ); - } -}; -``` - - - - - We render a simple UI which asks the user for their organisation's name. Their input will be treated as their tenant ID. - Once the user has submitted that form, we will store their input in localstorage. This value will be read later on (as shown below) by SuperTokens to render the right login method based on the saved tenantId. - In case the tenantID exists in localstorage, we render the SuperTokens UI as usual. @@ -233,6 +188,20 @@ We want to render the `AuthPage` component to show on `^{form_websiteBasePath}/* The `AuthPage` will replace the call to `getSuperTokensRoutesForReactRouterDom` or `getRoutingComponent` that you may have added to your app from the quick setup section. ::: + + + + +:::caution +No code snippet provided here, however, if you visit the auth component, you will see that we are rendering the pre built UI in the `"supertokensui"` `div` element on page load. The logic here needs to change to first check if the user has provided us with the tenantId. If they have, we render the SuperTokens UI as usual. If they have not, we render a simple UI which asks the user for their tenant id and save that in localstorage. + +Switch to the React code tab here to see how this is implemented in React, and a similar logic can be followed here. +::: + + + + + @@ -403,6 +372,50 @@ We also set the `usesDynamicLoginMethods` to `true` which tells SuperTokens that + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIMultitenancy from "supertokens-auth-react-script/recipe/multitenancy"; + +supertokensUIInit({ + appInfo: { + appName: "...", + apiDomain: "...", + websiteDomain: "...", + apiBasePath: "...", + websiteBasePath: "..." + }, + // highlight-next-line + usesDynamicLoginMethods: true, + recipeList: [ + // highlight-start + supertokensUIMultitenancy.init({ + override: { + functions: (oI) => { + return { + ...oI, + getTenantId: (input) => { + let tid = localStorage.getItem("tenantId"); + return tid === null ? undefined : tid; + } + } + } + } + }) + // highlight-end + // other recipes... + ] +}); +``` + +:::important +We also set the `usesDynamicLoginMethods` to `true` which tells SuperTokens that the login methods are dynamic (based on the tenantId). This means that on page load (of the login page), SuperTokens will first fetch the configured login methods for the tenantId and display the login UI based on the result of the API call. +::: + + + @@ -667,6 +680,42 @@ SuperTokens.init({ + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; +import supertokensUIMultitenancy from "supertokens-auth-react-script/recipe/multitenancy"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + // highlight-start + getRedirectionURL: async (context) => { + if (context.action === "SUCCESS" && context.newSessionCreated) { + let claimValue: string[] | undefined = await supertokensUISession.getClaimValue({ + claim: supertokensUIMultitenancy.AllowedDomainsClaim + }); + if (claimValue !== undefined) { + window.location.href = "https://" + claimValue[0]; + } else { + // there was no configured allowed domain for this user. Throw an error cause of + // misconfig or redirect to a default sub domain + } + } + return undefined; + }, + // highlight-end + recipeList: [ /* Recipe init here... */ ] +}); +``` + + + @@ -788,6 +837,68 @@ Above, in `Session.init` on the frontend, we add the `hasAccessToCurrentDomain` + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; +import supertokensMultitenancy from "supertokens-web-js-script/recipe/multitenancy"; + +supertokensUISession.init({ + override: { + functions: (oI) => ({ + ...oI, + getGlobalClaimValidators: ({ claimValidatorsAddedByOtherRecipes }) => [ + ...claimValidatorsAddedByOtherRecipes, + { + ...supertokensMultitenancy.AllowedDomainsClaim.validators.hasAccessToCurrentDomain(), + onFailureRedirection: async () => { + let claimValue = await supertokensUISession.getClaimValue({ + claim: supertokensMultitenancy.AllowedDomainsClaim, + }); + return "https://" + claimValue![0]; + }, + }, + ], + }), + }, +}) +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: +```tsx +import Session from 'supertokens-web-js/recipe/session'; +import { AllowedDomainsClaim } from 'supertokens-web-js/recipe/multitenancy'; + +Session.init({ + override: { + functions: (oI) => ({ + ...oI, + getGlobalClaimValidators: ({ claimValidatorsAddedByOtherRecipes }) => [ + ...claimValidatorsAddedByOtherRecipes, + { + ...AllowedDomainsClaim.validators.hasAccessToCurrentDomain(), + onFailureRedirection: async () => { + let claimValue = await Session.getClaimValue({ + claim: AllowedDomainsClaim, + }); + return "https://" + claimValue![0]; + }, + }, + ], + }), + }, +}) +``` + +Above, in `Session.init` on the frontend, we add the `hasAccessToCurrentDomain` claim validator to the global validators. This means, that [whenever we check protect a route](../sessions/protecting-frontend-routes), it will check if `hasAccessToCurrentDomain` has passed, and if not, SuperTokens will redirect to the user to their right sub domain (via the values set in the `AllowedDomainsClaim` session claim). + + + diff --git a/v2/thirdpartypasswordless/common-customizations/multi-tenancy/sub-domain-login.mdx b/v2/thirdpartypasswordless/common-customizations/multi-tenancy/sub-domain-login.mdx index 4a0170ed0..7b62448d8 100644 --- a/v2/thirdpartypasswordless/common-customizations/multi-tenancy/sub-domain-login.mdx +++ b/v2/thirdpartypasswordless/common-customizations/multi-tenancy/sub-domain-login.mdx @@ -132,6 +132,48 @@ SuperTokens.init({ + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; +import supertokensUIMultitenancy from "supertokens-auth-react-script/recipe/multitenancy"; +supertokensUIInit({ + appInfo: { + appName: "^{form_appName}", + apiDomain: "^{form_apiDomain}", + websiteDomain: "^{form_websiteDomain}", + apiBasePath: "^{form_apiBasePath}", + websiteBasePath: "^{form_websiteBasePath}" + }, + // highlight-start + usesDynamicLoginMethods: true, + // highlight-end + recipeList: [ + // Other recipes... + supertokensUISession.init(), + // highlight-start + supertokensUIMultitenancy.init({ + override: { + functions: (oI) => { + return { + ...oI, + getTenantId: async () => { + // We treat the sub domain as the tenant ID + return window.location.host.split('.')[0] + } + } + } + }, + }) + // highlight-end + ] +}); +``` + + + @@ -497,6 +539,68 @@ Above, in `Session.init` on the frontend, we add the `hasAccessToCurrentDomain` + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; +import supertokensMultitenancy from "supertokens-web-js-script/recipe/multitenancy"; + +supertokensUISession.init({ + override: { + functions: (oI) => ({ + ...oI, + getGlobalClaimValidators: ({ claimValidatorsAddedByOtherRecipes }) => [ + ...claimValidatorsAddedByOtherRecipes, + { + ...supertokensMultitenancy.AllowedDomainsClaim.validators.hasAccessToCurrentDomain(), + onFailureRedirection: async () => { + let claimValue = await supertokensUISession.getClaimValue({ + claim: supertokensMultitenancy.AllowedDomainsClaim, + }); + return "https://" + claimValue![0]; + }, + }, + ], + }), + }, +}) +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: +```tsx +import Session from 'supertokens-web-js/recipe/session'; +import { AllowedDomainsClaim } from 'supertokens-web-js/recipe/multitenancy'; + +Session.init({ + override: { + functions: (oI) => ({ + ...oI, + getGlobalClaimValidators: ({ claimValidatorsAddedByOtherRecipes }) => [ + ...claimValidatorsAddedByOtherRecipes, + { + ...AllowedDomainsClaim.validators.hasAccessToCurrentDomain(), + onFailureRedirection: async () => { + let claimValue = await Session.getClaimValue({ + claim: AllowedDomainsClaim, + }); + return "https://" + claimValue![0]; + }, + }, + ], + }), + }, +}) +``` + +Above, in `Session.init` on the frontend, we add the `hasAccessToCurrentDomain` claim validator to the global validators. This means, that [whenever we check protect a route](../sessions/protecting-frontend-routes), it will check if `hasAccessToCurrentDomain` has passed, and if not, SuperTokens will redirect to the user to their right sub domain (via the values set in the `AllowedDomainsClaim` session claim). + + + diff --git a/v2/thirdpartypasswordless/common-customizations/sessions/claims/access-token-payload.mdx b/v2/thirdpartypasswordless/common-customizations/sessions/claims/access-token-payload.mdx index 828b6cb16..ac18be4b9 100644 --- a/v2/thirdpartypasswordless/common-customizations/sessions/claims/access-token-payload.mdx +++ b/v2/thirdpartypasswordless/common-customizations/sessions/claims/access-token-payload.mdx @@ -1111,7 +1111,7 @@ async function someFunc() { ```tsx -import Session from 'supertokens-auth-react/recipe/session'; +import Session from 'supertokens-web-js/recipe/session'; async function someFunc() { if (await Session.doesSessionExist()) { diff --git a/v2/thirdpartypasswordless/common-customizations/sessions/claims/claim-validators.mdx b/v2/thirdpartypasswordless/common-customizations/sessions/claims/claim-validators.mdx index 8ffe6e207..2a7b59a42 100644 --- a/v2/thirdpartypasswordless/common-customizations/sessions/claims/claim-validators.mdx +++ b/v2/thirdpartypasswordless/common-customizations/sessions/claims/claim-validators.mdx @@ -856,8 +856,8 @@ Now whenever you wrap your component with the `` wrapper, SuperToke ```tsx -import SuperTokens from "supertokens-auth-react"; -import Session, { BooleanClaim } from 'supertokens-auth-react/recipe/session'; +import SuperTokens from "supertokens-web-js"; +import Session, { BooleanClaim } from 'supertokens-web-js/recipe/session'; const SecondFactorClaim = new BooleanClaim({ id: "2fa-completed", @@ -870,7 +870,6 @@ SuperTokens.init({ appInfo: { apiDomain: "...", appName: "...", - websiteDomain: "..." }, recipeList: [ //... @@ -894,7 +893,7 @@ SuperTokens.init({ Now you can protect your frontend routes by using the `Session.validateClaims` function as shown below: ```tsx -import Session, { BooleanClaim } from "supertokens-auth-react/recipe/session"; +import Session, { BooleanClaim } from "supertokens-web-js/recipe/session"; const SecondFactorClaim = new BooleanClaim({ id: "2fa-completed", @@ -2286,8 +2285,8 @@ Unlike using the `overrideGlobalClaimValidators` prop, the `useClaimValue` funct ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { @@ -2330,8 +2329,8 @@ async function shouldLoadRoute(): Promise { If you want to have more complex access control, you can get the roles list from the session as follows, and check the list yourself: ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { diff --git a/v2/thirdpartypasswordless/common-customizations/sessions/disable-interception.mdx b/v2/thirdpartypasswordless/common-customizations/sessions/disable-interception.mdx index e1a878e6e..7d4a03d8a 100644 --- a/v2/thirdpartypasswordless/common-customizations/sessions/disable-interception.mdx +++ b/v2/thirdpartypasswordless/common-customizations/sessions/disable-interception.mdx @@ -58,6 +58,63 @@ Session.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUISession.init({ + override: { + functions: (oI) => { + return { + ...oI, + shouldDoInterceptionBasedOnUrl: (url, apiDomain, sessionTokenBackendDomain) => { + try { + let urlObj = new URL(url); + if (!urlObj.pathname.startsWith("/auth")) { + return false; + } + } catch (ignored) { } + return oI.shouldDoInterceptionBasedOnUrl(url, apiDomain, sessionTokenBackendDomain); + } + } + } + } +}) +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import Session from "supertokens-web-js/recipe/session"; + +Session.init({ + override: { + functions: (oI) => { + return { + ...oI, + shouldDoInterceptionBasedOnUrl: (url, apiDomain, sessionTokenBackendDomain) => { + try { + let urlObj = new URL(url); + if (!urlObj.pathname.startsWith("/auth")) { + return false; + } + } catch (ignored) { } + return oI.shouldDoInterceptionBasedOnUrl(url, apiDomain, sessionTokenBackendDomain); + } + } + } + } +}) +``` + + + diff --git a/v2/thirdpartypasswordless/common-customizations/sessions/in-iframe.mdx b/v2/thirdpartypasswordless/common-customizations/sessions/in-iframe.mdx index e43e2fa15..0589f4b94 100644 --- a/v2/thirdpartypasswordless/common-customizations/sessions/in-iframe.mdx +++ b/v2/thirdpartypasswordless/common-customizations/sessions/in-iframe.mdx @@ -69,6 +69,65 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; +declare let cookieHandler: any // typecheck-only, removed from output +declare let windowHandler: any // typecheck-only, removed from output + +supertokensUIInit({ + cookieHandler, + windowHandler, + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUISession.init({ + // highlight-start + tokenTransferMethod: "header", + isInIframe: true + // highlight-end + }) + ] +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from "supertokens-web-js"; +import Session from "supertokens-web-js/recipe/session"; +declare let cookieHandler: any // typecheck-only, removed from output +declare let windowHandler: any // typecheck-only, removed from output + +SuperTokens.init({ + cookieHandler, + windowHandler, + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + Session.init({ + // highlight-start + tokenTransferMethod: "header", + isInIframe: true + // highlight-end + }) + ], +}) +``` + + + @@ -84,8 +143,12 @@ SuperTokens.init({ ```tsx import SuperTokens from "supertokens-web-js"; import Session from "supertokens-web-js/recipe/session"; +declare let cookieHandler: any // typecheck-only, removed from output +declare let windowHandler: any // typecheck-only, removed from output SuperTokens.init({ + cookieHandler, + windowHandler, appInfo: { apiDomain: "...", appName: "...", @@ -107,7 +170,11 @@ SuperTokens.init({ ```tsx import supertokens from "supertokens-web-js-script"; import supertokensSession from "supertokens-web-js-script/recipe/session"; +declare let cookieHandler: any // typecheck-only, removed from output +declare let windowHandler: any // typecheck-only, removed from output supertokens.init({ + cookieHandler, + windowHandler, appInfo: { apiDomain: "...", appName: "...", diff --git a/v2/thirdpartypasswordless/common-customizations/sessions/multiple-api-endpoints.mdx b/v2/thirdpartypasswordless/common-customizations/sessions/multiple-api-endpoints.mdx index 2b9aae909..12d91616d 100644 --- a/v2/thirdpartypasswordless/common-customizations/sessions/multiple-api-endpoints.mdx +++ b/v2/thirdpartypasswordless/common-customizations/sessions/multiple-api-endpoints.mdx @@ -241,6 +241,51 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. +```tsx +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUISession.init({ + // highlight-next-line + sessionTokenBackendDomain: ".example.com" + }) + ] +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from 'supertokens-web-js'; +import Session from 'supertokens-web-js/recipe/session'; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + Session.init({ + sessionTokenBackendDomain: ".example.com" + }), + ], +}); +``` + + + diff --git a/v2/thirdpartypasswordless/common-customizations/sessions/protecting-frontend-routes.mdx b/v2/thirdpartypasswordless/common-customizations/sessions/protecting-frontend-routes.mdx index 13b1829bc..232bba79f 100644 --- a/v2/thirdpartypasswordless/common-customizations/sessions/protecting-frontend-routes.mdx +++ b/v2/thirdpartypasswordless/common-customizations/sessions/protecting-frontend-routes.mdx @@ -123,7 +123,7 @@ function MyDashboardComponent(props: any) { You can use the `doesSessionExist` function to check if a session exists in all your routes. ```tsx -import Session from 'supertokens-auth-react/recipe/session'; +import Session from 'supertokens-web-js/recipe/session'; async function doesSessionExist() { if (await Session.doesSessionExist()) { @@ -211,8 +211,8 @@ function ProtectedComponent() { ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { @@ -255,8 +255,8 @@ async function shouldLoadRoute(): Promise { If you want to have more complex access control, you can get the roles list from the session as follows, and check the list yourself: ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { diff --git a/v2/thirdpartypasswordless/common-customizations/sessions/revoke-session.mdx b/v2/thirdpartypasswordless/common-customizations/sessions/revoke-session.mdx index 500a1f526..fdfdad5b9 100644 --- a/v2/thirdpartypasswordless/common-customizations/sessions/revoke-session.mdx +++ b/v2/thirdpartypasswordless/common-customizations/sessions/revoke-session.mdx @@ -66,7 +66,7 @@ The [`signOut` method](https://supertokens.com/docs/web-js/modules/recipe_sessio ```tsx // highlight-next-line -import Session from "supertokens-auth-react/recipe/session"; +import Session from "supertokens-web-js/recipe/session"; async function logout () { // highlight-next-line diff --git a/v2/thirdpartypasswordless/common-customizations/sessions/share-session-across-sub-domains.mdx b/v2/thirdpartypasswordless/common-customizations/sessions/share-session-across-sub-domains.mdx index 9c95085ab..b0f863386 100644 --- a/v2/thirdpartypasswordless/common-customizations/sessions/share-session-across-sub-domains.mdx +++ b/v2/thirdpartypasswordless/common-customizations/sessions/share-session-across-sub-domains.mdx @@ -58,6 +58,56 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + // ... + // this should be equal to the domain where the user will see the login UI + apiDomain: "...", + appName: "...", + websiteDomain: "https://example.com" + }, + recipeList: [ + supertokensUISession.init({ + // highlight-next-line + sessionTokenFrontendDomain: ".example.com" + }) + ] +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from "supertokens-web-js"; +import Session from "supertokens-web-js/recipe/session"; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + Session.init({ + // highlight-start + sessionTokenFrontendDomain: ".example.com" + // highlight-end + }), + ], +}) +``` + + + :::caution diff --git a/v2/thirdpartypasswordless/common-customizations/sessions/ssr.mdx b/v2/thirdpartypasswordless/common-customizations/sessions/ssr.mdx index 116901a02..863e5cb5b 100644 --- a/v2/thirdpartypasswordless/common-customizations/sessions/ssr.mdx +++ b/v2/thirdpartypasswordless/common-customizations/sessions/ssr.mdx @@ -83,7 +83,7 @@ export function AttemptRefresh(props: any) { ```tsx -import Session from 'supertokens-auth-react/recipe/session'; +import Session from 'supertokens-web-js/recipe/session'; function attemptRefresh() { Session.attemptRefreshingSession().then(success => { diff --git a/v2/thirdpartypasswordless/common-customizations/sessions/token-transfer-method.mdx b/v2/thirdpartypasswordless/common-customizations/sessions/token-transfer-method.mdx index d07b73456..05bf214db 100644 --- a/v2/thirdpartypasswordless/common-customizations/sessions/token-transfer-method.mdx +++ b/v2/thirdpartypasswordless/common-customizations/sessions/token-transfer-method.mdx @@ -71,6 +71,54 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +This change is in your auth route config. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUISession.init({ + // highlight-next-line + tokenTransferMethod: "header" // or "cookie" + }) + ] +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from "supertokens-web-js"; +import Session from "supertokens-web-js/recipe/session"; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + Session.init({ + // highlight-next-line + tokenTransferMethod: "header" // or "cookie" + }) + ], +}) +``` + + + diff --git a/v2/thirdpartypasswordless/common-customizations/sessions/with-jwt/read-jwt.mdx b/v2/thirdpartypasswordless/common-customizations/sessions/with-jwt/read-jwt.mdx index fe1b9a7e5..6406c10f2 100644 --- a/v2/thirdpartypasswordless/common-customizations/sessions/with-jwt/read-jwt.mdx +++ b/v2/thirdpartypasswordless/common-customizations/sessions/with-jwt/read-jwt.mdx @@ -435,7 +435,7 @@ async function getJWT() { ```tsx -import Session from 'supertokens-auth-react/recipe/session'; +import Session from 'supertokens-web-js/recipe/session'; async function getJWT() { if (await Session.doesSessionExist()) { diff --git a/v2/thirdpartypasswordless/common-customizations/sign-in-and-up/default-country.mdx b/v2/thirdpartypasswordless/common-customizations/sign-in-and-up/default-country.mdx index 0fcab2dd0..501f13d08 100644 --- a/v2/thirdpartypasswordless/common-customizations/sign-in-and-up/default-country.mdx +++ b/v2/thirdpartypasswordless/common-customizations/sign-in-and-up/default-country.mdx @@ -2,15 +2,21 @@ id: default-country title: Setting default country for phone inputs hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" import { PasswordlessFrontendForm, ConditionalSection } from "/src/components/snippetConfigForm/passwordlessFrontendForm"; + # Setting default country for phone inputs + + + + ```tsx @@ -60,7 +66,40 @@ SuperTokens.init({ ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIPasswordless.init({ + contactMethod: "PHONE", + // highlight-start + signInUpFeature: { + /* + * Must be a two-letter ISO country code (e.g.: "US") + */ + defaultCountry: "HU", + } + // highlight-end + }), + supertokensUISession.init({ /* ... */ }) + ] +}); +``` + + + @@ -72,7 +111,7 @@ By default, there is no default country selected. This means that users will hav If you would like to set a default country (for all users), then you should use the `defaultCountry` config: - + ```tsx @@ -104,8 +143,51 @@ SuperTokens.init({ ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIPasswordless.init({ + contactMethod: "EMAIL_OR_PHONE", + // highlight-start + signInUpFeature: { + /* + * Must be a two-letter ISO country code (e.g.: "US") + */ + defaultCountry: "HU", + } + // highlight-end + }), + supertokensUISession.init({ /* ... */ }) + ] +}); +``` + + + + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/thirdpartypasswordless/common-customizations/sign-in-and-up/resend-time-gap.mdx b/v2/thirdpartypasswordless/common-customizations/sign-in-and-up/resend-time-gap.mdx index 788bcda66..b261df0b7 100644 --- a/v2/thirdpartypasswordless/common-customizations/sign-in-and-up/resend-time-gap.mdx +++ b/v2/thirdpartypasswordless/common-customizations/sign-in-and-up/resend-time-gap.mdx @@ -2,13 +2,18 @@ id: resend-time-gap title: Changing email / SMS resend time interval hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Changing email / SMS resend time interval + + + :::caution This limit is only enforced on the client-side. For API rate-limiting please check out the [Advanced customizations](../../advanced-customizations/apis-override/about) section. @@ -17,7 +22,7 @@ This limit is only enforced on the client-side. For API rate-limiting please che You can set `resendEmailOrSMSGapInSeconds` to establish a minimum delay before the frontend allows the user to click the "Resend" button. - + ```tsx @@ -47,4 +52,45 @@ SuperTokens.init({ ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIPasswordless.init({ + contactMethod: "EMAIL_OR_PHONE", // This example will work with any contactMethod. + // highlight-start + signInUpFeature: { + // The default value is 15 seconds + resendEmailOrSMSGapInSeconds: 60, + } + // highlight-end + }), + supertokensUISession.init({ /* ... */ }) + ] +}); +``` + + + + + + + +:::caution +At the moment, this is a frontend only setting for the pre built UI, and is therefore not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/thirdpartypasswordless/common-customizations/sign-in-and-up/toc-privacypolicy.mdx b/v2/thirdpartypasswordless/common-customizations/sign-in-and-up/toc-privacypolicy.mdx index 592749007..380a49b86 100644 --- a/v2/thirdpartypasswordless/common-customizations/sign-in-and-up/toc-privacypolicy.mdx +++ b/v2/thirdpartypasswordless/common-customizations/sign-in-and-up/toc-privacypolicy.mdx @@ -2,19 +2,27 @@ id: toc-privacypolicy title: Terms of service & Privacy policy links hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" + + + +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Terms of service & Privacy policy links + + + You can provide a Privacy policy and Terms of service link which will render the following text on the sign up page: -- Provided both links: "By continuing, you agree to our [Terms of Service](./toc-privacypolicy) and [Privacy Policy](./toc-privacypolicy)" -- Provided only Terms of service link: "By continuing, you agree to our [Terms of Service](./toc-privacypolicy)" -- Provided only Privacy policy link: "By continuing, you agree to our [Privacy Policy](./toc-privacypolicy)" +- Provided both links: "By signing up, you agree to our [Terms of Service](./toc-privacypolicy) and [Privacy Policy](./toc-privacypolicy)" +- Provided only Terms of service link: "By signing up, you agree to our [Terms of Service](./toc-privacypolicy)" +- Provided only Privacy policy link: "By signing up, you agree to our [Privacy Policy](./toc-privacypolicy)" - + ```tsx @@ -26,11 +34,44 @@ SuperTokens.init({ appName: "...", websiteDomain: "..." }, + // highlight-start + termsOfServiceLink: "https://example.com/terms-of-service", + privacyPolicyLink: "https://example.com/privacy-policy", + // highlight-end + recipeList: [/* ... */] +}); +``` + + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + // highlight-start termsOfServiceLink: "https://example.com/terms-of-service", privacyPolicyLink: "https://example.com/privacy-policy", + // highlight-end recipeList: [/* ... */] }); ``` - + + + + + +:::caution +Not applicable since you do not use our pre built UI. +::: + + + diff --git a/v2/thirdpartypasswordless/common-customizations/signup-form/built-in-providers.mdx b/v2/thirdpartypasswordless/common-customizations/signup-form/built-in-providers.mdx index b1ac89d38..e66fffcea 100644 --- a/v2/thirdpartypasswordless/common-customizations/signup-form/built-in-providers.mdx +++ b/v2/thirdpartypasswordless/common-customizations/signup-form/built-in-providers.mdx @@ -62,6 +62,43 @@ SuperTokens.init({ }); ``` + + + + +Import and all the built in providers that you wish to show in the UI as shown below. + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIThirdParty from "supertokens-auth-react-script/recipe/thirdparty"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIThirdParty.init({ + signInAndUpFeature: { + // highlight-start + providers: [ + supertokensUIThirdParty.Github.init(), + supertokensUIThirdParty.Google.init(), + supertokensUIThirdParty.Facebook.init(), + supertokensUIThirdParty.Apple.init(), + ], + // highlight-end + // ... + }, + // ... + }), + // ... + ] +}); +``` + @@ -108,6 +145,15 @@ SuperTokens.init({ ] }); ``` + + + + +:::caution +This is not possible for non react apps at the moment. Please use custom UI instead for the sign in form. +::: + + diff --git a/v2/thirdpartypasswordless/common-customizations/signup-form/custom-providers.mdx b/v2/thirdpartypasswordless/common-customizations/signup-form/custom-providers.mdx index f9861a33a..ee1e47137 100644 --- a/v2/thirdpartypasswordless/common-customizations/signup-form/custom-providers.mdx +++ b/v2/thirdpartypasswordless/common-customizations/signup-form/custom-providers.mdx @@ -69,6 +69,14 @@ SuperTokens.init({ ] }); ``` + + + + +:::caution +This is not possible for non react apps at the moment. Please use custom UI instead for the sign in form. +::: + diff --git a/v2/thirdpartypasswordless/common-customizations/styling/changing-colours.mdx b/v2/thirdpartypasswordless/common-customizations/styling/changing-colours.mdx index 5c91a71c4..26ef412b8 100644 --- a/v2/thirdpartypasswordless/common-customizations/styling/changing-colours.mdx +++ b/v2/thirdpartypasswordless/common-customizations/styling/changing-colours.mdx @@ -2,19 +2,24 @@ id: changing-colours title: Changing Colours hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Changing Colours + + + It is possible to update the default theme with your colours to make it fit perfectly with your website by defining a few css variables in the `style` property to the `ThirdPartyPasswordless.init` call. You have to specify the colors as RGB (see the following example), because we use the `rgb` and `rgba` functions to apply them. For example if your website uses a dark theme, here is how you can quickly customize it: - + ```tsx @@ -45,7 +50,39 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + // highlight-start + style: ` + [data-supertokens~=container] { + --palette-background: 51, 51, 51; + --palette-inputBackground: 41, 41, 41; + --palette-inputBorder: 41, 41, 41; + --palette-textTitle: 255, 255, 255; + --palette-textLabel: 255, 255, 255; + --palette-textPrimary: 255, 255, 255; + --palette-error: 173, 46, 46; + --palette-textInput: 169, 169, 169; + --palette-textLink: 169, 169, 169; + } + `, + // highlight-end + recipeList: [ /* ... */] +}); +``` + + Prebuilt form with custom colors @@ -148,4 +185,14 @@ Changes to the palette will apply to all the UI components we provide. If you wa - Description: This value controls the color of the "Powered by SuperTokens" text on the bottom of sign-in/up pages - Default: ```173, 189, 196``` (heather grey) -Prebuilt form SuperTokens label \ No newline at end of file +Prebuilt form SuperTokens label + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/thirdpartypasswordless/common-customizations/styling/changing-style.mdx b/v2/thirdpartypasswordless/common-customizations/styling/changing-style.mdx index 6d22f0494..9f38c5d6c 100644 --- a/v2/thirdpartypasswordless/common-customizations/styling/changing-style.mdx +++ b/v2/thirdpartypasswordless/common-customizations/styling/changing-style.mdx @@ -2,13 +2,17 @@ id: changing-style title: Changing Style via CSS hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Changing Style via CSS + + Updating the CSS allows you to change the UI of our components to meet your needs. @@ -27,7 +31,7 @@ Each stylable components contains `data-supertokens` attributes (in our example Let's customize elements with the `button` attribute. The syntax for styling is plain CSS. - + ```tsx @@ -53,7 +57,34 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + // highlight-start + style: ` + [data-supertokens~=button] { + background-color: #252571; + border: 0px; + width: 30%; + margin: 0 auto; + } + `, + // highlight-end + recipeList: [ /* ... */] +}); +``` + + The above will result in: @@ -63,7 +94,7 @@ The above will result in: By default, SuperTokens uses the Arial font. The best way to override this is to add a `font-family` styling to the `container` component in the recipe configuration. - + ```tsx @@ -84,13 +115,35 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + style: ` + [data-supertokens~=container] { + font-family: cursive; + } + `, + recipeList: [ /* ... */] +}); +``` + + ### Using media queries You may want to have different CSS for different viewports. This can be achieved via media queries like this: - + ```tsx @@ -120,13 +173,44 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + style: ` + [data-supertokens~=button] { + background-color: #252571; + border: 0px; + width: 30%; + margin: 0 auto; + } + + @media (max-width: 440px) { + [data-supertokens~=button] { + width: 90%; + } + } + `, + recipeList: [ /* ... */], +}); +``` + + ## Customising the Sign-Up / Sign-In form These are the screens shown when the user tries to log in or sign up for the application. - + ```tsx @@ -145,13 +229,33 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + style: `[data-supertokens~=authPage] { + ... + }`, + recipeList: [ /* ... */] +}); +``` + + ## Customizing the OAuth callback screen This screen is shown when the user returns to the application from the OAuth provider - + ```tsx @@ -178,13 +282,41 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIThirdParty from "supertokens-auth-react-script/recipe/thirdparty"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + supertokensUIThirdParty.init({ + // highlight-start + oAuthCallbackScreen: { + style: ` ... ` + } + // highlight-end + }), + supertokensUISession.init() + ] +}); +``` + + ### OTP input screen This screen is shown if your users are logging in by typing an OTP - + ```tsx @@ -212,14 +344,43 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIPasswordless.init({ + contactMethod: "EMAIL_OR_PHONE", // This example will work with any contactMethod. + // highlight-start + signInUpFeature: { + userInputCodeFormStyle: ` ... ` + } + // highlight-end + }), + supertokensUISession.init() + ] +}); +``` + + ### Link sent screen This screen is shown if your users can only log in via a magic link. - + ```tsx @@ -247,13 +408,42 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIPasswordless.init({ + contactMethod: "EMAIL_OR_PHONE", // This example will work with any contactMethod. + // highlight-start + signInUpFeature: { + linkSentScreenStyle: ` ... ` + } + // highlight-end + }), + supertokensUISession.init() + ] +}); +``` + + ## Customizing the Magic Link Clicked Screen This screen is shown when the user clicks a magic link. - + ```tsx @@ -281,4 +471,43 @@ SuperTokens.init({ }); ``` - \ No newline at end of file + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + recipeList: [ + supertokensUIPasswordless.init({ + contactMethod: "EMAIL_OR_PHONE", // This example will work with any contactMethod. + // highlight-start + linkClickedScreenFeature: { + style: ` ... ` + } + // highlight-end + }), + supertokensUISession.init() + ] +}); +``` + + + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/thirdpartypasswordless/common-customizations/styling/shadow-dom.mdx b/v2/thirdpartypasswordless/common-customizations/styling/shadow-dom.mdx index 8f703aab6..eb9077930 100644 --- a/v2/thirdpartypasswordless/common-customizations/styling/shadow-dom.mdx +++ b/v2/thirdpartypasswordless/common-customizations/styling/shadow-dom.mdx @@ -2,20 +2,30 @@ id: shadow-dom title: Disable use of shadow DOM hide_title: true +show_ui_switcher: true --- -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs" + + + +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Disable use of shadow DOM + + + We use [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) to prevent CSS clashes between your CSS and the ones we provide. This guarantees that all our UI will render as expected. -However, this means that you cannot override our CSS using your CSS (though you can [use JS to do that](./changing-style)). +However, this has a few problems: +- You cannot override our CSS using your CSS (though you can [use JS to do that](./changing-style)). +- Password managers may not work for your end user. If you want to disable use of shadow dom, you can do so like: - + ```tsx @@ -27,13 +37,43 @@ SuperTokens.init({ appName: "...", websiteDomain: "..." }, + // highlight-next-line useShadowDom: false, - recipeList: [ /* ... */] + recipeList: [/* ... */] }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "..." + }, + // highlight-next-line + useShadowDom: false, + recipeList: [/* ... */] +}); +``` + + :::caution If disabled, please be sure to check that our components render correctly - because your CSS might affect our components' UI (the other way around won't happen). -::: \ No newline at end of file +::: + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/thirdpartypasswordless/common-customizations/translations.mdx b/v2/thirdpartypasswordless/common-customizations/translations.mdx index 9d4d58ef4..1f12c8499 100644 --- a/v2/thirdpartypasswordless/common-customizations/translations.mdx +++ b/v2/thirdpartypasswordless/common-customizations/translations.mdx @@ -2,16 +2,18 @@ id: translations title: Language Translation for the UI hide_title: true +show_ui_switcher: true --- - - -import FrontendSDKTabs from "/src/components/tabs/FrontendSDKTabs"; +import FrontendPreBuiltUITabs from "/src/components/tabs/FrontendPreBuiltUITabs" import TabItem from '@theme/TabItem'; -import NpmOrScriptTabs from "/src/components/tabs/NpmOrScriptTabs" +import {PreBuiltOrCustomUISwitcher, PreBuiltUIContent, CustomUIContent} from "/src/components/preBuiltOrCustomUISwitcher" # Language Translation for the UI + + + You can translate the UI using two main methods: 1. You can override all displayed translation strings by providing translated versions for different languages (and even change the default English version). 2. You can provide a translation function to integrate supertokens with your preferred internationalization library. @@ -28,7 +30,7 @@ You can provide translations for each segment displayed in our UIs. - You can find the third party login UI keys [here](https://github.com/supertokens/supertokens-auth-react/blob/master/lib/ts/recipe/thirdparty/components/themes/translations.ts). ::: - + ```tsx @@ -73,13 +75,57 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +supertokensUIInit({ + // highlight-start + languageTranslations: { // This object contains all translation related options + translations: { // These are the displayed translation strings for each language + // The property names define the language code of the translations + en: { + // Here each key is a translation key and the value is the string that will be displayed + // Setting the value to undefined will either display the translation from the default language or the translation key + BRANDING_POWERED_BY_START: "We ❤️ ", + // If you added a custom label or placeholder you can also provide translation for them if necessary + // You can also use these to provide translations for your component overrides + MY_CUSTOM_LABEL: "Age", + }, + hu: { + BRANDING_POWERED_BY_START: "Sok szeretettel: ", + // This key is associated with an empty string by default, but you can override these as well. + BRANDING_POWERED_BY_END: " 😊", + } + }, + /* + * This optional property sets the default and fallback language. + * It can be any string that will be used to fetch translations from the above object. + * Defaults to "en" + */ + defaultLanguage: "hu", + }, + // highlight-end + appInfo: { + appName: "...", + apiDomain: "...", + websiteDomain: "...", + }, + recipeList: [ + // ... + ], +}); +``` + + ### Loading translations After initialization, you can provide additional translation data by calling the `SuperTokens.loadTranslation`. This can be useful if you are loading them asynchronously. - + ```tsx @@ -94,13 +140,27 @@ SuperTokens.loadTranslation({ }); ``` - + + + +```tsx +import supertokensUI from "supertokens-auth-react-script"; +// This method takes an object as a parameter, which is structured the same as above. +// This will be merged into the existing definitions, so any properties missing here won't remove them from the already loaded translations +supertokensUI.loadTranslation({ + en: { + BRANDING_POWERED_BY_END: " :)", + } +}); +``` + + ### Changing the current language You can update which translations store is displayed by calling the `SuperTokens.changeLanguage`. - + ```tsx @@ -109,7 +169,15 @@ import SuperTokens from "supertokens-auth-react"; SuperTokens.changeLanguage("hu"); ``` - + + + +```tsx +import supertokensUI from "supertokens-auth-react-script"; +supertokensUI.changeLanguage("hu"); +``` + + ## Using an internationalization library @@ -117,7 +185,7 @@ You can easily integrate SuperTokens with your internationalization library of c 1. Provide the translation function in `SuperTokens.init` - + ```tsx @@ -144,7 +212,33 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +supertokensUIInit({ + // highlight-start + languageTranslations: { + translationFunc: (key: string) => { + // The string returned by this function will be displayed + return key + "!"; + }, + }, + // highlight-end + appInfo: { + appName: "...", + apiDomain: "...", + websiteDomain: "...", + }, + recipeList: [ + // ... + ], +}); +``` + + 2. Call `SuperTokens.changeLanguage` or `SuperTokens.loadTranslation` to re-render the translated UI @@ -158,7 +252,7 @@ If the SDK can't find a segment in the current language's translation store, we The currently chosen language is stored in a cookie, this way it can be restored the next time the page loads. The domain of this cookie can be customized through the `currentLanguageCookieScope` option. This can be useful if you are running our SDK in multiple applications and want to share the language choice between sub-domains. - + ```tsx @@ -182,13 +276,36 @@ SuperTokens.init({ }); ``` - + + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +supertokensUIInit({ + // highlight-start + languageTranslations: { + currentLanguageCookieScope: ".example.com", + }, + // highlight-end + appInfo: { + appName: "...", + apiDomain: "...", + websiteDomain: "...", + }, + recipeList: [ + // ... + ], +}); +``` + + ## Translations in component overrides The SDK also exports the `useTranslation` React hook you can use while overriding components. It returns a function that takes a translation segment key and returns it translated to the currently selected language. For more information on what translation keys you should use and the exact syntax, please see the original source code of the component you are overriding. - + ```tsx @@ -208,4 +325,22 @@ export const HeaderOverride = () => { ``` - \ No newline at end of file + + + +:::caution +Not applicable for non react apps. +::: + + + + + + + +:::caution +Not applicable since you do not use our pre built UI +::: + + + diff --git a/v2/thirdpartypasswordless/pre-built-ui/auth-redirection.mdx b/v2/thirdpartypasswordless/pre-built-ui/auth-redirection.mdx index 319295e7e..ed93e37c6 100644 --- a/v2/thirdpartypasswordless/pre-built-ui/auth-redirection.mdx +++ b/v2/thirdpartypasswordless/pre-built-ui/auth-redirection.mdx @@ -50,6 +50,47 @@ SuperTokens.init({ }); ``` + + + + +By default, the user is redirected the the `/` route on your website post login. To change this, you can use the `getRedirectionURL` function on the frontend as shown below: + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + // highlight-start + getRedirectionURL: async (context) => { + if (context.action === "SUCCESS" && context.newSessionCreated) { + if (context.redirectToPath !== undefined) { + // we are navigating back to where the user was before they authenticated + return context.redirectToPath; + } + if (context.createdNewUser) { + // user signed up + } else { + // user signed in + } + return "/dashboard"; + } + return undefined; + }, + // highlight-end + recipeList: [ /* Recipe list */] +}); +``` + + + + + The user will be redirected to the provided URL on: - Successful sign up. - Successful sign in. @@ -62,9 +103,6 @@ If you want to redirect the user to a different domain, then you can do so by fi Please refer to [this page](../advanced-customizations/frontend-hooks/redirection-callback) to learn more about the `getRedirectionURL` hook. ::: - - - ## Redirect user to the login page @@ -100,12 +138,10 @@ function NavBar () { -Use the `redirectToAuth({show?: "signin" | "signup", redirectBack?: boolean}?)` function to redirect the user to the login screen. For example, you may want to call this function when the user clicks on the login button. +Redirect the user to the `/auth` (this is the default path for the pre built UI) ```ts import { Component } from "@angular/core"; -// highlight-next-line -import { redirectToAuth } from "supertokens-auth-react"; @Component({ selector: 'nav-bar', @@ -120,20 +156,20 @@ import { redirectToAuth } from "supertokens-auth-react"; export class NavBarComponent { async onLogin () { // highlight-next-line - redirectToAuth(); + window.location.href = "/auth?show=signin&redirecToPath=" + encodeURIComponent(window.location.pathname); } } ``` -- Call `redirectToAuth({show: "signin"})` to take them to the sign in screen -- Call `redirectToAuth({show: "signup"})` to take them to the sign up screen -- If you do not want the user to be redirected to the current page post sign in, use `redirectToAuth({redirectBack: false})` +- Set `show=signin` to take them to the sign in screen +- Set `show=signup` to take them to the sign up screen +- Set `redirecToPath` to redirect the user to a specific page after they have signed in, or you can skip it to take them to the `/` route (which is the default one). -Use the `redirectToAuth({show?: "signin" | "signup", redirectBack?: boolean}?)` function to redirect the user to the login screen. For example, you may want to call this function when the user clicks on the login button. +Redirect the user to the `/auth` (this is the default path for the pre built UI) ```html ``` -- Call `redirectToAuth({show: "signin"})` to take them to the sign in screen -- Call `redirectToAuth({show: "signup"})` to take them to the sign up screen -- If you do not want the user to be redirected to the current page post sign in, use `redirectToAuth({redirectBack: false})` +- Set `show=signin` to take them to the sign in screen +- Set `show=signup` to take them to the sign up screen +- Set `redirecToPath` to redirect the user to a specific page after they have signed in, or you can skip it to take them to the `/` route (which is the default one). diff --git a/v2/thirdpartypasswordless/pre-built-ui/enable-email-verification.mdx b/v2/thirdpartypasswordless/pre-built-ui/enable-email-verification.mdx index f713525c2..033a16a9f 100644 --- a/v2/thirdpartypasswordless/pre-built-ui/enable-email-verification.mdx +++ b/v2/thirdpartypasswordless/pre-built-ui/enable-email-verification.mdx @@ -214,6 +214,33 @@ function App() { + + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; +import supertokensUIEmailVerification from "supertokens-auth-react-script/recipe/emailverification"; +import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + +supertokensUIInit({ + appInfo: { + apiDomain: "...", + appName: "...", + websiteDomain: "...", + }, + recipeList: [ + // highlight-start + supertokensUIEmailVerification.init({ + mode: "REQUIRED", // or "OPTIONAL" + }), + // highlight-end + supertokensUISession.init(), + ], +}); +``` + + + @@ -737,8 +764,8 @@ If all validations pass, we render the `props.children` component. ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { EmailVerificationClaim } from "supertokens-auth-react/recipe/emailverification"; +import Session from "supertokens-web-js/recipe/session"; +import { EmailVerificationClaim } from "supertokens-web-js/recipe/emailverification"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { diff --git a/v2/thirdpartypasswordless/pre-built-ui/handling-session-tokens.mdx b/v2/thirdpartypasswordless/pre-built-ui/handling-session-tokens.mdx index 6d37e05ca..11f2460fa 100644 --- a/v2/thirdpartypasswordless/pre-built-ui/handling-session-tokens.mdx +++ b/v2/thirdpartypasswordless/pre-built-ui/handling-session-tokens.mdx @@ -61,7 +61,15 @@ async function getToken(): Promise { -~COPY-TABS=reactjs +```tsx +import Session from "supertokens-web-js/recipe/session"; + +async function getToken(): Promise { + // highlight-next-line + const accessToken = await Session.getAccessToken(); + console.log(accessToken); +} +``` diff --git a/v2/thirdpartypasswordless/pre-built-ui/securing-routes.mdx b/v2/thirdpartypasswordless/pre-built-ui/securing-routes.mdx index 4df26e055..22d56941e 100644 --- a/v2/thirdpartypasswordless/pre-built-ui/securing-routes.mdx +++ b/v2/thirdpartypasswordless/pre-built-ui/securing-routes.mdx @@ -490,7 +490,7 @@ class App extends React.Component { You can use the `doesSessionExist` function to check if a session exists in all your routes. ```tsx -import Session from 'supertokens-auth-react/recipe/session'; +import Session from 'supertokens-web-js/recipe/session'; async function doesSessionExist() { if (await Session.doesSessionExist()) { diff --git a/v2/thirdpartypasswordless/pre-built-ui/setup/frontend.mdx b/v2/thirdpartypasswordless/pre-built-ui/setup/frontend.mdx index 5f561c385..92433149b 100644 --- a/v2/thirdpartypasswordless/pre-built-ui/setup/frontend.mdx +++ b/v2/thirdpartypasswordless/pre-built-ui/setup/frontend.mdx @@ -16,6 +16,7 @@ import {Question, Answer}from "/src/components/question" import AppInfoForm from "/src/components/appInfoForm" import RRDVersionSubTabs from "/src/components/tabs/RRDVersionSubTabs" import NpmVersionOrYarnSubTabs from "/src/components/tabs/NpmVersionOrYarnSubTabs" +import PreBuiltUIInjector from "/src/components/prebuiltuiInjector" # Frontend Integration @@ -73,58 +74,35 @@ yarn add supertokens-auth-react supertokens-web-js -:::important -SuperTokens does not provide Angular components for pre built UI, but, there are two ways of implementing SuperTokens in your Angular frontend: -- Load SuperTokens's pre-built React UI components in your Angular app. Continue following the guide for this flow. -- Build your own UI. Click [here](../../custom-ui/init/frontend) to learn more. -::: - -Start by installing the SuperTokens ReactJS SDK and React: +Start by installing the SuperTokens Web SDK: ```bash -npm i -s supertokens-auth-react +npm i -s supertokens-web-js ``` -:::important -SuperTokens does not provide Angular components for pre built UI, but, there are two ways of implementing SuperTokens in your Angular frontend: -- Load SuperTokens's pre-built React UI components in your Angular app. Continue following the guide for this flow. -- Build your own UI. Click [here](../../custom-ui/init/frontend) to learn more. -::: -Start by installing the SuperTokens ReactJS SDK and React: +Start by installing the SuperTokens Web SDK: ```bash -npm i -s supertokens-auth-react supertokens-web-js +npm i -s supertokens-web-js ``` -:::important -SuperTokens does not provide Angular components for pre built UI, but, there are two ways of implementing SuperTokens in your Angular frontend: -- Load SuperTokens's pre-built React UI components in your Angular app. Continue following the guide for this flow. -- Build your own UI. Click [here](../../custom-ui/init/frontend) to learn more. -::: -Start by installing the SuperTokens ReactJS SDK and React: +Start by installing the SuperTokens Web SDK: ```bash -yarn add supertokens-auth-react supertokens-web-js +yarn add supertokens-web-js ``` -You will also need to update `compilerOptions` in your `tsconfig.json` file with the following: - -```json title="tsconfig.json" -"jsx": "react", -"allowSyntheticDefaultImports": true, -``` - @@ -132,46 +110,30 @@ You will also need to update `compilerOptions` in your `tsconfig.json` file with -:::important -SuperTokens does not provide Vue components for pre built UI, but, there are two ways of implementing SuperTokens in your Vue frontend: -- Load SuperTokens's pre-built React UI components in your Vue app. Continue following the guide for this flow. -- Build your own UI. Click [here](../../custom-ui/init/frontend) to learn more. -::: - -Start by installing the SuperTokens ReactJS SDK and React: +Start by installing the SuperTokens web SDK: ```bash -npm i -s supertokens-auth-react +npm i -s supertokens-web-js ``` -:::important -SuperTokens does not provide Vue components for pre built UI, but, there are two ways of implementing SuperTokens in your Vue frontend: -- Load SuperTokens's pre-built React UI components in your Vue app. Continue following the guide for this flow. -- Build your own UI. Click [here](../../custom-ui/init/frontend) to learn more. -::: -Start by installing the SuperTokens ReactJS SDK and React: +Start by installing the SuperTokens web SDK: ```bash -npm i -s supertokens-auth-react supertokens-web-js +npm i -s supertokens-web-js ``` -:::important -SuperTokens does not provide Vue components for pre built UI, but, there are two ways of implementing SuperTokens in your Vue frontend: -- Load SuperTokens's pre-built React UI components in your Vue app. Continue following the guide for this flow. -- Build your own UI. Click [here](../../custom-ui/init/frontend) to learn more. -::: -Start by installing the SuperTokens ReactJS SDK and React: +Start by installing the SuperTokens web SDK: ```bash -yarn add supertokens-auth-react supertokens-web-js +yarn add supertokens-web-js ``` @@ -283,14 +245,16 @@ SuperTokens.init({ askForAPIDomain askForWebsiteDomain> + + -Before we initialize the `supertokens-auth-react` SDK let's see how we will use it in our Angular app +Before we initialize the `supertokens-web-js` SDK let's see how we will use it in our Angular app **Architecture** -- The `supertokens-auth-react` SDK is responsible for rendering the login UI, handling authentication flows and session management. -- Using `supertokens-auth-react`'s pre-built UI does not increase application's bundle size. React is only added to authentication-related routes. +- The `supertokens-web-js` SDK is responsible for session management and providing helper functions to check if a session exists, or validate the access token claims on the frontend (for example, to check for user roles before showing some UI). We will initialise this SDK on the root of your Angular app, so that all pages in your app can use it. +- We will create a `^{form_websiteBasePath}*` route in the Angular app which will render our pre built UI which will also need to be initialised, but only on that route. **Creating the `^{form_websiteBasePath}` route** @@ -300,109 +264,99 @@ Before we initialize the `supertokens-auth-react` SDK let's see how we will use ng generate module auth --route auth --module app.module ``` -- In your `auth` component folder create a react component `supertokensAuthComponent.tsx`. This component will be used to render appropriate UI when user visits the login page. - - ```tsx title="/app/auth/supertokensAuthComponent.tsx" - import * as React from "react"; - import * as SuperTokens from "supertokens-auth-react"; - import { canHandleRoute, getRoutingComponent } from "supertokens-auth-react/ui"; - ^{prebuiltuiimport} - - // highlight-start - class SuperTokensReactComponent extends React.Component { - override render() { - if (canHandleRoute([^{recipePreBuiltUINameCapitalLetters}])) { - return getRoutingComponent([^{recipePreBuiltUINameCapitalLetters}]); - } - return "Route not found"; - } - } - // highlight-end - - export default SuperTokensReactComponent; - ``` - -- Load `superTokensAuthComponent` in the `auth` angular component +- Add the following code to your `auth` angular component ```tsx title="/app/auth/auth.component.ts" - import { AfterViewInit, Component, OnDestroy } from "@angular/core"; - import * as React from "react"; - import * as ReactDOM from "react-dom"; - // @ts-ignore - import SuperTokensReactComponent from "./supertokensAuthComponent.tsx"; + import {init as supertokensUIInit} from "supertokens-auth-react-script"; + import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless"; + import supertokensUIThirdParty from "supertokens-auth-react-script/recipe/thirdparty"; + import supertokensUISession from "supertokens-auth-react-script/recipe/session"; + import { Component, OnDestroy, AfterViewInit, Renderer2, Inject } from "@angular/core"; + import { DOCUMENT } from "@angular/common"; @Component({ selector: "app-auth", - template: '
', + template: '
', }) - export class AuthComponent implements AfterViewInit, OnDestroy { - title = "angularreactapp"; + export class AuthComponent implements OnDestroy, AfterViewInit { - public rootId = "rootId"; + constructor( + private renderer: Renderer2, + @Inject(DOCUMENT) private document: Document + ) { } - // highlight-start - // We use the ngAfterViewInit lifecycle hook to render the React component after the Angular component view gets initialized ngAfterViewInit() { - ReactDOM.render(React.createElement(SuperTokensReactComponent), document.getElementById(this.rootId)); + this.loadScript('^{jsdeliver_prebuiltui}'); } - // We use the ngOnDestroy lifecycle hook to unmount the React component when the Angular wrapper component is destroyed. ngOnDestroy() { - ReactDOM.unmountComponentAtNode(document.getElementById(this.rootId) as Element); + // Remove the script when the component is destroyed + const script = this.document.getElementById('supertokens-script'); + if (script) { + script.remove(); + } + } + + private loadScript(src: string) { + const script = this.renderer.createElement('script'); + script.type = 'text/javascript'; + script.src = src; + script.id = 'supertokens-script'; + script.onload = () => { + supertokensUIInit({ + appInfo: { + appName: "^{form_appName}", + apiDomain: "^{form_apiDomain}", + websiteDomain: "^{form_websiteDomain}", + apiBasePath: "^{form_apiBasePath}", + websiteBasePath: "^{form_websiteBasePath}" + }, + recipeList: [ + supertokensUIPasswordless.init({ + contactMethod: "^{form_contactMethod}" + }), + supertokensUIThirdParty.init({ + signInAndUpFeature: { + providers: [ + supertokensUIThirdParty.Github.init(), + supertokensUIThirdParty.Google.init(), + supertokensUIThirdParty.Facebook.init(), + supertokensUIThirdParty.Apple.init(), + ] + } + }), + supertokensUISession.init(), + ], + }); + } + this.renderer.appendChild(this.document.body, script); } - // highlight-end } ``` + - In the `loadScript` function, we provide the SuperTokens config for the UI. We add the passwordless, session and social login recipes along with Github, Google, Facebook and Apple login buttons. -- Initialize the `supertokens-auth-react` SDK in your angular app's root component. This will provide session management across your entire application. - - ```tsx title="/app/app.component.ts " - import { Component } from "@angular/core"; +- Initialize the `supertokens-web-js` SDK in your angular app's root component. This will provide session management across your entire application. - import * as SuperTokens from "supertokens-auth-react"; - import Passwordless from "supertokens-auth-react/recipe/passwordless"; - import ThirdParty, { Github, Google, Facebook, Apple } from "supertokens-auth-react/recipe/thirdparty"; - import * as Session from "supertokens-auth-react/recipe/session"; - - SuperTokens.init({ - // highlight-start + ```tsx title="/app/app.component.ts " + import SuperTokens from "supertokens-web-js"; + import Session from "supertokens-web-js/recipe/session"; + + SuperTokens.init({ appInfo: { appName: "^{form_appName}", apiDomain: "^{form_apiDomain}", - websiteDomain: "^{form_websiteDomain}", apiBasePath: "^{form_apiBasePath}", - websiteBasePath: "^{form_websiteBasePath}" }, recipeList: [ - Passwordless.init({ - contactMethod: "^{form_contactMethod}", - }), - ThirdParty.init({ - signInAndUpFeature: { - providers: [ - Github.init(), - Google.init(), - Facebook.init(), - Apple.init(), - ], - }, - }), Session.init(), ], - // highlight-end }); - - @Component({ - selector: "app-root", - template: "", - }) - export class AppComponent { - title = "^{form_appName}"; - } ``` + + @@ -414,103 +368,105 @@ Before we initialize the `supertokens-auth-react` SDK let's see how we will use askForAPIDomain askForWebsiteDomain> + + -Before we initialize the `supertokens-auth-react` SDK let's see how we will use it in our Vue app +Before we initialize the `supertokens-web-js` SDK let's see how we will use it in our Vue app **Architecture** -- The `supertokens-auth-react` SDK is responsible for rendering the login UI, handling authentication flows and session management. -- Using `supertokens-auth-react`'s pre-built UI does not increase application's bundle size. React is only added to authentication-related routes. +- The `supertokens-web-js` SDK is responsible for session management and providing helper functions to check if a session exists, or validate the access token claims on the frontend (for example, to check for user roles before showing some UI). We will initialise this SDK on the root of your Vue app, so that all pages in your app can use it. +- We will create a `^{form_websiteBasePath}*` route in the Vue app which will render our pre built UI which will also need to be initialised, but only on that route. **Creating the `^{form_websiteBasePath}` route** -- Create a new file `AuthView.vue`, this Vue component will be used to render the auth component - -- Create a React component `Supertokens.tsx`. This component will be used to render appropriate UI when user visits the login page. - - ```tsx title="/components/Supertokens.tsx" - import * as SuperTokens from "supertokens-auth-react"; - import { canHandleRoute, getRoutingComponent } from "supertokens-auth-react/ui"; - ^{prebuiltuiimport} - - // highlight-start - function SuperTokensReactComponent(props: any) { - if (canHandleRoute([^{recipePreBuiltUINameCapitalLetters}])) { - return getRoutingComponent([^{recipePreBuiltUINameCapitalLetters}]); - } - return "Route not found"; - } - // highlight-end - - export default SuperTokensReactComponent; - ``` - -- Load `SuperTokensReactComponent` in the `AuthView.vue` component - - ```html title="/views/AuthView.vue" +- Create a new file `AuthView.vue`, this Vue component will be used to render the auth component: + ```tsx + import {init as supertokensUIInit} from "supertokens-auth-react-script"; + import supertokensUIPasswordless from "supertokens-auth-react-script/recipe/passwordless"; + import supertokensUIThirdParty from "supertokens-auth-react-script/recipe/thirdparty"; + import supertokensUISession from "supertokens-auth-react-script/recipe/session"; ``` + - In the `loadScript` function, we provide the SuperTokens config for the UI. We add the passwordless, session and social login recipes along with Github, Google, Facebook and Apple login buttons. -- Initialize the `supertokens-auth-react` SDK in your Vue app's `main.ts` file. This will provide session management across your entire application. +- Initialize the `supertokens-web-js` SDK in your Vue app's `main.ts` file. This will provide session management across your entire application. ```tsx title="/main.ts " // @ts-ignore import { createApp } from "vue"; - import * as SuperTokens from "supertokens-auth-react"; - import Passwordless from "supertokens-auth-react/recipe/passwordless"; - import ThirdParty, { Github, Google, Facebook, Apple } from "supertokens-auth-react/recipe/thirdparty"; - import Session from "supertokens-auth-react/recipe/session"; - + import SuperTokens from "supertokens-web-js"; + import Session from "supertokens-web-js/recipe/session"; // @ts-ignore import App from "./App.vue"; // @ts-ignore import router from "./router"; SuperTokens.init({ - // highlight-start appInfo: { appName: "^{form_appName}", apiDomain: "^{form_apiDomain}", - websiteDomain: "^{form_websiteDomain}", apiBasePath: "^{form_apiBasePath}", - websiteBasePath: "^{form_websiteBasePath}" }, recipeList: [ - Passwordless.init({ - contactMethod: "^{form_contactMethod}", - }), - ThirdParty.init({ - signInAndUpFeature: { - providers: [ - Github.init(), - Google.init(), - Facebook.init(), - Apple.init(), - ], - }, - }), Session.init(), ], - // highlight-end }); const app = createApp(App); @@ -518,9 +474,11 @@ Before we initialize the `supertokens-auth-react` SDK let's see how we will use app.use(router); app.mount("#app"); + ``` + @@ -710,6 +668,8 @@ Update your Vue router so that all auth related requests load the `AuthView` com import { createRouter, createWebHistory } from "vue-router"; // @ts-ignore import HomeView from "../views/HomeView.vue"; +// @ts-ignore +import AuthView from "../views/AuthView.vue"; const router = createRouter({ // @ts-ignore @@ -723,8 +683,7 @@ const router = createRouter({ { path: "^{form_websiteBasePath}/:pathMatch(.*)*", name: "auth", - // @ts-ignore - component: () => import("../views/AuthView.vue"), + component: AuthView, }, ], }); diff --git a/v2/thirdpartypasswordless/pre-built-ui/sign-out.mdx b/v2/thirdpartypasswordless/pre-built-ui/sign-out.mdx index 8b25a1f07..799748faa 100644 --- a/v2/thirdpartypasswordless/pre-built-ui/sign-out.mdx +++ b/v2/thirdpartypasswordless/pre-built-ui/sign-out.mdx @@ -42,11 +42,11 @@ function NavBar() { -The [`signOut` method](https://supertokens.com/docs/auth-react/modules/recipe_session.html#signOut-1) revokes the session for the user. +The [`signOut` method](https://supertokens.com/docs/web-js/modules/recipe_session.html#signOut-1) revokes the session for the user. ```tsx // highlight-next-line -import Session from "supertokens-auth-react/recipe/session"; +import Session from "supertokens-web-js/recipe/session"; async function logout () { // highlight-next-line diff --git a/v2/thirdpartypasswordless/troubleshooting/how-to-troubleshoot.mdx b/v2/thirdpartypasswordless/troubleshooting/how-to-troubleshoot.mdx index 41507a865..901aaa4d7 100644 --- a/v2/thirdpartypasswordless/troubleshooting/how-to-troubleshoot.mdx +++ b/v2/thirdpartypasswordless/troubleshooting/how-to-troubleshoot.mdx @@ -132,6 +132,45 @@ SuperTokens.init({ + + +You will have to make changes to the auth route config, as well as to the `supertokens-web-js` SDK config at the root of your application: + +```tsx +// this goes in the auth route config of your frontend app (once the pre built UI script has been loaded) +import {init as supertokensUIInit} from "supertokens-auth-react-script"; + +supertokensUIInit({ + // highlight-next-line + enableDebugLogs: true, + // @ts-ignore + appInfo: { /*...*/ }, + // @ts-ignore + recipeList: [/*...*/] +}); +``` + +This change goes in the `supertokens-web-js` SDK config at the root of your application: + +```tsx +import SuperTokens from 'supertokens-web-js'; +import Session from 'supertokens-web-js/recipe/session'; + +SuperTokens.init({ + appInfo: { + apiDomain: "...", + appName: "...", + }, + recipeList: [ + Session.init(), + ], + // highlight-next-line + enableDebugLogs: true, +}); +``` + + + diff --git a/v2/thirdpartypasswordless/user-roles/protecting-routes.mdx b/v2/thirdpartypasswordless/user-roles/protecting-routes.mdx index b3ea9478d..58c95e15f 100644 --- a/v2/thirdpartypasswordless/user-roles/protecting-routes.mdx +++ b/v2/thirdpartypasswordless/user-roles/protecting-routes.mdx @@ -1224,8 +1224,8 @@ function ProtectedComponent() { ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { @@ -1268,8 +1268,8 @@ async function shouldLoadRoute(): Promise { If you want to have more complex access control, you can get the roles list from the session as follows, and check the list yourself: ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { diff --git a/v2/userroles/protecting-routes.mdx b/v2/userroles/protecting-routes.mdx index 6ab9d6cfe..b6e6e149f 100644 --- a/v2/userroles/protecting-routes.mdx +++ b/v2/userroles/protecting-routes.mdx @@ -1224,8 +1224,8 @@ function ProtectedComponent() { ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim, /*PermissionClaim*/ } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) { @@ -1268,8 +1268,8 @@ async function shouldLoadRoute(): Promise { If you want to have more complex access control, you can get the roles list from the session as follows, and check the list yourself: ```tsx -import Session from "supertokens-auth-react/recipe/session"; -import { UserRoleClaim } from "supertokens-auth-react/recipe/userroles"; +import Session from "supertokens-web-js/recipe/session"; +import { UserRoleClaim } from "supertokens-web-js/recipe/userroles"; async function shouldLoadRoute(): Promise { if (await Session.doesSessionExist()) {