Tanstack start

[robinsandborg]

Would you consider sharing an example of how to use the library with tanstack/start?

I know this is a SPA focused library, but if it's possible to use this with start across the client and server functions/middleware, that would be very interesting. I find the solutions offered in the tanstack docs to be too tied to Clerk.

[garronej]

Hello @robinsandborg,

Thank you for reaching out. Currently, the library is strictly designed for SPAs. There is a significant amount of work required to make it compatible with SSR. However, this is part of the roadmap.

[garronej]

Update

The major milestone on our roadmap, making the library truly provider-agnostic, is now complete!
Learn more here.

We'll now focus on supporting TanStack Start and Next.js, working on this with @ddecrulle.

[garronej]

We're making progresss

Screen.Recording.2025-03-23.at.09.56.25.mov

[robinsandborg]

Very cool to see!

[garronej]

We just need this to land: https://x.com/tannerlinsley/status/1892364303711281262

Once that's done, it’ll be possible to use loaders—including server loaders.
SSR already works; the only requirement is to wrap components using useOidc in a "no-SSR" boundary. Fortunately, these boundaries can be scoped deep in the tree, so it shouldn’t be a major compromise. We're working to make this as transparent as possible so users don't even have to think about it.

Also, when I check the HTML output from Vercel or Clerk’s dashboards before hydration, there’s not much—just the header and footer. In practice, I doubt most people will mind not having full-tree SSR as long as they can use server functions in loaders.

And when you compare what you gain—no DB setup, no session lifecycle to manage, no need for an __auth boundary—it’s just so much simpler operationally. I think it’s a clear win.

@robinsandborg One note about Clerk: there's currently a limitation that prevents using anything other than their SDK for client-side token exchange. I believe this is just a technical oversight though—I’ve been in touch with their CTO by email and they seem very willing to resolve it, he say he'll keep me up to date with the progress, kudos to them for their commitment to open standards.

[DaliborHomola]

I must say that this is a very ambitious project and I am glad that someone wants to unify multiple authentication providers and make it work for SSR Tanstack-Start. Thank you

[garronej]

This is the is the RFC to follow: TanStack/router#3394

[garronej]

@0-don I have two main issues with supporting Next.js:

• Maintenance burden: I've been burned multiple times implementing integration with Next. Supporting it reliably requires an absurd amount of ongoing maintenance. The framework changes constantly, and features often don’t behave as advertised, forcing OSS maintainers to implement brittle workarounds. Most users don’t realize how broken Next.js can be because the OSS ecosystem silently compensates for its shortcomings.

• Strategic misalignment: For a new library, investing in Next.js support doesn’t move the needle much, it’s already a saturated and mature ecosystem. On the other hand, TanStack Start is just emerging. If oidc-spa can become the go-to auth solution for TanStack Start by the time v1 ships, that’s a meaningful adoption opportunity.

If the library gains real traction, I’ll probably revisit Next.js support. But for now, it’s just not my priority.

[mwolf1989]

Hi,
Since tanstack start hit the RC level, are there any updates on this? Beside SSR - Is is possible to use oidc-spa in the client part?

[garronej]

I’ll revisit the integration this week to check if the last missing pieces are in place (support for server function).
I got a bit sidetracked working on the Angular integration, but my focus is shifting back to TanStack Start.

I also have a new idea, with Suspense and streaming, we might even get SSR working transparently. No promises yet, but I’ll experiment and see if it holds up in practice.

Is is possible to use oidc-spa in the client part?

It might be a painfull experience for you. If you want client only TanStack Start. This is TanStack Router in file based rooting mode and this is fully supported.

[garronej]

UPDATE: The latest relase candidate of TanStack Start now features what we where missing!
No more excuses!

[garronej]

Just a preview of what the src/oidc.ts file should look like:

import { oidcSpa } from "oidc-spa/tanstack-start/react";
import { z } from "zod";

export const { 
    bootstrapOidc, 
    useOidc, 
    getOidcAccessToken,
    getOidcFnMiddleware, 
    getOidcRequestMiddleware 
} = oidcSpa
    .withExpectedDecodedIdTokenShape({
        decodedIdTokenSchema: z.object({
            preferred_username: z.string(),
            realm_access: z.object({
                roles: z.array(z.string())
            })
        })
    })
    .withAccessTokenValidation({
        // Suitable for any auth provider that is configured to issue JWT as access_token.
        // Keycloak does it by default.
        type: "RFC 9068: JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens",
        decodedAccessTokenSchema: z.object({
            audience: z.string();
            sub: z.string(),
            realm_access: z.object({
                roles: z.array(z.string())
            })
        }),
        additionalValidation: ({ paramsOfBootstrap, accessTokenClaims }) => accessTokenClaims.audience === "account"
    })
    .finalize();
    /*

    OR when the auth provider is configured to issue an opaque access_token that requires
    calling a bespoke introspection endpoint to validate the access_token and get it's claim.

    .withAccessTokenValidation({ type: "clerk", ... })
    .withAccessTokenValidation({ type: "Auth0", ... })
    .withAccessTokenValidation({ type: "EntraID", ... })
    .withAccessTokenValidation({ type: "Google OAuth2" })

    // You can also implement your own validation/introspection to support arbitrary providers:  
    .withAccessTokenValidation<{ sub: string; }>({ type: "custom", createValidateAndGetAccessTokenClaims: ... })

    */

// Can be called here or wherever in the app
if (import.meta.env.USE_MOCK) {

    bootstrapOidc({
        isMock: true,
        mockDecodedIdToken: {
            preferred_username: "jhond",
            realm_access: { roles: ["admin"] }
        },
        mockAccessTokenClaims: {
            audience: "profile",
            sub: "123",
            realm_access: { roles: ["admin"] }
        }
    });

} else {

    bootstrapOidc({
        issuerUri: "https://auth.my-company.com/realms/myrealm",
        clientId: "myclient",
        startCountdownSecondsBeforeAutoLogout: 45,
        // ...
    });

}

[garronej]

I have published an RFC regarding TanStack Start integration:
#105

It's dense but feel free to voice your opinion, now it's the perfect time to influence the API design.

[garronej]

Hello here,

Just an update to say that I'm really, really close to have something shippable.
#103

I found a way to get rid of suspense.
It will be a full, end to end solution for auth. Not just the client side part.

This is why it's taking so long but it's comming.