From d150a7911ca19cf05e3c6fbde2e6fe9b8a12c116 Mon Sep 17 00:00:00 2001 From: Iain Collins Date: Tue, 5 May 2020 10:22:22 +0100 Subject: [PATCH] Update documentation --- CODE_OF_CONDUCT.md | 76 ++++++++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 9 ++++++ LICENSE.txt | 2 +- README.md | 46 ++++++++++++++++++++++++++-- 4 files changed, 129 insertions(+), 4 deletions(-) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000000..c6b93b47ca --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,76 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, sex characteristics, gender identity and expression, +level of experience, education, socio-economic status, nationality, personal +appearance, race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or +advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic +address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a +professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting me@iaincollins.com. All complaints will be reviewed and +investigated and will result in a response that is deemed necessary and +appropriate to the circumstances. The project team is obligated to maintain +confidentiality with regard to the reporter of an incident. Further details of +specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see +https://www.contributor-covenant.org/faq diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..5ca8a92431 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,9 @@ +# Contributing + +Contributions and feedback are welcome. + +This includes bug reports, feature requests, ideas, pull requests and examples of how you have used this software and what your experience of using it was like - both things that worked well and things that didn't work well. + +Please see the [Code of Conduct](CODE_OF_CONDUCT.md) and follow any templates configured in GitHub when reporting bugs, requesting enhancements or contributing code. + +Please note that as I maintain a number of packages it's not always possible to respond to feedback as quickly as I'd like. It can sometimes take a while to get around to reviewing pull requests and acting on feedback but the time and effort that does into raising them is appreciated. \ No newline at end of file diff --git a/LICENSE.txt b/LICENSE.txt index e48e0c34db..28f12d4d87 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -1,6 +1,6 @@ ISC License -Copyright (c) 2018, Iain Collins +Copyright (c) 2018-2020, Iain Collins Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above diff --git a/README.md b/README.md index bcd9251635..25cf0e82c4 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,10 @@ Note: NextAuth is not associated with Next.js or Vercel. ## Configuration +Configuration is much simpler and more powerful than in NextAuth 1.0, with both SQL and Document databases supported out of the box. There are predefined models for Users and Sessions, which you can use, extend or replace with your own! + +### Server + To add `next-auth` to a project, create a file to handle authentication requests at `pages/api/auth/[...slug.js]` with a list of authentication providers (e.g. Twitter, Facebook, Google, GitHub, etc) and your database (e.g. MongoDB, MySQL, Elasticsearch, etc). All requests to `pages/api/auth/*` (signin, callback, signout) will be automatically handed by NextAuth. @@ -28,7 +32,6 @@ Example `pages/api/auth/[...slug.js]`: import NextAuth from 'next-auth' import Providers from 'next-auth/providers' import Adapters from 'next-auth/adapters' -import MongoClient from 'mongodb' const options = { site: 'https://www.example.com', @@ -46,16 +49,53 @@ const options = { clientSecret: process.env.GITHUB_CLIENT_SECRET }), ], - adapter: Adapters.MongoDB(MongoClient, process.env.MONGODB) + adapter: Adapters.Default() } export default (req, res) => NextAuth(req, res, options) ``` +An "*Adapter*" in NextAuth is a object connects to whatever system you want to use to store data for user accounts, sessions, etc. + +NextAuth comes with a default adapter that uses [TypeORM](https://typeorm.io/) so that it can be be used with many different databases without any configuration. + +To specify the database you want to use (and to pass any credentials) you can use environment variables ([see TypeORM configuration documentation](https://github.com/typeorm/typeorm/blob/master/docs/using-ormconfig.md)). + +Alternatively, you can create a file called `ormconfig.json` at the top level of your project with your configuration, or you can pass a configuration object to the `Adapters.Default()` function. + +An example `ormconfig.json` configuration for SQL Lite (useful for local development and testing): + +```json +{ + "type": "sqlite", + "database": "test" +} +``` + +The following databases are supported by default adapter: + +* cordova +* expo +* mariadb +* mongodb +* mssql +* mysql +* oracle +* postgres +* sqlite +* sqljs +* react-native + +Appropriate tables / collections for Users, Sessions (etc) will be created automatically. You can customize, extend or replace the models by passing additional options to the `Adapters.Default()` function. + +### Client + NextAuth Client usage remains almost identical, but is much simpler than in version 1.x. +It can be used with React Hooks as well as React lifescycle and Next.js methods. + You can still create your own custom authentication pages, but if you want to you will now be able to just link to `/api/auth/signin` to use the built-in authentication pages, which are generated automatically based on the supplied configuration options. -*Additional documentation coming soon!* +*This documentation will be updated closer to release.*