Remix and React Router

Identify in a route and verify in an action with guardRequest.

10 minutes

This quickstart adds Trace to a Remix or React Router (framework mode) app. A provider and hook identify the visitor in the browser, and the route action verifies the event with your secret key.

Before you start

You need a running Trace server, a public key (pk_...) whose allowed origins include your site, and a secret key (sk_...) for the server. The quick start guide creates both.

  1. 1

    Install the SDKs

    npm install @trace-id/sdk-react @trace-id/sdk-node
    .env
    # .env
    TRACE_PUBLIC_KEY=pk_...
    TRACE_ENDPOINT=https://id.example.com
    TRACE_SECRET_KEY=sk_...
  2. 2

    Add the provider

    Pass the public values from a loader so the browser gets them. Nothing runs during server rendering; collection starts in the browser.

    TSX
    // app/root.tsx
    import { IdentifyProvider } from '@trace-id/sdk-react';
    import { Outlet, useLoaderData } from 'react-router'; // or '@remix-run/react'
    
    export function loader() {
      return { traceKey: process.env.TRACE_PUBLIC_KEY!, traceEndpoint: process.env.TRACE_ENDPOINT! };
    }
    
    export default function App() {
      const { traceKey, traceEndpoint } = useLoaderData<typeof loader>();
      return (
        <IdentifyProvider apiKey={traceKey} endpoint={traceEndpoint}>
          <Outlet />
        </IdentifyProvider>
      );
    }
  3. 3

    Identify on submit

    Identify first, then put the eventId into the form data you post.

    TSX
    // app/routes/signup.tsx
    import { useVisitorData } from '@trace-id/sdk-react';
    import { useFetcher } from 'react-router';
    
    export default function Signup() {
      const fetcher = useFetcher();
      const { getData, isLoading } = useVisitorData({ immediate: false });
    
      async function onSubmit(e: React.FormEvent<HTMLFormElement>) {
        e.preventDefault();
        const form = new FormData(e.currentTarget);
        const result = await getData({ tags: { action: 'signup' } }); // null if Trace is unavailable
        form.set('eventId', result?.eventId ?? '');
        fetcher.submit(form, { method: 'post' });
      }
    
      return (
        <fetcher.Form method="post" onSubmit={onSubmit}>
          <input name="email" type="email" required />
          <button disabled={isLoading || fetcher.state !== 'idle'}>Create account</button>
        </fetcher.Form>
      );
    }
  4. 4

    Verify in the action

    guardRequest reads the event id from the form body (or a header or JSON body), verifies it, and leaves the request body readable for formData().

    TypeScript
    // app/routes/signup.tsx
    import { guardRequest } from '@trace-id/sdk-node/web';
    
    export async function action({ request }: { request: Request }) {
      const guard = await guardRequest(request, {
        secretKey: process.env.TRACE_SECRET_KEY!,
        endpoint: process.env.TRACE_ENDPOINT!,
        failOpen: true,
        reject: (event) => event.suspectScore >= 60,
      });
      if (guard.response) return guard.response; // 400, 403, 503 or 500, with a JSON error body
    
      const form = await request.formData();
      // create the account for form.get('email'), and store guard.event?.visitorId with it
      return { ok: true };
    }

    Start in shadow mode

    For the first week, log event.suspectScore and event.reasons instead of blocking. Look at who would have been blocked, then pick thresholds you trust.

  5. 5

    Other backends

Next steps

Suggest an edit

Spotted something wrong or unclear? Tell us on GitHub and we will fix it.