useCookie

페이지, 구성요소 및 플러그인 내에서 SSR 친화적인 컴포저블인 useCookie 을 사용하여 쿠키를 읽고 쓸 수 있다.

const cookie = useCookie(name, options)

useCookie ref는 쿠키 값을 JSON으로 자동으로 직렬화 및 역직렬화한다.

Example

아래 예에서는 counter 라는 쿠키를 생성한다 . 쿠키가 존재하지 않으면 처음에는 임의의 값으로 설정된다. 변수 counter 를 업데이트할 때마다 그에 따라 쿠키도 업데이트된다.

<!--
app.vue
-->

<script setup lang="ts">
const counter = useCookie('counter')

counter.value = counter.value || Math.round(Math.random() * 1000)
</script>

<template>
  <div>
    <h1>Counter: {{ counter || '-' }}</h1>
    <button @click="counter = null">reset</button>
    <button @click="counter--">-</button>
    <button @click="counter++">+</button>
  </div>
</template>

아래 예는 useCookie API를 사용하여 클라이언트와 서버 모두 사용할 수 있는 소량의 데이터를 유지하는 방법을 보여준다.

<!--
app.vue
-->

<script setup lang="ts">
const user = useCookie<{ name: string }>('user')
const logins = useCookie<number>('logins')

const name = ref('')

const login = () => {
  logins.value = (logins.value || 0) + 1
  user.value = { name: name.value }
}

const logout = () => {
  user.value = null
}
</script>

<template>
  <NuxtExampleLayout class="h-50" example="composables/use-cookie">
    <template v-if="user">
      <h1 class="text-3xl mb-3">
        Welcome, {{ user.name }}! 👋
      </h1>
      <div>
        <NTip n="green6" icon="carbon:idea" class="inline-flex">
          You have logged in <b>{{ logins }} times</b>!
        </NTip>
      </div>
      <div class="mt-3">
        <NButton n="red" icon="carbon:logout" @click="logout">
          Log out
        </NButton>
      </div>
    </template>
    <template v-else>
      <h1 class="text-3xl mb-3">
        Login
      </h1>
      <NTextInput v-model="name" n="lg" class="w-100 m-auto" placeholder="Enter your name..." @keypress.enter="login()" />
      <div class="mt-3">
        <NButton icon="carbon:user" :disabled="!name" @click="login">
          Log in
        </NButton>
      </div>
    </template>
  </NuxtExampleLayout>
</template>

 

옵션

• maxAge / expire : 쿠키 만료 설정
  
  • maxAge :  헤더 Set-Cookie 어트리뷰트의 Max-Age 의 값.
    • type: int (defualt no maximum)
  • expire : 기본적으로 만료 시간은 설정되어 있지 않습니다. 대부분의 클라이언트는 이를 "비영구 쿠키"로 간주하고 웹 브라우저 애플리케이션 종료와 같은 조건에서 삭제합니다.
    
    • type : Date

쿠키 사양에서는 expires 및 maxAge가 모두 설정된 경우 maxAge 가우선 순위를 가지지만 모든 클라이언트가 이를 준수할 수 있는 것은 아니므로 둘 다 설정된 경우 동일한 날짜와 시간을 가리켜야 한다고 명시되어 있다 .

• httpOnly : 헤더 Set-Cookie 어트리뷰트의 HttpOnly 의 값 true 일때 HttpOnly 가 활성화된다. 이 경우 클라이언트에서 document.cookie 로 접근하는 것이 불가능 하다.
  • type : boolean (default not set)
• secure : 헤더 Set-Cookie 어트리뷰트의 Secure 의 값
  • type : boolean (default not set)

브라우저에 HTTPS 연결이 없으면 호환 클라이언트가 나중에 서버에 쿠키를 다시 보내지 않으므로 이 값을 true 로 설정할 때는 주의하자. 이로 인해 하이드레이션 오류가 발생할 수 있다.

• domain : 헤더 Set-Cookie 어트리뷰트의 Domain 값을 지정한다. 기본적으로 도메인은 설정되어 있지 않으며 대부분의 클라이언트는 현재 도메인에만 쿠키를 적용하는 것을 고려해야한다.
• path : 헤더 Set-Cookie 어트리뷰트의 Path 값을 지정한다. 기본적으로 경로는 "기본경로" 이다.
• sameSite : 헤더 Set-Cookie 어트리뷰트의 SameSite 값을 지정한다. boolean 또는 값을 지정한다.
  • true : 엄격한 동일 사이트 적용을 위해 SameSite 속성을 Strict 로 설정한다.
  • false : SameSite 속성을 설정하지 않는다 .
  • 'lax' : 느슨한 동일 사이트 적용을 위해 SameSite 속성을 Lax 로 설정한다.
  • 'none' : 명시적인 크로스 사이트 쿠키에 대한 SameSite 속성을 None 으로 설정한다 .
  • 'strict' : 엄격한 동일 사이트 적용을 위해 SameSite 속성을 Strict 로 설정한다.
• encode : 쿠키 값을 인코딩하는데 사용될 함수를 지정한다. 쿠키 값은 제한된 문자 집합을 갖고 있으므로(단순 문자열이어야 함), 이 함수를 사용하여 값을 쿠키 값에 적합한 문자열로 인코딩할 수 있다. 기본 인코더 함수는 JSON.stringfy + encodeURIComponent 이다.
• decode : 쿠키 값을 디코딩하는 데 사용할 함수를 지정한다. 쿠키 값은 제한된 문자 집합을 가지며(단순 문자열이어야 함) 이 함수를 사용하여 이전에 인코딩된 쿠키 값을 JavaScript 문자열이나 다른 개체로 디코딩할 수 있다. 기본 디코더는 decodeURIComponent+ destr 이다.

위 함수에서 error 가 발생하면 디코드 되지않은 값이 리턴된다.

• default : 쿠키의 기본값을 반환하는 함수를 지정한다. 이 함수는 Ref 를 반환할 수도 있다.
• readonly : 쿠키 값을 설정하지 않고도 쿠키 값에 액세스 할 수 있다.
• watch :  쿠키 ref 데이터에 대한 감시 범위를 boolean 또는 string 값을 지정한다.
  • true : 쿠키 ref 데이터에 대해서 nested 속성까지 감시
  • shallow : 쿠키 ref 데이터에 대해서 한 레벨만 감시
  • false : 쿠키 ref 데이터를 감시하지 않음

예제 1)

<script setup lang="ts">
const user = useCookie(
  'userInfo',
  {
    default: () => ({ score: -1 }),
    watch: false
  }
)

if (user.value && user.value !== null) {
  user.value.score++; // userInfo cookie not update with this change
}
</script>

<template>
  <div>User score: {{ user?.score }}</div>
</template>

예제 2)

<script setup lang="ts">
const list = useCookie(
  'list',
  {
    default: () => [],
    watch: 'shallow'
  }
)

function add() {
  list.value?.push(Math.round(Math.random() * 1000))
  // list cookie not update with this change
}

function save() {
  if (list.value && list.value !== null) {
    list.value = [...list.value]
    // list cookie update with this change
  }
}
</script>

<template>
  <div>
    <h1>List</h1>
    <pre>{{ list }}</pre>
    <button @click="add">Add</button>
    <button @click="save">Save</button>
  </div>
</template>

 

API 경로의 쿠키

패키지 h3  에 포함된 getCookie 와 setCookie 를 사용하여 서버 API 경로에 쿠키를 설정할 수 있다.

// server/api/counter.ts

export default defineEventHandler(event => {
  // Read counter cookie
  let counter = getCookie(event, 'counter') || 0

  // Increase counter cookie by 1
  setCookie(event, 'counter', ++counter)

  // Send JSON response
  return { counter }
})

 

사용 예)

<script setup lang="ts">
const user = useCookie<{ name: string }>('user')
const logins = useCookie<number>('logins')

const name = ref('')

const login = () => {
  logins.value = (logins.value || 0) + 1
  user.value = { name: name.value }
}

const logout = () => {
  user.value = null
}
</script>

<template>
  <NuxtExampleLayout class="h-50" example="composables/use-cookie">
    <template v-if="user">
      <h1 class="text-3xl mb-3">
        Welcome, {{ user.name }}! 👋
      </h1>
      <div>
        <NTip n="green6" icon="carbon:idea" class="inline-flex">
          You have logged in <b>{{ logins }} times</b>!
        </NTip>
      </div>
      <div class="mt-3">
        <NButton n="red" icon="carbon:logout" @click="logout">
          Log out
        </NButton>
      </div>
    </template>
    <template v-else>
      <h1 class="text-3xl mb-3">
        Login
      </h1>
      <NTextInput v-model="name" n="lg" class="w-100 m-auto" placeholder="Enter your name..." @keypress.enter="login()" />
      <div class="mt-3">
        <NButton icon="carbon:user" :disabled="!name" @click="login">
          Log in
        </NButton>
      </div>
    </template>
  </NuxtExampleLayout>
</template>