Improve documentation around the path location of custom pages

[jeremycaine]

Summary of proposed feature
Improve documentation around using custom pages and their location they must not be put in.

Purpose of proposed feature
The key documentation page for explaining custom signin pages is here.
The documentatin should say that custom pages should NOT be put in the pages/api/auth location.

Detail about proposed feature
On this page I made the mistake of reading the Examples Email Sign In pages/auth/credentials-signin.js and Credentials Sign In pages/auth/email-signin.js as instructions to create the pages in the path pages/api/auth/.... This error was in part because of the commented out elements of pages: in the pages/api/auth/[...nextauth.js] where it says:

// You can define custom pages to override the built-in pages.
  // The routes shown here are the default URLs that will be used when a custom
  // pages is not specified for that route.
  // https://next-auth.js.org/configuration/pages
  pages: {
    //signIn: '/api/auth/signin',  // Displays signin buttons
    // signOut: '/api/auth/signout', // Displays form with sign out button
    // error: '/api/auth/error', // Error code passed in query string as ?error=
    // verifyRequest: '/api/auth/verify-request', // Used for check email page
    // newUser: null // If set, new users will be directed here on first sign in
  },

I made the incorrect assumption that the custom pages need to be in the /api/auth/... path.

Potential problems
If the developer puts the pages in the location pages/api/auth/xxxx... then for Email and Credentials providers there is an error when trying to go the custom page in that wrong location e.g.

..
pages: {
    //signIn: '/api/auth/myloginpage',  
...

You get this error:
API resolved without sending a response for /api/auth/myloginpage?callbackUrl=http://localhost:3000/, this may result in stalled requests.

Additional context
This is the page that should be improved with more guidance.

Please indicate if you are willing and able to help implement the proposed feature.
I'm happy to fork and suggest an edit to the documentation

[balazsorban44]

Thank you for raising this! Indeed, the docs could be more clear. It would be very welcome if you could improve it!

The reason why it did not work for you is probably that the pages/api routes in Next.js are reserved for, well, API handlers. They should always have a single default export, with a similar signature:

export default async function handler(req: NextApiRequest, res: NextApiResponse): void

Check the docs for more info: https://nextjs.org/docs/api-routes/introduction

We actually use preact and server rendering for those pages, have a look here: https://github.com/nextauthjs/next-auth/blob/canary/src/server/pages/signin.js

So I think you could actually add your custom page under pages/api/auth, as long as you are aware that it should be wrapped with an API handler, sending actual HTML as the response.

So in the end, it is not a restriction on our end, it is simply how Next.js works. Hope this clears things up, and help you improve our docs 🙂