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

|Option|Type|Default|Description| |-|-|-|-| |name|string|'cookieSessionId'|Name of the cookie.| |secret|string|'default-secret'|Secret for signing of cookie id. It's recommended to use custom secret.| |genid|Object||Options used for generating of ids. nanoid is used as a generator.| |genid.length|number|21|The length of generated id.| |genid.prefix|string|'s:'|Prefix of signed cookie id.| |api|Object||Options for API endpoints.| |api.enable|boolean|true|Whether to enable API endpoints.| |api.path|string|'/api/cookie-session'|Path for API endpoints.| |storage|Object||Storage options.| |storage.id|string|'cookie-session'|Id of storage used for storing of cookie session data. You can define your own storage under nitro option at nuxt.config.| |storage.keyPrefix|string|''|Prefix of the keys in the storage.| |cookie|Object||Cookie options.| |cookie.path|string|'/'|Path where cookie is available for the server.| |cookie.httpOnly|boolean|true|Whether cookie is accessible throught client side code.| |cookie.maxAge|number|0|TTL of the cookie in seconds. Default value is life cycle of the current browser tab.| |cookie.domain|string|''|Domain where cookie is available.| |cookie.sameSite|string | boolean|'Strict'|Rule for cookie usage defined in MDN docs.| |cookie.secure|boolean|true|Whether cookie is accessible throught https only.|

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.