@stanlemon/react-couchdb-authentication

React CouchDB Authentication Component

React component for streamlining user authentication against an Apache CouchDB instance. If you're building a React application and want to let the amazing CouchDB be your backend, you can take advantage of CouchDB's userdb feature, and with this component streamline using CouchDB to sign up and login users to a secure application. Each user's database is replicated locally to a PouchDB instance that you can use to wrok with documents.

Getting Started

First add the component to your application. You should also have React and PouchDB installed.

npm install --save @stanlemon/react-couchdb-authentication pouchdb react

You will need an instance of CouchDB. If you don't have one, the CouchDB install docs will take care of you. In your CouchDB config you will need to enable couch_user.enable and couch_user.delete_dbs. You can do this through Fauxton, CouchDB's excellent UI or with the following commands:

curl -X PUT localhost:5984/_node/_local/_config/couch_peruser/enable -d "\"true\""
curl -X PUT localhost:5984/_node/_local/_config/couch_peruser/delete_dbs -d "\"true\""

Enabling these settings ensures that once a user signs up, their dedicated database is setup (and vice versa when their user is deleted).

You will also need to ensure that the _user database is created and can be written to by any user. Note that the security of this database changed in CouchDB 3, so it's not open by default anymore.

It is highly recommended that you setup a proxy to your couchdb instance so that your webapp and the instance can be accessed through the same domain. That is how the example app works.

Example

The <Authentication/> component is easy to use, simply wrap your <App /> and use the provided <Login /> and <SignUp /> components to get going. You can customize your login and signup views later.

<Authentication
  url="http://localhost:5984"
  login={<Login />}
  signup={<SignUp />}
>
  <h1>Authenticated!</h1>
</Authentication>

Want an easier way to see this in action? Clone the repository, and checkout the example folder. You can run npm start inside of it and see a fully functioning implementation of the components.

The <Login /> and <SignUp /> components are actually containers that provide some simple setters that are supplied to a view via the component property, which you can customize to look appropriate for your application.

Troubleshooting

Most issues are due to CouchDB being misconfigured, or cookies already being set. If you've pulled up Fauxton in your browser you will want to clear the cookies for your CouchDB instance before using this component.

Debug

This component has a fair amount of logging that can give you better insight into it's behavior. To see that logging you can set debug={true} on the <Authentication/> component and everything will be logged out to the console. Do not do this in production!

Building & Tooling

To get started, you can build the components using Typescript by simply doing:

  npm install
  npm run build

You can lint the source by doing:

  npm run lint

You can run tests by doing:

  npm test

Tests require a working CouchDB instance.

Typescript

If you use Typescript you may run into an issue with the PouchDB types conflicting with the Node types. You can fix this by adding the following to your package.json to override @types/pouchdb-core where the problem exists.

{
  "devDependencies": {
    "@types/pouchdb": "^6.4.2",
    "@types/debug": "^4.1.12"
  },
  "overrides": {
    "@types/pouchdb-core": "npm:@stanlemon/types-pouchdb-core@^0.0.1"
  }
}