getServerData Support

[graysonhicks]

First, this plugin is great! Probably the most seamless auth experience I've had in a while.

I'm looking to add support for SSR auth with Gatsby. Since Gatsby 4 in October 2021, Gatsby has supported SSR rendering pages outside of SSG. The pattern is similar to Next.js, but has a few differences. I have found that using the withServerSideAuth function basically works with Gatsby, but I'm not sure it's working as well as it could.

First Gatsby relies on exporting an async function called getServerData. That makes following the HOC pattern difficult. When trying to copy and paste the example directly, the context will be undefined inside withServerSideAuth:

export const getServerData = withServerSideAuth(({ req, resolvedUrl }) => {
  const { sessionId } = req.auth

  if (!sessionId) {
    return { redirect: { destination: '/sign-in?redirect_url=' + resolvedUrl } }
  }

  return { props: {} }
})

The Gatsby pattern looks more like this:

export async function getServerData(context) {
  try {
    withServerSideAuth(context)

    return {
      status: 200, 
      props: {
        test: 'foo',
      },
      headers: {},
    }
  } catch (err) {
    console.log(err)
    return {
      status: 500,
      headers: {},
      props: {},
    }
  }
}

With this pattern, the auth actually seems to work (it redirects to the auth url from Clerk), so I assume the Node logic from the Clerk library is working. When logged in, it successfully renders the page. But note that there is no callback to get the sessionId or resolvedUrl.

My guess is that this plugin could have an ssr folder that tweaks this same logic slightly and allows for SSR auth with Gatsby as well. Something like this:

import { serverSideAuth } from 'gatsby-plugin-clerk'

// ... components

export async function getServerData(context) {
  try {
    const auth = await serverSideAuth(context)

  const { sessionId } = auth.req;

  if (!sessionId) {
    return { redirect: { destination: "/sign-in?redirect_url=" + resolvedUrl } };
  }


    return {
      status: 200, 
      props: {
        test: 'foo',
      },
      headers: {},
    }
  } catch (err) {
    console.log(err)
    return {
      status: 500,
      headers: {},
      props: {},
    }
  }
}

Or the callback could be passed in to serverSideAuth as well. Either way, I think the existing Next.js pattern is already very, very close to what would work here, with maybe additional tweaks to sanitizing/serializing props that might not be needed.

Happy to help with this, thanks!

[nikosdouvlis]

Hello @graysonhicks 👋🏻

Great to hear that you liked the auth experience, even if this plugin is mainly focused on CSR until now :) Happy to say that updating this plugin to fully leverage the SSR capabilities of Clerk v3 that was released two weeks ago was on our roadmap already; the actual implementation would be starting next week.

I think you're correct; the final solution could look very similar to @clerk/nextjs, but I'd like to explore how we can handle the "interstitial" page. When we detect that a JWT is expired (among other edge cases), we use this interstitial page to refresh the JWT and then reload the page. In the @clerk/nextjs to ensure no user logic runs before we get a fresh JWT, the interstitial page is thrown by middleware (withServerSideAuth or withAuth in _middleware functions) before the application does any processing. (Please note that we have plans to replace this logic soon.)

It'd be great if you could give me a couple of days to run some tests internally and get back to you once I can share more details about the above.

We always aim to provide the best possible DX, so could you please share the kind of public API (HOC vs. callback, and possible naming) you think would feel more natural to a Gatsby user? I believe you are just the right person to ask :)

Gatsby is fantastic and we're more than happy to work on this plugin again

[graysonhicks]

@nikosdouvlis Awesome to hear! I'm going to share this with the OSS team and will get you some feedback.

[graysonhicks]

I think a minimal gatsby site using the Clerk plugin would be a good first step. Maybe this could be a good place to do that on a branch. That would make npm link easy to use for testing. @pieh

[nikosdouvlis]

Hello again!

I just wanted to let you know that we'll be moving gatsby-plugin-clerk into our clerkinc/javascript monorepo; the previous repo will be deprecated in favor of the new package. We already have a PR open, but please note that it's still a work-in-progress.

For gatsby-plugin-clerk v3, we have these basic requirements:

1. The plugin should feel like a Gatsby plugin. It should follow the same naming and config conventions anyone using Gatsby is already used to.
2. The final API should be close to the Clerk rootAuthLoader (Remix) and withServerSideAuth (Nextjs) SSR helpers.
3. The final solution should be SSR/CSR agnostic. Clerk should gracefully handle the absence of the initial SSR state during the client-side hydration phase; if withServerAuth is not used, Clerk should automatically function as a CSR-only library.
4. Following the last point (3), Clerk should support SSR on a per-page basis.

We still have to iron out some last details, but the proposed API looks like this:

Plugin name:

gatsby-clerk-plugin (no change)

Clerk configuration:

• A key-value object in gatsby-config.tsx, as usual for Gatsby plugins, expecting at least a frontendApi key with a string value.
• A CLERK_API_KEY env variable (used by @clerk/clerk-sdk-node).

Clerk SSR helper:

• We will introduce a withSeverAuth higher-order function, matching the getServerData function Gatsby expects.
• withSeverAuth can accept a user-defined callback. The passed props object will be decorated with the Clerk auth object and typed accordingly.
• withSeverAuth can also accept an optional options object. If loadUser is passed and is set to true, props will also have a user object.
• Similarly, if loadSession is passed and is set to true, props will also have a session object.
• withSeverAuth will inject the auth state to the callbacks returned value and become available through our hooks both during SSR and CSR.

Example:

// 1. Read userId, sessionId, getToken from `auth`
export const getServerData: GetServerData = withServerAuth(async ({ auth }) => {
  const { userId, sessionId, getToken } = auth;
  const posts = userId ? await db.getPostsByUserId(userId) : [];
  return { props: { posts } };
});

// 2. Get access to the whole `user` object
export const getServerData: GetServerData = withServerAuth(async ({ auth, user }) => {
  const { userId, sessionId, getToken } = auth;
  const data = user ? await serviceThatNeedsAnEmailAddress(user.emailAddresses[0].EmailAddress) : null;
  return { props: { data } };
}, { loadUser: true });

// 3. Access Clerk state from the page component
const IndexPage = ({ serverData }) => {
  // auth state
  const { userId, sessionId, getToken } = useAuth();
  const { user } = useUser();
  // other data fetched during SSR
  const { posts } = serverData;

  return <div>...</div>;
};

I have to say, building Gatsby plugins is fun. I'd love to hear your thoughts on the API; any feedback is welcome :)

PS: I've also converted the original issue into a discussion and moved it to the clerkinc/javascript repo. I hope this won't confuse anyone.

[nikosdouvlis]

Following my last comment, I have a couple of questions I'd like to ask. The Gatsby plugin system is very flexible, so I want to make sure we're not missing something.

1. Making severData available to ClerkProvider

There are tons of ways to go about this. We used wrapPageElement in gatsby-browser and gatsby-ssr in our POC PR, which looks like the most straightforward approach. This method conveniently makes props.serverData available during SSR and CSR. I hoped that wrapRootElement would also provide access to severData, but unfortunately, it doesn't. If wrapRootElement gives access to serverData in the future we will use that, but for now, I cannot think of a scenario where this would cause issues with our ClerkProvider. Would you recommend a different approach?

2. Returning a redirect response from getServerData

In your example, you return a { redirect: { destination: ... } } object. I might be missing something, but the GetServerDataReturn type does not specify this form and I couldn't find a reference for it in the docs. It's probably a leftover from the Nextjs example you used, but it'd be great if we could trigger a redirect directly from getServerData. That would make protecting a page during SSR quite easy:

export const getServerData: GetServerData = withServerAuth(async ({ auth, user, url }) => {
  const { userId } = auth;

  if (!userId) {
    return { redirect: { destination: `/sign-in?redirect_url=${url}` } }
  }

  const data = await serviceThatNeedsAnEmailAddress(user.emailAddresses[0].EmailAddress);
  return { props: { data } };
}, { loadUser: true });

I'm also investigating an issue where the referer and host headers are different in any request made to a page that's using getServerData. After running gatsby develop the app is available on localhost:8000; I noticed that if I visit the index page at localhost:8000, the referer header is localhost:8000 but the host header is localhost:51234 (random port) inside the getServerData callback. I haven't figured out why this happens yet, so I'll share more details later :) I now understand that this is the developPort Gatsby is using in the entry file for the develop command.

Thank you!

[graysonhicks]

Hi @nikosdouvlis ! Thanks! Ran this discussion by the rest of the team. For 1, yes using wrapPageElement works for what you are doing with the Provider. For 2, yes I left that in by accident, but Gatsby does not currently support the same pattern, but we are looking in to it. For now, you could try return a Location header redirect.

Lastly, the API examples above look great. Let us know if you have more questions!

[nikosdouvlis]

Hello @graysonhicks ! Apologies for the late reply; most of the European team was celebrating Easter this week :) Great to hear that we're headed in the right direction!

We've released an early alpha version that adds support for getServerData. I'll be working on supporting the API routes early next week using the same withAuth/requireAuth from clerk/clerk-sdk-node:

const handler = withAuth((req: WithAuthProp<GatsbyFunctionRequest<ContactBody>>, res: GatsbyFunctionResponse) => {
  const { getToken, sessionId, userId } = req.auth;
  console.log({ getToken, sessionId, userId });
  res.send({ title: `I am TYPESCRIPT`, message: req.body.message });
});

// or by simplifying the types slightly:
const handler = withAuth<{requestBody: ContactBody}>((req, res) => {
  const { getToken, sessionId, userId } = req.auth;
  console.log({ getToken, sessionId, userId });
  res.send({ title: `I am TYPESCRIPT`, message: req.body.message });
});

Once API route support is ready and thoroughly tested the integration, we can release the first v3 stable version.

One issue we faced, and we still haven't solved is related to the internal proxy Gatsby uses when booted with the develop command. As we can see here, you're creating the internal proxy server using httpProxy, and you're setting changeOrigin to true, without adding any x-forward-* headers. That makes our SSR middleware always treat this request as a cross-origin one, since it expects to find at least an X-Forwarded-Host header as is usual with proxied requests.

An easy fix would be to add the forward headers on the proxied request, simply by setting xfwd to true in createProxyServer options (https://github.com/http-party/node-http-proxy#options). Happy to open a PR myself if that's something you're interested in changing :)

Really appreciate the help!

[graysonhicks]

Thanks @nikosdouvlis ! Do you have a link to a demo repo so far? Would love to be working with the same codebase as we test. Tagging @KyleAMathews for the proxy question and any implications there.