Migrate to Typescript

[NickBolles]

Working off of #220, I took a shot at converting next-auth to typescript.

Todo

• Update any contributor docs
• Verify tests are succeeding
• Verify hot reloading works?
• Work with it for a while and verify it's all looking good
• Verify NPM publish
• Possibly organize types more
• verify signin/signout types
  • documentation suggests passing the function directly as the callback for events (onClick), but that means that the signin/signout functions are actually being called with the event object. So what should we type this? Right now I have it as an overloaded function, which allows both onClick={signIn} and onClick={() => signIn()} as well as provides intellisense on the available providers for the first argument

    type SigninFn = {
      (provider: AvailableProviders, args?: SignInArgs): Promise<void>;
      (provider?: any, args?: SignInArgs): Promise<void>;
    }

    

Why convert to typescript?

First off, see the linked issue and the discussion about switching there. While there was concern about switching in that issue, I wanted to show that it's not that difficult, and give a prototype to try.

Detached typings are impossible to keep up to date

To help emphasize why this is a good idea and why typings such as the ones referenced in the PR aren't good enough, here is a small subset of the issues with the proposed typings I ran across while doing this transition (please correct me if you see any issues, both here and in code. I'm not too familiar with next-auth v2 yet)

There were several other issues with null checks that I needed to fix as well, but those are less impactful. Most of these would result in incorrect functionality for typescript users.

1. Missing Providers typings (these would not show up for typescript users at all)

• Linked In
• Spotify
• Reddit
• Basecamp

2. Email config Typings

• It looks like these two were on the ProviderEmailServer, when it looks like they should be on ProviderEmailOptions (although I'm not too sure what ProviderEmailServer should be)

maxAge: number;
sendVerificationRequest: typeof sendVerificationRequest;

3. jwt on InitOptions shouldn't be a boolean

• https://next-auth.js.org/configuration/options#jwt
• and it will crash if it's a boolean at runtime

// JWT options
   const jwtOptions = {
     secret, // Use application secret if no keys specified
     maxAge: sessionOptions.maxAge, // maxAge is dereived from session maxAge,
     encode: jwt.encode,
     decode: jwt.decode,
     ...userSuppliedOptions.jwt
   }

4. PageOptions.signin should be PageOptions.signIn (capital "i")
5. PageOptions.newUsers should be PageOptions.newUser (no "s")
6. Fix "for" JSX attribute

src/server/pages/signin.tsx:67:22 - error TS2322: Type '{ children: string; for: string; }' is not assignable to type 'DetailedHTMLProps<LabelHTMLAttributes<HTMLLabelElement>, HTMLLabelElement>'.
       Property 'for' does not exist on type 'DetailedHTMLProps<LabelHTMLAttributes<HTMLLabelElement>, HTMLLabelElement>'.

     67               <label for={`input-email-for-${provider.id}-provider`}>Email</label>
                             ~~~

and

      src/server/pages/signin.tsx:78:23 - error TS2322: Type '{ children: any; for: string; }' is not assignable to type 'DetailedHTMLProps<LabelHTMLAttributes<HTMLLabelElement>, HTMLLabelElement>'.
        Property 'for' does not exist on type 'DetailedHTMLProps<LabelHTMLAttributes<HTMLLabelElement>, HTMLLabelElement>'.

      78                       for={`input-${credential}-for-${provider.id}-provider`}

Other

we don't need to have a debate about TS vs JS here, but I find it invaluable for documentation and confidence in community changes to have type checking, so I wanted to put this PR together.

A couple other questions I came across while doing the change

1. Basecamp doesn't look like it exists in code, but it's documented. Am I missing something here? - this is merged now
   1a. Basecamp doesn't have a scope property, all of the other OAuth providers do. Should it.
2. Reddit isn't documented, should it be? looks like profile part doesn't work yet though
3. Github has an extra scope parameter in typings that isn't in documentation. Should it be?
4. Are there any other providers that have extra options? how can we verify that?

[vercel]

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/nextauthjs/next-auth/jogohcsk7
✅ Preview: https://next-auth-git-fork-nickbolles-njb-migrate-to-ts.nextauthjs.vercel.app

[iaincollins]

I've added a label to note this is pull request is on hold, until after testing and after a core team decision about priorities and where this might fit in.

There is a lot of good stuff in this PR but there are also a number of things in flight merging this would impact and questions regarding what the impact of this would be on-going development.

[NickBolles]

@iaincollins sounds good. I also converted this to a draft. Feel free to ping me here when things merge to master (or I can pull in changes from branches in question too) and make the updates. I just did this for the basecamp change.

[iaincollins]

@iaincollins sounds good. I also converted this to a draft. Feel free to ping me here when things merge to master (or I can pull in changes from branches in question too) and make the updates. I just did this for the basecamp change.

Thanks Nick! Really appreciate it.

Letting pull requests go stale is never a good feeling and I appreciate this has happened before.

• I'm going to try and get the tests in shape to run on Monday, to unblock the work @JeffersonBledsoe has done in Add initial end-to-end tests #298

• I want to get our release system sorted out too (with team agreement) - that's why stuff like Basecamp provider is going live on the website before release, we just haven't had taken time to sort that out yet.

Once we have some versions of those in place (and either automated publishing of pre-release versions to canary tag or something equivalent) we should be in a much better place to handle refactoring. This is a bug bear for me too as there is a load of stuff I would like to refactor in the oauth code that is knarly and not easy to debug.

[stale]

Hi there! It looks like this issue hasn't had any activity for a while. It will be closed if no further activity occurs. If you think your issue is still relevant, feel free to comment on it to keep ot open. Thanks!

[grikomsn]

For those who are interested on helping the TypeScript rewrite, where can we start?

Recently I tried to rebuild next-auth from the ground up using tsdx but didn't continue because it has Docusaurus and other stuff I didn't know how to approach.

[balazsorban44]

@grikomsn I have an idea, don't know if it's the best strategy, but it is incremental, can be stretched over many PRs (which are easier to handle, the iteration is faster), and releases, so here it is:

1. Add JSDoc comments to user-facing API functions/methods
2. Add .d.ts files, and use those for functions defined in 1. (eg. you can do * @param {import("next").NextApiRequest} req and at least VSCode IntelliSense will work)
3. Add JSDoc for all internal functions
4. Repeat 2. only for internal functions
5. enable // @ts-check at the top of the files, and fix remaining errors (use any for faster iterations)
6. add TS compilation, merge .d.ts and .js files into .ts files.
7. retire @types/next-auth with a deprecation message
8. expose the .d.ts types through the types package.json property

This is good because even if we end up stopping at step 6 because we do not wish to convert everything to TS, we will still have a good type system right next to the codebase.

[balazsorban44]

I am pretty sure this PR won't be merged. If anyone would like to work on TS support, please create a corresponding issue for it, where we can track the progress. Initially, it would maybe even be better to discuss it in the Discussions