nuxt-cookie-session v1.0.0-alpha-11

nuxt-cookie-session

Nuxt module that allows you to store user's data on the server side using nitropack storage API and access them by hashed id stored in user's cookies.

The module is inspired by express-session package. Id is randomly generated by nanoid and protected by HMAC crypto algorithm.

Why to use this module?

Cookie is the simplest way for storing of user's data in the browser. Whereas, it's max size is 4096 bytes and cookie headers can increase the size of the request's payload. Regarding that, the common solution is to only save the identifier of the user in the cookie and to store all user's data on the server side. This module helps you to implement session cookie solution in your nuxt application.

Features

• Configurable all cookie options
• Public custom API endpoints
• All storage options available
• Protected ids

Setup

# pnpm
pnpm add nuxt-cookie-session

# npm
npm i nuxt-cookie-session

# yarn
yarn add nuxt-cookie-session

Configuration

Basic

Add module to the nuxt config and define module options under cookieSession property.

// `nuxt.config`
export default defineNuxtConfig({
  modules: ['nuxt-cookie-session'],

  cookieSession: {
    // Recommended for minimal configuration
    secret: 'randomly-generated-secret'
  }
})

Custom storage

// `nuxt.config`
export default defineNuxtConfig({
  modules: ['nuxt-cookie-session'],

  cookieSession: {
    secret: 'randomly-generated-secret',
    storage: {
      id: 'custom-redis-storage',
      keyPrefix: 'my-store-prefix' // optional prefix for all keys stored in the storage
    }
  },
  nitro: {
    storage: {
      'custom-redis-storage': {
        // available drivers are listed at https://unstorage.unjs.io/
        driver: 'redis',
        host: '127.0.0.1',
        // redis driver options
      }
    }
  }
})

You can find more examples in the test directory.

Usage

Use cookie session composable in the component.

<script setup>
const { data, patchData } = useCookieSession()
const username = useState('username', () => data.value?.username ?? '')

const onSubmit = () => patchData({ username: username.value })
</script>

<template>
  <form @submit.prevent="onSubmit">
    <input v-model="username" type="text" />
    <button type="submit">SAVE</button>
  </form>
</template>

Module options

HTTP API

• all session manipulation on the client side are made throught HTTP calls

PUT

• replaces all session data by new ones
• creates new session if it doesn't exist

// session: { name: 'John Doe', age: 35 }

PUT /api/cookie-session { name: 'Another John Doe' }

// session: { name: 'Another John Doe' }

PATCH

• updates existing session data, create new ones if needed
• creates new session if it doesn't exist

// session: { name: 'John Doe' }

PATCH /api/cookie-session { name: 'Another John Doe', age: 35 }

// session: { name: 'Another John Doe', age: 35 }

DELETE

• deletes cookie and all data stored in the storage

// session: { name: 'John Doe' }

DELETE /api/cookie-session

// session: {}

GET

• returns all session data
• does nothing if there is no existing session

Development

• Run pnpm dev:prepare to generate type stubs.
• Use pnpm dev to start playground in development mode.