WIP: Add live page to swingset

.changeset/swingset-live-sandbox.md

@@ -0,0 +1,2 @@
+---
+---

.cursorignore

@@ -5,6 +5,7 @@
 # Environment files
 .env
 .env.*
+!.env.example
 
 # Secrets directory
 secrets/

eslint.config.mjs

@@ -662,6 +662,18 @@ export default tseslint.config([
       ],
     },
   },
+  {
+    name: 'packages/swingset',
+    files: ['packages/swingset/src/**/*'],
+    rules: {
+      'turbo/no-undeclared-env-vars': [
+        'error',
+        {
+          allowList: ['SWINGSET_DASHBOARD_URL'],
+        },
+      ],
+    },
+  },
   {
     name: 'packages/upgrade',
     files: ['packages/upgrade/src/**/*'],

packages/swingset/.env.example

@@ -0,0 +1,6 @@
+# Copy to packages/swingset/.env.local and restart Swingset (`pnpm dev:swingset`).
+# Required for /live, /sign-in, and /sign-up. The component explorer works without it.
+NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=
+
+# Optional. Enables the Clerk handshake for SSO / OAuth on /sign-in and /sign-up.
+CLERK_SECRET_KEY=

packages/swingset/next.config.mjs

@@ -1,12 +1,14 @@
 import createMDX from '@next/mdx';
 import stylexPlugin from '@stylexjs/unplugin/webpack';
-import { resolve } from 'path';
+import { createRequire } from 'module';
+import { dirname, resolve } from 'path';
 import rehypeRaw from 'rehype-raw';
 import remarkGfm from 'remark-gfm';
 import { fileURLToPath } from 'url';
 
 import { mosaicLightningCssTargets } from '../ui/stylex-lightningcss.config.mjs';
 
+const require = createRequire(import.meta.url);
 const __dirname = fileURLToPath(new URL('.', import.meta.url));
 
 const withMDX = createMDX({
@@ -98,6 +100,9 @@ const nextConfig = {
     config.resolve.alias['@clerk/headless/hooks'] = resolve(__dirname, '../headless/src/hooks');
     config.resolve.alias['@clerk/headless/utils'] = resolve(__dirname, '../headless/src/utils');
     config.resolve.alias['@clerk/headless'] = resolve(__dirname, '../headless/src/primitives');
+    // Mosaic/headless source imports this. Webpack resolves from the aliased file's
+    // directory, which is outside swingset, so the package has to be named here.
+    config.resolve.alias['@floating-ui/react'] = dirname(require.resolve('@floating-ui/react/package.json'));
     return config;
   },
 };

packages/swingset/package.json

@@ -12,7 +12,10 @@
   "dependencies": {
     "@base-ui/react": "^1.5.0",
     "@clerk/headless": "workspace:*",
+    "@clerk/nextjs": "workspace:*",
+    "@clerk/shared": "workspace:*",
     "@clerk/ui": "workspace:*",
+    "@floating-ui/react": "catalog:repo",
     "@stylexjs/stylex": "0.19.0",
     "@tailwindcss/typography": "^0.5.19",
     "class-variance-authority": "^0.7.1",

packages/swingset/src/app/(clerk)/layout.tsx

@@ -0,0 +1,66 @@
+import { ClerkProvider } from '@clerk/nextjs';
+import type { ReactNode } from 'react';
+
+import { Separator } from '@/components/ui/separator';
+import { SidebarInset, SidebarProvider, SidebarTrigger } from '@/components/ui/sidebar';
+
+import { LiveSidebar } from './live-sidebar';
+import { LiveUserButton } from './live-user-button';
+
+function LiveChrome({ children, userButton }: { children: ReactNode; userButton?: ReactNode }) {
+  return (
+    <SidebarProvider>
+      <LiveSidebar />
+      <SidebarInset>
+        <header className='bg-background sticky top-0 z-10 flex h-12 shrink-0 items-center gap-2 border-b px-4'>
+          <SidebarTrigger className='-ml-1' />
+          <Separator
+            orientation='vertical'
+            className='data-vertical:h-4 data-vertical:self-auto mr-2'
+          />
+          <span className='text-muted-foreground text-xs'>Live Sandbox</span>
+          <div className='ml-auto'>{userButton}</div>
+        </header>
+        {children}
+      </SidebarInset>
+    </SidebarProvider>
+  );
+}
+
+export default function ClerkLayout({ children }: { children: ReactNode }) {
+  const publishableKey = process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY;
+
+  if (!publishableKey) {
+    return (
+      <LiveChrome>
+        <div className='mx-auto flex w-full max-w-3xl flex-col gap-2 p-3 sm:p-8'>
+          <h1 className='text-xl font-semibold'>Live Sandbox</h1>
+          <p className='text-muted-foreground text-sm'>
+            To access sign-in, sign-up, and live pages, set up a publishable key.
+          </p>
+          <p className='text-muted-foreground text-sm'>
+            Copy <code className='font-mono text-xs'>packages/swingset/.env.example</code> to{' '}
+            <code className='font-mono text-xs'>packages/swingset/.env.local</code> and set{' '}
+            <code className='font-mono text-xs'>NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY</code>, then restart Swingset.
+          </p>
+          <p className='text-muted-foreground text-sm'>
+            <code className='font-mono text-xs'>CLERK_SECRET_KEY</code> is optional. Add it for SSO and OAuth redirects.
+          </p>
+        </div>
+      </LiveChrome>
+    );
+  }
+
+  return (
+    <ClerkProvider
+      publishableKey={publishableKey}
+      signInUrl='/sign-in'
+      signUpUrl='/sign-up'
+      signInFallbackRedirectUrl='/live'
+      signUpFallbackRedirectUrl='/live'
+      afterSignOutUrl='/live'
+    >
+      <LiveChrome userButton={<LiveUserButton />}>{children}</LiveChrome>
+    </ClerkProvider>
+  );
+}

packages/swingset/src/app/(clerk)/live-sidebar.tsx

@@ -0,0 +1,66 @@
+'use client';
+
+import { ArrowLeftIcon } from 'lucide-react';
+import Link from 'next/link';
+import { usePathname } from 'next/navigation';
+import type { ComponentProps } from 'react';
+
+import {
+  Sidebar,
+  SidebarContent,
+  SidebarGroup,
+  SidebarGroupContent,
+  SidebarGroupLabel,
+  SidebarHeader,
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  SidebarRail,
+} from '@/components/ui/sidebar';
+
+const flows = [{ title: 'Reverification', href: '/live/reverification' }];
+
+export function LiveSidebar(props: ComponentProps<typeof Sidebar>) {
+  const pathname = usePathname();
+
+  return (
+    <Sidebar {...props}>
+      <SidebarHeader className='flex h-12 flex-row items-center border-b px-2'>
+        <SidebarMenu>
+          <SidebarMenuItem>
+            <SidebarMenuButton
+              className='h-auto py-1 text-xs'
+              render={<Link href='/' />}
+            >
+              <ArrowLeftIcon className='size-3.5!' />
+              Back to components
+            </SidebarMenuButton>
+          </SidebarMenuItem>
+        </SidebarMenu>
+      </SidebarHeader>
+      <SidebarContent className='gap-0'>
+        <SidebarGroup className='py-1'>
+          <SidebarGroupLabel className='text-sidebar-foreground/50 h-auto px-2 pb-1 pt-3 text-[10px] font-semibold uppercase tracking-wider'>
+            Flows
+          </SidebarGroupLabel>
+          <SidebarGroupContent>
+            <SidebarMenu>
+              {flows.map(flow => (
+                <SidebarMenuItem key={flow.href}>
+                  <SidebarMenuButton
+                    className='h-auto py-1 text-xs'
+                    isActive={pathname.startsWith(flow.href)}
+                    render={<Link href={flow.href} />}
+                  >
+                    {flow.title}
+                  </SidebarMenuButton>
+                </SidebarMenuItem>
+              ))}
+            </SidebarMenu>
+          </SidebarGroupContent>
+        </SidebarGroup>
+      </SidebarContent>
+      <SidebarRail />
+    </Sidebar>
+  );
+}

packages/swingset/src/app/(clerk)/live-user-button.tsx

@@ -0,0 +1,12 @@
+'use client';
+
+import { MosaicProvider } from '@clerk/ui/mosaic/MosaicProvider';
+import { UserButton } from '@clerk/ui/mosaic/user-button/user-button';
+
+export function LiveUserButton() {
+  return (
+    <MosaicProvider>
+      <UserButton modePriority='user' />
+    </MosaicProvider>
+  );
+}

packages/swingset/src/app/(clerk)/live/live-overview.tsx

@@ -0,0 +1,111 @@
+'use client';
+
+import { useClerk, useUser } from '@clerk/nextjs';
+import type { EnvironmentResource } from '@clerk/shared/types';
+import { ExternalLinkIcon } from 'lucide-react';
+import Link from 'next/link';
+
+export function LiveOverview({
+  frontendApi,
+  instanceType,
+  hasSecretKey,
+  dashboardUrl,
+  deployment,
+}: {
+  frontendApi: string | null;
+  instanceType: string | null;
+  hasSecretKey: boolean;
+  dashboardUrl: string | null;
+  deployment: { label: string; dashboardUrl: string | null } | null;
+}) {
+  const clerk = useClerk();
+  const { isLoaded, isSignedIn, user } = useUser();
+  // The environment resource isn't part of the public Clerk interface; reach through the internal getter.
+  const environment = (clerk as unknown as { __internal_environment?: EnvironmentResource | null })
+    .__internal_environment;
+  const applicationName = environment?.displayConfig.applicationName;
+
+  return (
+    <div className='mx-auto flex w-full max-w-3xl flex-col gap-6 p-3 sm:p-8'>
+      <div className='flex flex-col gap-1'>
+        <h1 className='text-xl font-semibold'>Live Sandbox</h1>
+        <p className='text-muted-foreground text-sm'>
+          Flows in this sandbox run against the real Clerk application configured in{' '}
+          <code className='font-mono text-xs'>packages/swingset/.env.local</code>.
+        </p>
+      </div>
+
+      <section className='flex flex-col gap-2'>
+        <h2 className='text-sm font-medium'>Application</h2>
+        <dl className='grid grid-cols-[max-content_1fr] gap-x-6 gap-y-1.5 text-sm'>
+          <dt className='text-muted-foreground'>Name</dt>
+          <dd>
+            {!isLoaded ? (
+              'Loading…'
+            ) : dashboardUrl ? (
+              <a
+                href={dashboardUrl}
+                target='_blank'
+                rel='noreferrer'
+                className='text-foreground underline underline-offset-4'
+              >
+                {applicationName ?? 'Unknown'}
+                <ExternalLinkIcon className='ml-1 inline size-3 align-[-1px]' />
+              </a>
+            ) : (
+              (applicationName ?? 'Unknown')
+            )}
+          </dd>
+          <dt className='text-muted-foreground'>Frontend API</dt>
+          <dd className='font-mono text-xs leading-5'>{frontendApi ?? '—'}</dd>
+          <dt className='text-muted-foreground'>Instance</dt>
+          <dd>{instanceType ?? '—'}</dd>
+          <dt className='text-muted-foreground'>Deployment</dt>
+          <dd>
+            {!deployment ? (
+              '—'
+            ) : deployment.dashboardUrl ? (
+              <>
+                {deployment.label} —{' '}
+                <a
+                  href={deployment.dashboardUrl}
+                  target='_blank'
+                  rel='noreferrer'
+                  className='text-foreground underline underline-offset-4'
+                >
+                  {deployment.dashboardUrl.replace('https://', '')}
+                </a>
+              </>
+            ) : (
+              deployment.label
+            )}
+          </dd>
+          <dt className='text-muted-foreground'>Secret key</dt>
+          <dd>{hasSecretKey ? 'Set' : 'Not set (optional — needed for SSO and OAuth redirects)'}</dd>
+        </dl>
+      </section>
+
+      <section className='flex flex-col gap-2'>
+        <h2 className='text-sm font-medium'>Session</h2>
+        {!isLoaded ? (
+          <p className='text-muted-foreground text-sm'>Loading…</p>
+        ) : isSignedIn ? (
+          <p className='text-muted-foreground text-sm'>
+            Signed in as {user.primaryEmailAddress?.emailAddress ?? user.id}. Pick a flow from the sidebar.
+          </p>
+        ) : (
+          <p className='text-muted-foreground text-sm'>
+            You are signed out.{' '}
+            <Link
+              href='/sign-in'
+              className='text-foreground underline underline-offset-4'
+            >
+              Sign in
+            </Link>{' '}
+            to run the flows.
+          </p>
+        )}
+      </section>
+    </div>
+  );
+}

packages/swingset/src/app/(clerk)/live/page.tsx

@@ -0,0 +1,30 @@
+import { apiUrlFromPublishableKey } from '@clerk/shared/apiUrlFromPublishableKey';
+import { parsePublishableKey } from '@clerk/shared/keys';
+
+import { LiveOverview } from './live-overview';
+
+function deploymentFromKey(publishableKey: string): { label: string; dashboardUrl: string | null } {
+  switch (apiUrlFromPublishableKey(publishableKey)) {
+    case 'https://api.clerkstage.dev':
+      return { label: 'staging', dashboardUrl: 'https://dashboard.clerkstage.dev' };
+    case 'https://api.lclclerk.com':
+      return { label: 'local', dashboardUrl: null };
+    default:
+      return { label: 'production', dashboardUrl: 'https://dashboard.clerk.com' };
+  }
+}
+
+export default function LivePage() {
+  const publishableKey = process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY;
+  const key = parsePublishableKey(publishableKey);
+
+  return (
+    <LiveOverview
+      frontendApi={key?.frontendApi ?? null}
+      instanceType={key?.instanceType ?? null}
+      hasSecretKey={Boolean(process.env.CLERK_SECRET_KEY)}
+      dashboardUrl={process.env.SWINGSET_DASHBOARD_URL ?? null}
+      deployment={key && publishableKey ? deploymentFromKey(publishableKey) : null}
+    />
+  );
+}