Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve documentation around the path location of custom pages #1228

Closed
jeremycaine opened this issue Jan 31, 2021 · 1 comment
Closed

Improve documentation around the path location of custom pages #1228

jeremycaine opened this issue Jan 31, 2021 · 1 comment
Labels
hacktoberfest-docs Relates to documentation upstream The issue dervies from one of next-auth dependencies

Comments

@jeremycaine
Copy link

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

@jeremycaine jeremycaine added the enhancement New feature or request label Jan 31, 2021
@balazsorban44
Copy link
Member

balazsorban44 commented Jan 31, 2021

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 🙂

@balazsorban44 balazsorban44 added hacktoberfest-docs Relates to documentation upstream The issue dervies from one of next-auth dependencies and removed enhancement New feature or request labels Jan 31, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
hacktoberfest-docs Relates to documentation upstream The issue dervies from one of next-auth dependencies
Projects
None yet
Development

No branches or pull requests

2 participants