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.