Make `next-auth` framework agnostic (Vite, Vue, Express...)

[brillout]

Follow up of https://twitter.com/balazsorban44/status/1410641689715347461.

cc @s-kris @balazsorban44

next-auth can actually already be used with Vite today thanks to https://github.com/s-kris/vite-ssr-next-auth.

---

UPDATE FROM MAINTAINER:

Proof of concept:

• SvelteKit https://sveltekit-next-auth.vercel.app/ (Thanks @wobsoriano)
• Nuxt https://nuxt-next-auth.vercel.app/ (Thanks @wobsoriano)

v4 has been marked as stable, and the source code has been refactored to be Next.js API routes agnostic. It is still undocumented, but we are ready to discuss how to integrate with other frameworks in the open. If you are developing in one of those communities (Vue, Svelte etc.), feel free to reach out!

[balazsorban44]

I'm very hopeful about this. We might have to do small adjustments, but I think in most cases, a tiny wrapper on top of NextAuth would be enough. The ground work could be done as early as in v4 (aiming for a release this summer).

I already started to decouple/better namespace our client code, in v4 it will be under next-auth/react

See #1473

[brillout]

The ground work could be done as early as in v4 (aiming for a release this summer)

Exciting 😍.

Will I then be able to use NextAuth.js in a let's say Vite + Vue app?

I'm developing a framework ("Vike") on top of Vite + vite-plugin-ssr + RPC and I'd love to offer authentication to both my React and Vue users with NextAuth.js.

Thanks for your wonderful work, it's lovely to see the JS ecosystem maturing.

[balazsorban44]

If we rewrite the backend a bit, as long as your framework can set cookies and do redirects and handle basic POST/GET requests, it should be good. We would need to separate the server/index.js file in a way that it is only a tiny wrapper for Next.js and the core stuff could be framework agnostic.

I liked the Sveltekit endpoint approach:

https://kit.svelte.dev/docs#routing-endpoints

[brillout]

Neat & yes, the backend integration should work then.

How about Vue?

You mentioned:

I already started to decouple/better namespace our client code, in v4 it will be under next-auth/react

Will we be able to have a next-auth/vue? I can see myself (and potentially other Vue users) to contribute.

[balazsorban44]

Yes, that would be easy I think.

Here is the source code for the react specific frontend:

https://github.com/nextauthjs/next-auth/blob/next/src/client/react.js

We still have to work out some small things like tab syncing and invalidation of the session, but other than that it should not be hard, hopefully.

[brillout]

👌.

Had a quick look over the source and yea should be fairly easy to port it to Vue's composition API; there aren't that many React specific things going on. AFACIT a common module that factors out the React/view-framework agnostic code should make porting quite easy.

Can't wait to see NextAuth.js to become the de facto standard — Vite & Vue users will love it :-).

[wobsoriano]

It's quite amazing that you don't even need to install react to use it with Nuxt. Here's a repo on how someone could use next-auth with nuxt! https://nuxt-next-auth.vercel.app/

https://github.com/wobsoriano/nuxt-next-auth

[brillout]

@wobsoriano Wow neat... would you be up to develop some Vue composition functions? Basically like next-auth/react but for Vue. I'd happily assist/review.

[balazsorban44]

That's awesome @wobsoriano! Looking forward to set some time aside for this enhancement, so we can start the expansion! I will probably need some help for the Vue client.

[wobsoriano]

Copied contents of next-auth/client and updated some lines to make it work with Vue's Composition API https://github.com/wobsoriano/nuxt-next-auth/blob/master/modules/next-auth/client.js

Most if it are working now - useSession, getSession, signIn, signOut, getCsrfToken, getProviders.

// store/index.js
export const actions = {
    async nuxtServerInit({ commit }, { req }) {
        try {
            const session = await getSession({ req })
            commit('SET_SESSION', session);
        } catch (e) {
            commit('SET_SESSION', null);
        }
    }
}

<template>
  <div>
    <div v-for="provider in Object.values(providers)" :key="provider.id">
      <button @click="signIn(provider.id)">Sign in with {{ provider.name }}</button>
    </div>
  </div>
</template>

<script>
import { defineComponent } from '@nuxtjs/composition-api';
import { getProviders, signIn } from '~/modules/next-auth/client';

export default defineComponent({
  middleware: 'guest',
  setup() {
    return {
      signIn
    }
  },
  async asyncData() {
    const providers = await getProviders()
    return {
      providers
    }
  }
})
</script>

and adding configs directly to nuxt.config.js

import Providers from 'next-auth/providers';

export default {
  // other nuxt config
  nextAuth: {
    providers: [
      Providers.GitHub({
          clientId: process.env.GITHUB_CLIENT_ID,
          clientSecret: process.env.GITHUB_CLIENT_SECRET
      }),
    ],
  }
}

[brillout]

@wobsoriano Neat neat 👌. What was your reason to use Nuxt's composition API instead of Vue's one? What do you think of factoring out the common code between next-auth/client and your version? That way anyone can use NextAuth.js with anything e.g. with Vue's composition API

[wobsoriano]

@wobsoriano Neat neat 👌. What was your reason to use Nuxt's composition API instead of Vue's one? What do you think of factoring out the common code between next-auth/client and your version? That way anyone can use NextAuth.js with anything e.g. with Vue's composition API

Actually published a simple Nuxt module for this that later we can add to next-auth/client since Nuxt 2.0 supports Vue 2 only

https://github.com/wobsoriano/nuxt-next-auth

[brillout]

Nice 👍. Ideally nuxt-next-auth would be only a thin wrapper around a next-auth view-framework agnostic library. Right now there is a lot of duplicated code between next-auth/client and nuxt-next-auth right?

[wobsoriano]

Nice 👍. Ideally nuxt-next-auth would be only a thin wrapper around a next-auth view-framework agnostic library. Right now there is a lot of duplicated code between next-auth/client and nuxt-next-auth right?

Yeah, the whole client.js file is copied

[brillout]

I guess it should be easy to factor out the common code?

The common code could then live at github.com/nextauthjs.

Thoughts?

[simplenotezy]

Pretty neat - looking to integrate Next-auth into an Express API, so would be happy to test this out and deliver feedback

[wobsoriano]

I think we can start adding integrations for vue/svelte in the beta branch

[balazsorban44]

I kindly ask anyone wanting to work on this to wait until v4 is released as stable! I have many ideas and future improvements planned, but v4 beta should be considered as a feature freeze, and no additional changes should be made apart from bug fixes. Keep an eye on the releases.

That said, you can definitely start looking into this, but I cannot provide feedback until v4 is ready.

[brillout]

👍 Is there an ETA for v4?

[balazsorban44]

It is currently in beta. The more people check it out/give feedback on what is missing/failing, the faster it will be to release it to stable.

I have never worked on anything of this scale, and the responsibility is huge, so I want to make it right.

[brillout]

check it out/give feedback

I will.

[brillout]

The more people check it out/give feedback on what is missing/failing

Are there some docs about extending NextAuth to add support for Vie, Vue, etc.?

[balazsorban44]

No, not that I'm aware of. Not sure where it could fit nicely, but feel free to open a PR on https://github.com/nextauthjs/docs

[brillout]

Would love to PR but I'm not sure I'm the right person to do it since I'm not that familiar with it.

Ideally nuxt-next-auth would be only a thin wrapper around a next-auth view-framework agnostic library

Is there a plan to have a lower-level view-framework agnostic public API? It would essentially resolve this ticket ❤️.

I can also see the SvelteKit folks to absolutely love it (they are super active on Vite).

[balazsorban44]

Yes, that is the plan, and I would like it to be similar to SvelteKit endpoints.

https://github.com/nextauthjs/next-auth/issues/2294#issuecomment-889141365

This will need some refactors in the core as we vigorously pass around req and res everywhere and even mutate it, but I don't think it will be hard. once v4 is stable, I'll jump right onto it :smile:

[balazsorban44]

OK, so because of some other factors, we are awaiting a stable v4, but in the meantime, I started working on this in #2857

I already tested it locally with different OAuth providers, Credentials, and an Email provider, with an adapter and without, and everything seems to work... :eyes:

For now, I will be publishing an experimental release, which you can find here (the comment will change whenever I approve a release for publishing): https://github.com/nextauthjs/next-auth/pull/2857#issuecomment-930139134

For merging, I'll have to test it more, make sure nothing is broken, and all the logic from before is intact.

The core has been rewritten entirely to not use res at all and the main NextAuthHandler method will return an object that any framework can wrap however they need.

export interface IncomingRequest {
  method: string
  headers: Record<string, any>
  cookies: Record<string, any>
  query: Record<string, any>
  body: Record<string, any>
}

export interface OutgoingResponse {
  status?: number
  headers?: any[]
  json?: any
  text?: any
  redirect?: string
  cookies?: Cookie[]
}

export interface NextAuthHandlerParams {
  req: IncomingRequest
  options: NextAuthOptions
}

export async function NextAuthHandler(params: NextAuthHandlerParams): Promise<OutgoingResponse>

Eg.: Here is the Next.js wrapper: https://github.com/nextauthjs/next-auth/blob/3bac68da3bf45343b90cf9b79dc96f251b60a6c4/src/next/index.ts

[brillout]

Love it.

Any feedback you want from me?

@wobsoriano Up for rebasing your work on top of this?

[balazsorban44]

With the full disclosure that this is very experimental at the moment

I'm kind of overly confident about it, so just testing it out with other frameworks and see what's missing (if anything) would be nice. 😁 would be interesting to see if someone could start working on a Vue/Svelte/Vanilla(?) client counterpart as well.

We have the @next-auth org on npm (adapters are there), so maybe it would make sense to release a @next-auth/core or something. Will have to think about it.

[Cafezinho]

Hey, I would love to use it in my NextJS app, but instead of using pages/api, I am using serverless framework in python deploying on Azure Functions.

Is there any way to use this fantastic lib in this setup?

Thanks!

[balazsorban44]

This is a JavaScript library. As much as I would love to support all the things, we have to draw the line at the language barrier, sorry. 😅

[danielweil]

This is a JavaScript library. As much as I would love to support all the things, we have to draw the line at the language barrier, sorry. 😅

I know, I am wondering if I can use the library to handle client side of SSO auth, save the jwt token and then use it to send to my Functions when needed. This seems plausible?

P.S same person, different user by accident

[wobsoriano]

Love it.

Any feedback you want from me?

@wobsoriano Up for rebasing your work on top of this?

Which one? The nuxt thing? 😅

[brillout]

if someone could start working on a Vue/Svelte/Vanilla(?) client counterpart so maybe it would make sense to release a @next-auth/core or something.

Yes that would awesome. How about releasing a beta npm package @next-auth/code0.1.0-beta.1 so we can start trying it? (Actually, how about naming it @next-auth/client? So: @next-auth/client + @next-auth/react + @next-auth/vue.)

@wobsoriano

Which one? The nuxt thing? 😅

Yea you migrated the React client to Vue; would be awesome to have your Vue client rebased on @next-auth/core 😍.

[brillout]

Ah actually I remember your client uses Nuxt's composition API. But I guess your client would also work with Vue's composition API? Or we also publish @next-auth/nuxt.

[wobsoriano]

Ah actually I remember your client uses Nuxt's composition API. But I guess your client would also work with Vue's composition API? Or we also publish @next-auth/nuxt.

Yes it's composition API. I'm actually waiting for Nuxt 3 so we can then use @next-auth/core there...

[wobsoriano]

OK, so because of some other factors, we are awaiting a stable v4, but in the meantime, I started working on this in #2857

I already tested it locally with different OAuth providers, Credentials, and an Email provider, with an adapter and without, and everything seems to work... 👀

For now, I will be publishing an experimental release, which you can find here (the comment will change whenever I approve a release for publishing): #2857 (comment)

For merging, I'll have to test it more, make sure nothing is broken, and all the logic from before is intact.

The core has been rewritten entirely to not use res at all and the main NextAuthHandler method will return an object that any framework can wrap however they need.

export interface IncomingRequest {
  method: string
  headers: Record<string, any>
  cookies: Record<string, any>
  query: Record<string, any>
  body: Record<string, any>
}

export interface OutgoingResponse {
  status?: number
  headers?: any[]
  json?: any
  text?: any
  redirect?: string
  cookies?: Cookie[]
}

export interface NextAuthHandlerParams {
  req: IncomingRequest
  options: NextAuthOptions
}

export async function NextAuthHandler(params: NextAuthHandlerParams): Promise<OutgoingResponse>

Eg.: Here is the Next.js wrapper: https://github.com/nextauthjs/next-auth/blob/3bac68da3bf45343b90cf9b79dc96f251b60a6c4/src/next/index.ts

IncomingRequest also requires action right?

[balazsorban44]

I slightly changed it in the newest release, sorry. Here are the most recent interfaces:

type NextAuthAction =
  | "providers"
  | "session"
  | "csrf"
  | "signin"
  | "signout"
  | "callback"
  | "verify-request"
  | "error"
  | "_log"

interface IncomingRequest {
  method: string
  cookies?: Record<string, any>
  headers?: Record<string, any>
  query?: Record<string, any>
  body?: Record<string, any>
  action: NextAuthAction
  providerId?: string
  error?: string
}

interface OutgoingResponse<J = any> {
  status?: number
  headers?: any[]
  json?: J
  text?: any
  redirect?: string
  cookies?: Cookie[]
}

interface NextAuthHandlerParams {
  req: IncomingRequest
  options: NextAuthOptions
}

They are also moved into another file. I'll do a quick release to actually expose it as next-auth/core

Here is the next-auth/next module (for the foreseeable future it will also be re-exported from next-auth): https://github.com/nextauthjs/next-auth/blob/3ba16de6cd30f9a7374db87d69ca682d97d69a7f/src/next/index.ts

[wobsoriano]

I slightly changed it in the newest release, sorry. Here are the most recent interfaces:

type NextAuthAction =
  | "providers"
  | "session"
  | "csrf"
  | "signin"
  | "signout"
  | "callback"
  | "verify-request"
  | "error"
  | "_log"

interface IncomingRequest {
  method: string
  cookies?: Record<string, any>
  headers?: Record<string, any>
  query?: Record<string, any>
  body?: Record<string, any>
  action: NextAuthAction
  providerId?: string
  error?: string
}

interface OutgoingResponse<J = any> {
  status?: number
  headers?: any[]
  json?: J
  text?: any
  redirect?: string
  cookies?: Cookie[]
}

interface NextAuthHandlerParams {
  req: IncomingRequest
  options: NextAuthOptions
}

They are also moved into another file. I'll do a quick release to actually expose it as next-auth/core

Here is the next-auth/next module (for the foreseeable future it will also be re-exported from next-auth): https://github.com/nextauthjs/next-auth/blob/3ba16de6cd30f9a7374db87d69ca682d97d69a7f/src/next/index.ts

Awesome! I was trying to make it work with SvelteKit but can't seem to make csrfTokenVerified set to true. Manually updated if (options.csrfTokenVerified && options.provider) to if (options.provider) to see if routes will work and it did.

https://gist.github.com/wobsoriano/87f6b2bb38587441db5d2ca1172c014c

[balazsorban44]

CSRF token has to be verifiedd in 3 cases, all three when the request is a POST request.

signin, signout, and callback (when using credentials provider): https://github.com/nextauthjs/next-auth/blob/e1db2838afff79ac5ec369f121b01579eb8056aa/src/core/index.ts#L145-L176

This is done through a method called double submit. https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html#double-submit-cookie https://github.com/nextauthjs/next-auth/blob/e1db2838afff79ac5ec369f121b01579eb8056aa/src/core/lib/csrf-token.ts#L31-L44

Basically you have to make sure that in the above cases, you attach the csrfToken to the request body as well as sending it as a cookie.

Example: https://github.com/nextauthjs/next-auth/blob/e1db2838afff79ac5ec369f121b01579eb8056aa/src/react/index.tsx#L219 (cookie is submitted automatically to the same domain.)

[balazsorban44]

After looking at your gist @wobsoriano, I decided to further simplify the OutgoingResponse interface to:

export interface OutgoingResponse<
  Body extends string | Record<string, any> | any[] = any
> {
  status?: number
  headers?: NextAuthHeader[]
  body?: Body
  redirect?: string
  cookies?: Cookie[]
}

Basically instead of having json, text, html etc. properties, I just set the correct header which you already propagate, and use body for any data.

There is one exception, redirect. It is just easier to set a string in the source code and deal with it in the wrapper.

Redirect has a caveat, which was previously hidden, so you probably did not see it:

When the client sends a POST request to the backend (eg. at signin), it will have to redirect the user to another page (to start the login flow in your Identity Provider). For this purpose, the frontend can send a json: true flag in the body, which means the redirect url has to be returned in JSON, instead of setting the Location header. See the code here:

https://github.com/nextauthjs/next-auth/blob/10fbb5ace8abcf2b39a232df33a60ad088f1650b/src/next/index.ts#L68-L81

Newest version is at: https://github.com/nextauthjs/next-auth/pull/2857#issuecomment-930139134

[balazsorban44]

I wonder if returning cookies is a nice abstraction, or should we just go all-in and return it as a Set-Cookie header as well? :thinking: (In your gist, you wouldn't need to install a third-party lib like cookie. We have a similar code snippet in core, so it feels unnecessary.)

Should headers be a Record<string, string> instead of a Array<{ key: string; value:string }>?

We could potentially fix all the above mentioned stuff (including the redirect and its special case) in the core, so the wrapper shouldn't have to care about handling special cases, I guess...

I'll have to sleep on it, but please tell me what you think!

[wobsoriano]

I wonder if returning cookies is a nice abstraction, or should we just go all-in and return it as a Set-Cookie header as well? 🤔 (In your gist, you wouldn't need to install a third-party lib like cookie. We have a similar code snippet in core, so it feels unnecessary.)

Should headers be a Record<string, string> instead of a Array<{ key: string; value:string }>?

We could potentially fix all the above mentioned stuff (including the redirect and its special case) in the core, so the wrapper shouldn't have to care about handling special cases, I guess...

I'll have to sleep on it, but please tell me what you think!

I think the current implementation looks fine!

Here's the working example for SvelteKit https://github.com/wobsoriano/sveltekit-next-auth-demo. Managed to fix csrfToken error

I'm getting build errors in Vercel deployment (GithubProvider is not a function) so I can't send preview yet. Also since SvelteKit is using Vite, and Vite only reads variables that starts with VITE_, the NEXTAUTH_URL isnt read

[balazsorban44]

I see. I can fix the env. variable by making so that the core itself doesn't read the env variable, but you can pass it in as well.

Not sure about the error with GithubProvider, I have to check.

UPDATE:

 interface IncomingRequest {
  /** @default "http://localhost:3000" */
  host?: string
  method: string
  cookies?: Record<string, any>
  headers?: Record<string, any>
  query?: Record<string, any>
  body?: Record<string, any>
  action: NextAuthAction
  providerId?: string
  error?: string
}

The host param can be passed as a variable now. It's up to the wrapper to verify it exists now, and show a warning to the user.

[balazsorban44]

Regarding https://github.com/wobsoriano/sveltekit-next-auth/blob/master/src/routes/api/auth/%5B...nextauth%5D.ts

I have a suggestion. Ideally the $lib/next-auth part won't be visible for users, so we should refactor a bit.

Depending on if SvelteKit supports a default exported object to catch both get and post or it only supports named exports, one of these would be ideal:

1.

import NextAuth, { NextAuthOptions } from '$lib/next-auth'

export const options: NextAuthOptions = {}
export default NextAuth(options)

Then https://github.com/wobsoriano/sveltekit-next-auth/blob/master/src/lib/next-auth.ts should be refactored to have a default exported object that looks something like this:

export default {
  get: (options: NextAuthOptions) => (req: Request) => NextAuth(req, options),
  post: (options: NextAuthOptions) => (req: Request) => NextAuth(req, options)
}

2.

import NextAuth, { NextAuthOptions } from '$lib/next-auth'

export const options: NextAuthOptions = {}
export const get = NextAuth(options)
export const post = NextAuth(options)

The lib then would be something like this:

export default function NextAuth(req: Request) {
  return (options: NextAuthOptions) => NextAuthHandler(req, options)
}

We also support a different syntax, in case the user wants to do any changes to the request before it is passed to NextAuth. So this should be transferred to either 1 or 2 in their lib file. See https://github.com/nextauthjs/next-auth/blob/8844846c99052b8d592580ac48d7f7c02159c92f/src/next/index.ts#L84-L90

For its simplicity, I would prefer 1., but I don't know if it's supported by SvelteKit.

Notice the exported options also. This will be useful for getServerSession, which requires the user to pass the same options object. I haven't decided yet if we want to advise to have something like a next-auth.config.ts or it's fine to export from here.

[wobsoriano]

I see. I can fix the env. variable by making so that the core itself doesn't read the env variable, but you can pass it in as well.

Not sure about the error with GithubProvider, I have to check.

UPDATE:

 interface IncomingRequest {
  /** @default "http://localhost:3000" */
  host?: string
  method: string
  cookies?: Record<string, any>
  headers?: Record<string, any>
  query?: Record<string, any>
  body?: Record<string, any>
  action: NextAuthAction
  providerId?: string
  error?: string
}

The host param can be passed as a variable now. It's up to the wrapper to verify it exists now, and show a warning to the user.

Can the host update be installed now and tested? I want to play with it :D

[wobsoriano]

export default {
  get: (options: NextAuthOptions) => (req: Request) => NextAuth(req, options),
  post: (options: NextAuthOptions) => (req: Request) => NextAuth(req, options)
}

Looks like SK don't support default export https://kit.svelte.dev/docs#routing-endpoints

[balazsorban44]

Yes, sorry... 😅 I meant to release it on experimental, but I accidentally pushed a 4.0.0-beta.3 release instead... 🤷

The newest version should be available in https://github.com/nextauthjs/next-auth/pull/2857#issuecomment-930139134

(When not specified, just assume that whenever I mention "I updated", it's updated in that comment.)

Regarding default export. Have you ever tried, or you just assumed from the docs? :thinking: They might have forgotten to document it.

I guess it's not a usual use-case to handle those methods with the same handler...?

Here is the source code: https://github.com/sveltejs/kit/blob/0245ce0e35ea663767dd7ecc4a614524ff9064a0/packages/kit/src/runtime/server/endpoint.js#L41-L45

Yeah, doesn't look like it supports a catch-all handler. :confused: (Asked them on Twitter, maybe they'll respond: https://twitter.com/balazsorban44/status/1444628760695877636)

[wobsoriano]

Yes, sorry... 😅 I meant to release it on experimental, but I accidentally pushed a 4.0.0-beta.3 release instead... 🤷

The newest version should be available in #2857 (comment)

(When not specified, just assume that whenever I mention "I updated", it's updated in that comment.)

Regarding default export. Have you ever tried, or you just assumed from the docs? 🤔 They might have forgotten to document it.

I guess it's not a usual use-case to handle those methods with the same handler...?

Here is the source code: https://github.com/sveltejs/kit/blob/0245ce0e35ea663767dd7ecc4a614524ff9064a0/packages/kit/src/runtime/server/endpoint.js#L41-L45

Yeah, doesn't look like it supports a catch-all handler. 😕 (Asked them on Twitter, maybe they'll respond: https://twitter.com/balazsorban44/status/1444628760695877636)

I also asked them in Discord about that.

Meanwhile, a working sample https://sveltekit-next-auth.vercel.app/

Had to add this line in vite.config.js to make the Github Provider is not a function error go away

vite: {
    ssr: {
        noExternal: dev ? [] : ['next-auth']
    }
}

[wobsoriano]

Another one could be like this (adjustments of no. 2):

import NextAuth, { NextAuthOptions } from '$lib/next-auth'

const options: NextAuthOptions = {}
export const { get, post } = NextAuth(options)

The lib:

export default (options: NextAuthOptions) => ({
    get: (req: Request): Promise<Response> => SKNextAuthHandler(req, options),
    post: (req: Request): Promise<Response> => SKNextAuthHandler(req, options)
})

[wobsoriano]

is it possible to export client utils?

import {
    BroadcastChannel,
    CtxOrReq,
    apiBaseUrl,
    fetchData,
    now,
    NextAuthClientConfig,
} from './client'