From 2e074efed7ae201022e39f1101e6a29f72382871 Mon Sep 17 00:00:00 2001 From: Gao Sun Date: Wed, 26 Jun 2024 18:59:37 +0800 Subject: [PATCH 1/2] refactor: update nuxt guide --- packages/console/package.json | 1 + packages/console/parcel-transformer-mdx2.js | 2 + .../docs/fragments/_sign_in_explanation.md | 20 ++++++ .../assets/docs/guides/web-nuxt/README.mdx | 57 ++++++--------- .../CodeEditor/index.module.scss | 7 ++ .../src/ds-components/CodeEditor/index.tsx | 3 + .../console/src/mdx-components/Code/index.tsx | 3 +- .../src/mdx-components/Steps/index.tsx | 7 +- pnpm-lock.yaml | 70 +++++++++++++++++-- 9 files changed, 125 insertions(+), 45 deletions(-) create mode 100644 packages/console/src/assets/docs/fragments/_sign_in_explanation.md diff --git a/packages/console/package.json b/packages/console/package.json index ca2e8b90525..40f98746c29 100644 --- a/packages/console/package.json +++ b/packages/console/package.json @@ -117,6 +117,7 @@ "react-syntax-highlighter": "^15.5.0", "react-timer-hook": "^3.0.5", "recharts": "^2.1.13", + "rehype-mdx-code-props": "^3.0.1", "remark-gfm": "^4.0.0", "stylelint": "^15.0.0", "swr": "^2.2.0", diff --git a/packages/console/parcel-transformer-mdx2.js b/packages/console/parcel-transformer-mdx2.js index 367247041c7..060d299da63 100644 --- a/packages/console/parcel-transformer-mdx2.js +++ b/packages/console/parcel-transformer-mdx2.js @@ -3,6 +3,7 @@ import { compile } from '@mdx-js/mdx'; import { default as ThrowableDiagnostic } from '@parcel/diagnostic'; import { Transformer } from '@parcel/plugin'; +import rehypeMdxCodeProps from 'rehype-mdx-code-props'; export default new Transformer({ async transform({ asset }) { @@ -15,6 +16,7 @@ export default new Transformer({ development: true, jsx: true, providerImportSource: '@mdx-js/react', + rehypePlugins: [[rehypeMdxCodeProps, { tagName: 'code' }]], }); } catch (error) { const { start, end } = error.position; diff --git a/packages/console/src/assets/docs/fragments/_sign_in_explanation.md b/packages/console/src/assets/docs/fragments/_sign_in_explanation.md new file mode 100644 index 00000000000..81d9f642e97 --- /dev/null +++ b/packages/console/src/assets/docs/fragments/_sign_in_explanation.md @@ -0,0 +1,20 @@ +Before we dive into the details, here's a quick overview of the end-user experience. The sign-in process can be simplified as follows: + +```mermaid +graph LR + A(Your app) -->|1. Invoke sign-in| B(Logto) + B -->|2. Finish sign-in| A +``` + +1. Your app invokes the sign-in method. +2. The user is redirected to the Logto sign-in page. For native apps, the system browser is opened. +3. The user signs in and is redirected back to your app (configured as the redirect URI). + +Regarding redirect-based sign-in: + +1. This authentication process follows the [OpenID Connect (OIDC)](https://openid.net/specs/openid-connect-core-1_0.html) protocol, and Logto enforces the Authorization Code Flow with PKCE to ensure the security of the authentication process. +2. If you have multiple apps, you can use the same authentication server (Logto), and the user only needs to sign in once. + +To learn more about the rationale and benefits of redirect-based sign-in, see [Logto sign-in experience explained](https://docs.logto.io/docs/tutorials/get-started/sign-in-experience). + +--- diff --git a/packages/console/src/assets/docs/guides/web-nuxt/README.mdx b/packages/console/src/assets/docs/guides/web-nuxt/README.mdx index d4bf7ef8ece..13d70bebe28 100644 --- a/packages/console/src/assets/docs/guides/web-nuxt/README.mdx +++ b/packages/console/src/assets/docs/guides/web-nuxt/README.mdx @@ -5,20 +5,22 @@ import InlineNotification from '@/ds-components/InlineNotification'; import Steps from '@/mdx-components/Steps'; import Step from '@/mdx-components/Step'; import Checkpoint from '../../fragments/_checkpoint.md'; +import SignInExplanation from '../../fragments/_sign_in_explanation.md'; import { generateStandardSecret } from '@logto/shared/universal'; export const cookieEncryptionKey = generateStandardSecret(); - - Logto Nuxt SDK only works with Nuxt 3. - - + + + Logto Nuxt SDK only works with Nuxt 3. + + @@ -46,18 +48,9 @@ pnpm add @logto/nuxt -In your Nuxt config file (`nuxt.config.ts`), add the Logto module: +In your Nuxt config file, add the Logto module and configure it: -```ts -export default defineNuxtConfig({ - modules: ['@logto/nuxt'], - // ...other configurations -}); -``` - -The minimal configuration for the module is as follows: - - + {`export default defineNuxtConfig({ modules: ['@logto/nuxt'], runtimeConfig: { @@ -74,7 +67,7 @@ The minimal configuration for the module is as follows: Since these information are sensitive, it's recommended to use environment variables (`.env`): - + {`NUXT_LOGTO_ENDPOINT=${props.endpoint} NUXT_LOGTO_APP_ID=${props.app.id} NUXT_LOGTO_APP_SECRET=${props.app.secret} @@ -88,15 +81,17 @@ See [runtime config](https://nuxt.com/docs/guide/going-further/runtime-config) f + + In the following steps, we assume your app is running on http://localhost:3000. -First, let's enter your redirect URI. E.g. `http://localhost:3000/callback`. [Redirect URI](https://www.oauth.com/oauth2-servers/redirect-uris/) is an OAuth 2.0 concept which implies the location should redirect after authentication. +Now, let's enter your redirect URI. E.g. `http://localhost:3000/callback`. -After signing out, it'll be great to redirect user back to your website. For example, add `http://localhost:3000` as the post sign-out redirect URI below. +Just like signing in, users should be redirected to Logto for signing out of the shared session. Once finished, it would be great to redirect the user back to your website. For example, add `http://localhost:3000` as the post sign-out redirect URI below. @@ -107,7 +102,7 @@ When registering `@logto/nuxt` module, it will do the following: These routes are configurable via `logto.pathnames` in the module options, for example: -```ts +```ts title="nuxt.config.ts" export default defineNuxtConfig({ logto: { pathnames: { @@ -122,32 +117,24 @@ export default defineNuxtConfig({ Check out the [type definition file](https://github.com/logto-io/js/blob/HEAD/packages/nuxt/src/runtime/utils/types.ts) in the `@logto/nuxt` package for more information. -Note: If you configure the callback route to a different path, you need to update the redirect URI in Logto accordingly. + +If you configure the callback route to a different path, you need to update the redirect URI in Logto accordingly. + -Since Nuxt pages will be hydrated and become a single-page application (SPA) after the initial load, we need to redirect the user to the sign-in or sign-out route when needed. - -```html -Sign in -
-Sign out -``` - - - - - -To display the user's information, you can use the `useLogtoUser()` composable, which is available on both server and client side: +Since Nuxt pages will be hydrated and become a single-page application (SPA) after the initial load, we need to redirect the user to the sign-in or sign-out route when needed. To help with this, our SDK provides the `useLogtoUser()` composable, which can be used in both server and client side. -```html +```html title="index.vue"