Skip to content

Commit

Permalink
docs: update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
Pooya Parsa committed Jan 30, 2018
1 parent 8e5a55b commit 93255d5
Showing 1 changed file with 173 additions and 101 deletions.
274 changes: 173 additions & 101 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,147 +1,219 @@
# Auth Module
<h1 align="center">Auth</h1>

<p align="center">Authentication module for Nuxt.js</p>

<p align="center">
<a href="https://david-dm.org/nuxt-community/auth-module">
<img alt="" src="https://david-dm.org/nuxt-community/auth-module/status.svg?style=flat-square">
</a>
<a href="https://standardjs.com">
<img alt="" src="https://img.shields.io/badge/code_style-standard-brightgreen.svg?style=flat-square">
</a>
<a href="https://circleci.com/gh/nuxt-community/auth-module">
<img alt="" src="https://img.shields.io/circleci/project/github/nuxt-community/auth-module.svg?style=flat-square">
</a>
<a href="https://codecov.io/gh/nuxt-community/auth-module">
<img alt="" src="https://img.shields.io/codecov/c/github/nuxt-community/auth-module.svg?style=flat-square">
</a>
<br>
<a href="https://npmjs.com/package/@nuxtjs/auth">
<img alt="" src="https://img.shields.io/npm/v/@nuxtjs/auth/latest.svg?style=flat-square">
</a>
<a href="https://npmjs.com/package/@nuxtjs/auth">
<img alt="" src="https://img.shields.io/npm/dt/@nuxtjs/auth.svg?style=flat-square">
</a>
</p>

[![npm (scoped with tag)](https://img.shields.io/npm/v/@nuxtjs/auth/latest.svg?style=flat-square)](https://npmjs.com/package/@nuxtjs/auth)
[![npm](https://img.shields.io/npm/dt/@nuxtjs/auth.svg?style=flat-square)](https://npmjs.com/package/@nuxtjs/auth)
[![CircleCI](https://img.shields.io/circleci/project/github/nuxt-community/auth-module.svg?style=flat-square)](https://circleci.com/gh/nuxt-community/auth-module)
[![Codecov](https://img.shields.io/codecov/c/github/nuxt-community/auth-module.svg?style=flat-square)](https://codecov.io/gh/nuxt-community/auth-module)
[![Dependencies](https://david-dm.org/nuxt-community/auth-module/status.svg?style=flat-square)](https://david-dm.org/nuxt-community/auth-module)
[![js-standard-style](https://img.shields.io/badge/code_style-standard-brightgreen.svg?style=flat-square)](http://standardjs.com)
[📖 **Release Notes**](./CHANGELOG.md)

> Authentication module for Nuxt.js
If you are coming from an older release please be sure to read [Migration Guide](https://github.com/nuxt-community/auth-module/wiki/Migration-guide).

[📖 **Release Notes**](./CHANGELOG.md)
<h2 align="center">Setup</h2>

Install with yarn:

## Setup
- Add `@nuxtjs/auth` dependency using yarn or npm to your project
- Add `@nuxtjs/auth` and `@nuxtjs/axios` to `modules` section of `nuxt.config.js`
```bash
yarn add @nuxtjs/auth @nuxtjs/axios
```

Install with npm:

```bash
npm install @nuxtjs/auth @nuxtjs/axios
```

Edit `nuxt.js.config`:

```js
{
modules: [
'@nuxtjs/auth',

// ...Axios module should be included AFTER @nuxtjs/auth
'@nuxtjs/axios'
'@nuxtjs/axios', // <-- Should be before @nuxtjs/auth
'@nuxtjs/auth'
],
// Default Values

auth: {
user: {
endpoint: 'auth/user',
propertyName: 'user',
resetOnFail: true,
enabled: true,
method: 'GET',
},
login: {
endpoint: 'auth/login',
},
logout: {
endpoint: 'auth/logout',
method: 'GET',
},
redirect: {
guest: true,
user: true,
notLoggedIn: '/login',
loggedIn: '/'
},
token: {
enabled: true,
type: 'Bearer',
localStorage: true,
name: 'token',
cookie: true,
cookieName: 'token'
},
errorHandler: {
fetch: null,
logout: null
}
// Options
}
```
<h2 align="center">Auth Middleware</h2>
```js
// ... in nuxt.config.js ...
router: {
middleware: [
'auth',
]
}
```
## Options
### Components Exclusion
#### user
You can set a `guarded` option to false in a specific component and the middleware will ignore this component.
```js
export default {
options: {
guarded: false,
}
}
```
<h2 align="center">Options</h2>
### `user`
Sets the global settings for store **fetch** action.
* **endpoint** - Set the URL of the user data endpoint. It can be a relative or absolute path.
* **propertyName** - Set the name of the return object property that contains the user data. If you want the entire object returned, set an empty string.
* **resetOnFail** - Automatically invalidate all tokens if user fetch fails. (Default is `true`)
* **method** - Set the request to POST or GET.
#### login
`endpoint`
Set the URL of the user data endpoint. It can be a relative or absolute path.
`propertyName`
Set the name of the return object property that contains the user data. If you want the entire object returned, set an empty string.
`resetOnFail`
- Default: `true`
Automatically invalidate all tokens if user fetch fails.
`method`
Set the request to POST or GET.
### `login`
Set the global settings for store **login** action.
* **endpoint** - Set the URL of the login endpoint. It can be a relative or absolute path.
#### logout
`endpoint`
Set the URL of the login endpoint. It can be a relative or absolute path.
### `logout`
Sets the global settings for store **logout** action.
* **endpoint** - Set the URL of the logout endpoint. It can be a relative or absolute path.
* **method** - Set the request to POST or GET.
#### token
* **enabled** (Boolean) - Get and use tokens for authentication.
* **type** - Sets the token type of the authorization header.
* **localStorage**(Boolean) - Keeps token in local storage, if enabled.
* **name** - Set the token name in the local storage.
* **cookie** (Boolean) - Keeps token in cookies, if enabled.
* **cookieName** - Set the token name in Cookies.
`endpoint`
Set the URL of the logout endpoint. It can be a relative or absolute path.
`method`
#### redirect
* **guest** (Boolean) - Sets if the middleware should redirect guests users (unauthenticated). Only when `auth` middleware is added to a page.
* **user** (Boolean) - Sets if the middleware should redirect logged users (authenticated). Only when `auth` middleware is added to a page.
* **notLoggedIn** (Boolean) - Sets the redirect URL default of the users not logged in. Only when `auth` middleware is added to a page.
* **loggedIn** (Boolean) - Sets the redirect URL default of the users logged in. Only when `auth` middleware is added to a page.
Set the request to POST or GET.
### `token`
`enabled`
#### errorHandler
* **fetch** (Function(context, error)) - Function will be called when fetch get an exception.
* **logout** (Function(context, error)) - Function will be called when logout get an exception.
Get and use tokens for authentication.
## Example usage
`type`
Sets the token type of the authorization header.
`localStorage`
If set to `true`, Keeps token in local storage.
`name`
Set the token name in the local storage.
`cookie`
Keeps token in cookies, if enabled.
`cookieName`
Set the token name in Cookies.
### `redirect`
`guest`
Sets if the middleware should redirect guests users (unauthenticated). Only when `auth` middleware is added to a page.
`user`
Sets if the middleware should redirect logged users (authenticated). Only when `auth` middleware is added to a page.
`notLoggedIn`
Sets the redirect URL default of the users not logged in. Only when `auth` middleware is added to a page.
`loggedIn`
Sets the redirect URL default of the users logged in. Only when `auth` middleware is added to a page.
### `errorHandler`
`fetch`
- Type: `Function(context, error)`
Function will be called when fetch get an exception.
`logout`
- Type: `Function(context, error)`
Function will be called when logout get an exception.
<h2 align="center">Snippets</h2>
Do a password based login:
```js
// ... code ...
// Do a password based login
store.dispatch('auth/login', {
this.$store.dispatch('auth/login', {
fields: {
username: 'your_username',
password: 'your_password'
}
})
```
// ... code ...
store.dispatch('auth/logout') // run logout
Logout:
// ... code ...
store.state.auth.token // get access token
```js
this.$store.dispatch('auth/logout')
```
// ... code ...
store.state.auth.user // get user data
Get access token:
// ... code ...
store.getters['auth/loggedIn'] // get login status (true or false)
```js
console.log($store.state.auth.token)
```
## Middleware
Get user data:
```js
// ... in nuxt.config.js ...
router: {
middleware: [
'auth',
]
}
console.log($store.state.auth.user)
```
### Middleware Components Exclusion
You can set a `guarded` option to false in a specific component and the middleware will now ignore this component.
Get login status (Boolean):
```js
export default {
options: {
guarded: false,
}
}
store.getters['auth/loggedIn']
```
## License
Expand Down

0 comments on commit 93255d5

Please sign in to comment.