feat(console): add remix guide (#7384)

Author: wangsijie

packages/console/src/assets/docs/guides/index.tsx

@@ -38,6 +38,7 @@ import webOutline from './web-outline/index';
 import webPassport from './web-passport/index';
 import webPhp from './web-php/index';
 import webPython from './web-python/index';
+import webRemix from './web-remix';
 import webRuby from './web-ruby/index';
 import webSveltekit from './web-sveltekit/index';
 import webWordpress from './web-wordpress/index';
@@ -108,6 +109,14 @@ export const guides: Readonly<Guide[]> = Object.freeze([
     Component: safeLazy(async () => import('./web-sveltekit/README.mdx')),
     metadata: webSveltekit,
   },
+  {
+    order: 1.2,
+    id: 'web-remix',
+    Logo: safeLazy(async () => import('./web-remix/logo.svg?react')),
+    DarkLogo: safeLazy(async () => import('./web-remix/logo-dark.svg?react')),
+    Component: safeLazy(async () => import('./web-remix/README.mdx')),
+    metadata: webRemix,
+  },
   {
     order: 1.3,
     id: 'spa-vue',

packages/console/src/assets/docs/guides/web-remix/README.mdx

@@ -0,0 +1,157 @@
+import NpmLikeInstallation from '@/mdx-components/NpmLikeInstallation';
+import { generateStandardSecret } from '@logto/shared/universal';
+import Steps from '@/mdx-components/Steps';
+import Step from '@/mdx-components/Step';
+import Checkpoint from '../../fragments/_checkpoint.md';
+import RedirectUrisWeb, { defaultBaseUrl } from '../../fragments/_redirect-uris-web.mdx';
+
+<Steps>
+
+<Step
+  title="Installation"
+  subtitle="Install Logto SDK"
+>
+
+<NpmLikeInstallation packageName="@logto/remix" />
+
+</Step>
+
+<Step
+  title="Init LogtoClient"
+>
+
+Before initializing the SDK, we have to create a `SessionStorage` instance which takes care of the session persistence. In our case, we want to use a cookie-based session:
+
+<Code title="services/auth.server.ts" className="language-ts">
+    {`import { createCookieSessionStorage } from '@remix-run/node';
+import { makeLogtoRemix } from '@logto/remix';
+
+const sessionStorage = createCookieSessionStorage({
+  cookie: {
+    name: 'logto-session',
+    maxAge: 14 * 24 * 60 * 60,
+    secrets: '${generateStandardSecret()}', // Auto-generated 32 digit secret
+  },
+});
+
+export const logto = makeLogtoRemix(
+  {
+    endpoint: '${props.endpoint}',
+    appId: '${props.app.id}',
+    appSecret: '${props.secrets[0]?.value ?? props.app.secret}',
+    baseUrl: '${defaultBaseUrl}',  // Change to your own base URL
+  },
+  { sessionStorage }
+);`}
+</Code>
+
+</Step>
+
+<Step 
+  title="Configure redirect URIs"
+  subtitle="2 URIs"
+>
+
+<RedirectUrisWeb defaultRedirectUri={`${defaultBaseUrl}api/logto/callback`} />
+
+</Step>
+
+<Step title="Mounting authentication routes">
+
+The SDK ships with a convenient function that mounts the authentication routes: sign-in, sign-in callback and the sign-out route. Create a file `routes/api.logto.$action.ts`
+
+```ts title="routes/api.logto.$action.ts"
+import { logto } from '../services/auth.server';
+
+export const loader = logto.handleAuthRoutes({
+  'sign-in': {
+    path: '/api/logto/sign-in',
+    redirectBackTo: '/api/logto/callback',
+  },
+  'sign-in-callback': {
+    path: '/api/logto/callback',
+    redirectBackTo: '/',
+  },
+  'sign-out': {
+    path: '/api/logto/sign-out',
+    redirectBackTo: '/',
+  },
+  'sign-up': {
+    path: '/api/logto/sign-up',
+    redirectBackTo: '/api/logto/callback',
+  },
+});
+```
+
+As you can see, the mount process is configurable and you can adjust it for your particular route structure. The whole URL path structure can be customized via the passed configuration object.
+
+When mounting the routes as described above, you can navigate your browser to `/api/logto/sign-in` and you should be redirected to your Logto instance where you have to authenticate then.
+
+</Step>
+
+<Step
+  title="Implement sign-in and sign-out"
+>
+
+We have prepared the authentication routes, now let's implement the sign-in and sign-out buttons in your home page. We need to redirect the user to the sign-in or sign-out route when needed. To help with this, use `loader` to fetch authentication status from Logto client.
+
+```tsx title="/app/routes/_index.tsx"
+import { type LogtoContext } from '@logto/remix';
+import { type LoaderFunction } from '@remix-run/node';
+import { json, Link, useLoaderData } from '@remix-run/react';
+
+import { logto } from '../services/auth.server';
+
+type LoaderResponse = {
+  readonly context: LogtoContext;
+};
+
+export const loader: LoaderFunction = async ({ request }) => {
+  const context = await logto.getContext({ getAccessToken: false })(request);
+
+  return json<LoaderResponse>({ context });
+};
+
+const Home = () => {
+  const { context } = useLoaderData<LoaderResponse>();
+  const { isAuthenticated, claims } = context;
+
+  return (
+    <div>
+      <h1>Remix Sample</h1>
+      {isAuthenticated ? (
+        <div>
+          <p>Hello {claims?.email ?? claims?.name ?? claims?.sub}</p>
+          <form action="/api/logto/sign-out" method="get">
+            <button type="submit">Sign Out</button>
+          </form>
+          <p>
+            <Link to="/user-info">Example of fetching user info</Link>
+          </p>
+          <p>
+            <Link to="/access-token">Example of fetching access token</Link>
+          </p>
+        </div>
+      ) : (
+        <form action="/api/logto/sign-in" method="get">
+          <button type="submit">Sign In</button>
+        </form>
+      )}
+    </div>
+  );
+};
+
+export default Home;
+```
+
+</Step>
+
+<Step
+  title="Checkpoint: Test your application"
+>
+
+<Checkpoint />
+
+</Step>
+
+</Steps>

packages/console/src/assets/docs/guides/web-remix/config.json

@@ -0,0 +1,3 @@
+{
+  "order": 1.2
+}

packages/console/src/assets/docs/guides/web-remix/index.ts

@@ -0,0 +1,17 @@
+import { ApplicationType } from '@logto/schemas';
+
+import { type GuideMetadata } from '../types';
+
+const metadata: Readonly<GuideMetadata> = Object.freeze({
+  name: 'Remix',
+  description:
+    'Remix is a full stack web framework that lets you focus on the user interface and work back through web standards to deliver a fast, slick, and resilient user experience.',
+  target: ApplicationType.Traditional,
+  sample: {
+    repo: 'js',
+    path: 'packages/remix-sample',
+  },
+  fullGuide: 'remix',
+});
+
+export default metadata;