Move all NextAuth.js projects into a monorepo

[balazsorban44]

When NextAuth.js was first created, it had a single Adapter, and no docs. Later on, a documentation page was added, and until v4, it lived under a www folder in this repository.

As the need for more adapters appeared, we decided to separate the project into multiple repositories:

Currently we have:

Core: https://github.com/nextauthjs/next-auth
Adapters: https://github.com/nextauthjs/adapters
Docs: https://github.com/nextauthjs/docs
JS Example: https://github.com/nextauthjs/next-auth-example
TS Example: https://github.com/nextauthjs/next-auth-typescript-example

I propose that we move Core, Adapters and Docs into the same repository again, but this time we do it properly as a monorepo.

Adapters is a good starting point, as it is already a monorepo, using Lerna under the hood.

For the new monorepo, Turborepo looks like a very good candidate. It currently does not support versioning, and I propose we have a look at Changesets as an alternative to lerna. I've had difficulties with it on the Adapters repo (mainly because of lack of experience, I admit), and I've heard good things about Changesets.

As for the examples, ideally, we could also move those into the monorepo, but they are currently available as repository templates. We could add a cron job that copies our example packages from the monorepo to those repos, so we don't have to maintain them separately.

A reason for this proposal is that although the initial intention was a better separation of bug reports for easier maintenance, most of the time people don't check where they post a bug report, and it has been difficult to keep up with that (I mostly had to manually transfer issues to the correct place, which is tedious).

Further, as we plan to expand to other frameworks (#2294), it might be easier to keep everything under the same repository.

In the long term, the core package should be available as @next-auth/core probably, but for now let's keep it as next-auth.

With this transition to a monorepo, we could start accepting PRs for other frameworks.

If you have any suggestions, let us know!

[ThangHuuVu]

To replace lerna, it is a question about which features of lerna we'd like to keep:

• Installer: candidates are yarn workspaces (v1), pnpm
• Publisher: I see that we've already got a preference for changesets. Otherwise: pnpm, rush. For rush, they have an interesting Version Policy feature in the new release.
• Task runner: I think this is where turborepo shines. Other: Nx
• All-in-one candidates: rush, pnpm

IMO, we can try this combo (astro use the same combo):

• yarn for installer + changesets for publisher: First step, make it works first
• turborepo for task runner: Second step, make it fast

[adambrgmn]

I would love to help out with this if you need it! I've tried both turborepo and changesets in personal projects with decent result.

Turborepo works great with npm workspaces as well, so no need to move over to yarn for that reason.

I guess a good first step would be to setup turborepo in this repository, and make sure that every script etc. works the same way as before. Then following steps could be to extract shared configuration and bring in adapters and the docs.

[balazsorban44]

Thank you! I believe @ThangHuuVu already has something he asked my opinion about, but any help is appreciated @adambrgmn! 🙏

I do use yarn 1 though (not 2 of 3), so that's not an issue for me.

[ThangHuuVu]

Yeah, so I did try to merge docs & this repo together at a separate repository. It has the most basic setup for yarn workspaces. I then immediately ran into the problem @adambrgmn hinted: shared configuration files conflict at the root of each repo. I'm not sure how to unify them reliably, so at the moment I just put all the files to their directory in packages. Files that need to be unified:

• Metadata: .github, readme, etc.
• Tools: eslint, tsconfig.json, etc.
• ...

Furthermore, in this repo, we have app for development and src for core lib. It makes good sense to separate these two into two packages in the monorepo project.

With that, together with @adambrgmn's comment, I suggest the following steps:

1. Convert this repo into monorepo with app and src using the chosen stack. Rename app and src into for example dev-app and core.
2. After 1), we then have root files at this repo: .github, readme, eslint, tsconfig,... Unify these root files with docs and adapters (prepare for merge):
   2.1. adapters: adapters is already a monorepo. To ensure everything continues to work with the new stack, I suggest we can also convert adapters from lerna to use the new tools first (In the process, we might need to change root files in the main monorepo). I also suggest renaming adapters package directories to add -adapters suffix.
   2.2. docs: Because docs is not a monorepo, it's simpler. To avoid merge conflicts, we can move all files that are only relevant to docs to a subdirectory first. For example, packages/docs.
3. Then merge docs and adapters into this repo.

TBD: The tech stack. Currently:

• yarn workspaces vs npm workspaces?
• changesets
• turborepo

@balazsorban44 @adambrgmn What do you think about this? 🤝

[adambrgmn]

I think this sounds like a great plan 👍 let me know if you need help with something!

Just "a few words"; I saw this tweet the other day. It has proven to be very true. We did a migration to NX at work before summer last year. We had two attempts before succeeding. The failures was due to us trying to "fix" stuff while migrating. ☺️

[balazsorban44]

I'm so thankful for thinking this through!

This sounds like a good plan, let's start with step 1.

I am traveling this week and will meet up @ndom91 and @lluia the next week in live for the first time (:tada:). So if any of you want to open a PR until then, we could review, or else we can make this as our goal for the meetup to make the migration.

[ndom91]

Wow thanks for all the hard work so far everyone! @balazsorban44 this sounds like a great project for us next week 🎉

[always-maap]

@ThangHuuVu I recommend moving "dev-app" to the apps folder as many mono-repo do

[balazsorban44]

@ndom91 and I successfully moved the docs and adapter repositories into this one.

Tests, builds are passing.

Remaining tasks:

• set up versioning/publishing
• cleanup configs/CI
• make sure no links are broken in docs
• migrate PRs from other repos
• retire old repos
• decide on how to maintain https://github.com/nextauthjs/next-auth-example

Admittedly, I don't seem to be a fan of Changesets, as it requires extra effort to write release notes. We already write commits, that should be enough to determine everything. I think https://github.com/pmowrer/semantic-release-monorepo might be a good solution for us. It is like semantic-release but only considers commits that touched a certain folder for a package.

For the example repo, we might move it into the monorepo, and have a GitHub action set up that commits all changes to the template repo.

[always-maap]

@ndom91 and I successfully moved the docs and adapter repositories into this one.

Tests, builds are passing.

Remaining tasks:

• set up versioning/publishing
• cleanup configs/CI
• make sure no links are broken in docs
• migrate PRs from other repos
• retire old repos
• decide on how to maintain https://github.com/nextauthjs/next-auth-example

Admittedly, I don't seem to be a fan of Changesets, as it requires extra effort to write release notes. We already write commits, that should be enough to determine everything. I think https://github.com/pmowrer/semantic-release-monorepo might be a good solution for us. It is like semantic-release but only considers commits that touched a certain folder for a package.

For the example repo, we might move it into the monorepo, and have a GitHub action set up that commits all changes to the template repo.

I think moving dev-app, next-auth-example and docs in the apps folder here would be great and docs md in the root.
that's how I like to see mono-repo grow. it also opens the door for muli-framework examples.

[balazsorban44]

I believe we could take the above suggestion further. I propose something like this:

This will allow extreme flexibility for us in the future, regarding work on other frameworks (#2294)

[asuraphel]

This is awesome. Any updates? Thanks!