https://github.com/gravitano/vue-auth
Authentication library for Vue 3
https://github.com/gravitano/vue-auth
authentication axios vue vue-auth
Last synced: about 2 months ago
JSON representation
Authentication library for Vue 3
- Host: GitHub
- URL: https://github.com/gravitano/vue-auth
- Owner: gravitano
- Created: 2021-09-14T07:56:11.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2022-08-23T09:54:29.000Z (almost 3 years ago)
- Last Synced: 2025-04-09T23:14:22.123Z (about 2 months ago)
- Topics: authentication, axios, vue, vue-auth
- Language: TypeScript
- Homepage: https://vue-auth-demo.vercel.app/
- Size: 213 KB
- Stars: 7
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# Auth
> Authentication Plugin for Vue 3
- [Auth](#auth)
- [Demo](#demo)
- [Dependencies](#dependencies)
- [Installation](#installation)
- [Usage](#usage)
- [Use as Vue Plugin](#use-as-vue-plugin)
- [Use with Composition API](#use-with-composition-api)
- [`login(payload: Object): Promise`](#loginpayload-object-promiseaxiosresponse)
- [`fetchUser(): Promise`](#fetchuser-promiseaxiosresponse)
- [`setToken(tokenData: string): void`](#settokentokendata-string-void)
- [`setUser(userData: Object): void`](#setuseruserdata-object-void)
- [`logout(): boolean`](#logout-boolean)
- [`forceLogout(): boolean`](#forcelogout-boolean)
- [`user: Object`](#user-object)
- [`loggedIn: boolean`](#loggedin-boolean)
- [Manually Creating The Auth Function](#manually-creating-the-auth-function)
- [Default Options](#default-options)
- [Options](#options)
- [`endpoints`](#endpoints)
- [`token`](#token)
- [`user`](#user)
- [`moduleName`](#modulename)
- [`expiredStorage`](#expiredstorage)
- [`redirect`](#redirect)
- [`registerAxiosInterceptors`](#registeraxiosinterceptors)
- [`storage`](#storage)
- [Implementing Refresh Token](#implementing-refresh-token)
- [Refresh Token Options](#refresh-token-options)
- [`enabled`](#enabled)
- [`property`](#property)
- [`maxAge`](#maxage)
- [`storageName`](#storagename)
- [`name`](#name)
- [`autoLogout`](#autologout)
- [License](#license)
## Demo
- Checkout online demo [here](https://vue-auth-demo.vercel.app/)
- View example project [here](https://github.com/gravitano/volar-starter)
## Dependencies
- [axios](https://github.com/axios/axios): Used as the default http client.
- [Vuex](https://next.vuex.vuejs.org/): Used to store auth `state`.
- [Vou Router](https://next.vuex.vuejs.org/): Used to redirect between pages.
- [TypeScript](https://www.typescriptlang.org/): Written in TypeScript, optimize for Vue + TypeScript. But, also ship ESM and Common JS version on `dist`.
## Installation
Install the package just like regular npm package.
```bash
npm i @gravitano/vue-auth
# OR
yarn add @gravitano/vue-auth
```
## Usage
### Use as Vue Plugin
Install the plugin to your Vue app.
```js
// main.js
import {createApp} from 'vue';
import Auth from '@gravitano/vue-auth'; // 👈 import the plugin
import store from '~/store'
import router from '~/router'
import axios from 'axios'
const app = createApp(App);
app.use(Auth); // 👈 use the plugin
// or with custom options
// 👇
app.use(Auth, {
options, // auth options
store, // vuex store instance
axios, // axios instance
router // vue router instance
}); // 👈 use the plugin
app.mount('#app');
```
After that, you can access the plugin via `$auth` global property.
```html
Logged In as : {{ $auth.user.name }}
```
If you are using composition API, you can also access the `auth` object by using `inject` method.
```js
import {injectAuth} from '@gravitano/vue-auth'
// user is Ref
const {user} = injectAuth()
// access the user
console.log(user)
```
### Use with Composition API
To use the auth in composition API, just import and use the `useAuth` function.
```ts
import {useAuth} from '@gravitano/vue-auth';
const auth = useAuth();
// OR with object destruction
const {user} = useAuth();
```
#### `login(payload: Object): Promise`
Login the user and save token to the auth storage.
```js
auth.login({
email: '[email protected]',
password: 'admin',
});
```
#### `fetchUser(): Promise`
Fetch user data from API.
```js
const user = await auth.fetchUser();
console.log(user);
```
#### `setToken(tokenData: string): void`
Manually Set User Token.
```js
auth.setToken(token);
```
#### `setUser(userData: Object): void`
Manually set the user data.
```js
const userData = {
id: 1,
name: 'Admin',
};
auth.setUser(userData);
```
#### `logout(): boolean`
Logout the current user.
```js
auth.logout();
```
#### `forceLogout(): boolean`
Force logout the current user.
```js
auth.forceLogout();
```
#### `user: Object`
Get the current user data.
```js
console.log(auth.user);
```
#### `loggedIn: boolean`
Get the current logged in state.
```js
console.log(auth.loggedIn);
```
### Manually Creating The Auth Function
First, create `auth.ts` file under your `src/plugins` folder.
```ts
import {authOptions} from '~/config';
import store, {AppRootState} from '~/store';
import {createAuth} from '@gravitano/vue-auth';
import axios from 'axios';
import router from '~/router';
export const useAuth = () => createAuth(authOptions, axios, store, router);
```
Then, in your component, just import and use it as regular composition function. For example:
```vue
import {useAuth} from '~/plugins/auth'
// destruct user object from `useAuth` function
const {user} = useAuth();
console.log(user); // <-- user data
```
## Default Options
This is the default options object:
```ts
import { AuthOptions } from '@gravitano/vue-auth'
export const defaultOptions: AuthOptions = {
endpoints: {
login: {
url: '/auth/login',
method: 'post',
},
logout: {
url: '/auth/logout',
method: 'delete',
},
user: {
url: '/auth/me',
method: 'get',
},
},
token: {
property: 'data.token',
type: 'Bearer',
storageName: 'auth.token',
autoDecode: false,
name: 'Authorization',
},
user: {
autoFetch: true,
property: 'data',
storageName: 'auth.user',
},
moduleName: 'auth',
expiredStorage: 'auth.expired',
redirect: {
home: '/',
login: '/auth/login',
},
registerAxiosInterceptors: true,
storage: {
driver: 'secureLs', // supported: cookie, local, secureLs (secure local storage)
},
};
```
## Options
### `endpoints`
- #### `login`
- `url`: Login path. E.g. `/user/login`
- `method`: HTTP Method. E.g. `GET`, `POST`, etc.
- #### `logout`
- `url`: Logout path. E.g. `/user/logout`
- `method`: HTTP Method. E.g. `GET`, `POST`, etc.
- #### `user`
- `url`: Endpoint for getting user data. E.g. `/my/profile`
- `method`: HTTP Method. E.g. `GET`, `POST`, etc.
### `token`
- #### `property`
Token property path using dot notation.
- Type: `string`
- Default: `data.token`
- #### `type`
Token type.
- Type: `string`
- Default: `Bearer`
- #### `storageName`
Token storage name.
- Type: `string`
- Default: `auth.token`
- #### `autoDecode`
Auto decodes token when possible. Usually used when using JWT Token.
- Type: `boolean`
- Default: `true`
- #### `name`
Token header name.
- Type: `string`
- Default:`Authorization`
### `user`
- #### `autoFetch`
Fetch user data automatically when user successfully logged in.
- Type: `boolean`
- Default: `true`
- #### `property`
Property path of user data.
- Type: `string`
- Default: `data`
- #### `storageName`
Storage name for storing user data.
- Type: `string`
- Default: `auth.user`
### `moduleName`
Vuex's module name.
- Default: `auth`
- Type: `string`
### `expiredStorage`
Storage name for storing token expiratin time.
- Type: `string`
- Default: `auth.expired`
### `redirect`
- #### `home`
Homepage path.
- Type: `string`
- Default: `/`
- #### `login`
Login path.
- Type: `string`
- Default: `/`
### `registerAxiosInterceptors`
Register custom axios interceptors when `true`. Set the value to `false` if you want to use your own interceptors.
- Type: `boolean`
- Default: `true`
### `storage`
- #### `driver`
- Type: `string`
- Default: `secureLs`
- Available Options: `local` | `secureLs` | `cookie`
## Implementing Refresh Token
To implement refresh token, update your auth options like so:
```diff
import { AuthOptions } from '@gravitano/vue-auth'
export const defaultOptions: AuthOptions = {
endpoints: {
login: {
url: '/auth/login',
method: 'post',
},
logout: {
url: '/auth/logout',
method: 'delete',
},
user: {
url: '/auth/me',
method: 'get',
},
+ refresh: {
+ url: '/auth/refresh_token',
+ method: 'get',
+ },
},
token: {
property: 'data.token',
type: 'Bearer',
storageName: 'auth.token',
autoDecode: false,
name: 'Authorization',
},
user: {
autoFetch: true,
property: 'data',
storageName: 'auth.user',
},
moduleName: 'auth',
expiredStorage: 'auth.expired',
redirect: {
home: '/',
login: '/auth/login',
},
registerAxiosInterceptors: true,
storage: {
driver: 'secureLs', // supported: cookie, local, secureLs (secure local storage)
},
+ refreshToken: {
+ enabled: true, // <-- make sure the value is set to true
+ property: 'data',
+ maxAge: 60 * 60 * 24 * 30, // default 30 days
+ storageName: 'auth.refresh_token',
+ name: 'refresh_token',
+ autoLogout: true,
+ },
};
```
### Refresh Token Options
#### `enabled`
Indicates the refresh token is enabled or not.
- Type: `string`
- Default: `false`
#### `property`
Path of refresh token property from the response.
- Type: `string`
- Default: `data.refresh_token`
#### `maxAge`
Maximum age of new token.
- Type: `number`
- Default: `60 * 60 * 24 * 30` (30 Days)
#### `storageName`
Storage name for storing refresh token data.
- Type: `string`
- Default: `auth.refresh_token`
#### `name`
Payload name to sent when refreshing token.
- Type: `string`
- Default: `refresh_token`
#### `autoLogout`
When `true`, user will forced to logout and login again when refresh token failed.
- Type: `boolean`
- Default: `true`
## License
[MIT](https://opensource.org/licenses/MIT)