js-cookie

KO | EN

gitlite — search

#python #javascript #php #ruby #hacktoberfest #scala #events #blog #plugin #shell #grammar #video

★ 22,595 Open GitHub ↗

클라이언트 사이드에서 쿠키를 처리하기 위한 간단하고 가벼운 JavaScript API입니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

![](https://cloud.githubusercontent.com/assets/835857/14581711/ba623018-0436-11e6-8fce-d2ccd4d379c9.gif)

# JavaScript Cookie [![CI](https://github.com/js-cookie/js-cookie/actions/workflows/ci.yml/badge.svg)](https://github.com/js-cookie/js-cookie/actions/workflows/ci.yml) [![npm](https://img.shields.io/github/package-json/v/js-cookie/js-cookie)](https://www.npmjs.com/package/js-cookie) [![size](https://img.shields.io/bundlephobia/minzip/js-cookie/3)](https://www.npmjs.com/package/js-cookie) [![jsDelivr Hits](https://data.jsdelivr.com/v1/package/npm/js-cookie/badge?style=rounded)](https://www.jsdelivr.com/package/npm/js-cookie)
클라이언트 측에서 쿠키를 다루기 위한 간단하고 가벼운 JavaScript API입니다.
- 광범위한 브라우저 지원
- [모든](#encoding) 문자 허용
- [철저하게](#test) 테스트됨
- 의존성 없음
- ES 및 AMD/CommonJS 모듈 모두 지원
- [RFC 6265](https://tools.ietf.org/html/rfc6265) 준수
- 유용한 [Wiki](https://github.com/js-cookie/js-cookie/wiki) 제공
- [사용자 정의 인코딩/디코딩](#converters) 활성화
- \*\*< 800 바이트\*\* (gzip 압축 기준)!
\*\*👉👉 만약 https://github.com/js-cookie/js-cookie에서 이 내용을 보고 계신다면, main 브랜치의 문서를 읽고 계신 것입니다.
[최신 릴리스의 문서를 확인하세요.](https://github.com/js-cookie/js-cookie/tree/latest#readme) 👈👈\*\*
## 설치 (Installation)
### NPM
```bash
npm i js-cookie
```
npm 패키지는 주로 ES 모듈을 지원하는 번들러를 위해 라이브러리의 ES 모듈 변종을 가리키는 `module` 필드를 가지고 있으며, 하위 호환성을 위해 UMD 모듈을 가리키는 `browser` 필드도 함께 제공합니다.
\_아직 모든 브라우저가 네이티브로 ES 모듈을 지원하지는 않습니다\_. 이러한 이유로 npm 패키지/릴리스는 ES와 UMD 모듈 변종을 모두 제공하며, 이에 대비하여 UMD 폴백과 함께 ES 모듈을 포함할 수 있습니다:
### CDN
또는 [jsDelivr CDN](https://www.jsdelivr.com/package/npm/js-cookie)을 통해 js-cookie를 포함할 수 있습니다.
## 기본 사용법 (Basic Usage)
라이브러리 불러오기:
```javascript
import Cookies from 'js-cookie'
// 또는
const Cookies = require('js-cookie')
```
사이트 전체에서 유효한 쿠키 생성:
```javascript
Cookies.set('name', 'value')
```
지금부터 7일 동안 유지되며 사이트 전체에서 유효한 쿠키 생성:
```javascript
Cookies.set('name', 'value', { expires: 7 })
```
현재 페이지의 경로에서 유효하고 만료되는 쿠키 생성:
```javascript
Cookies.set('name', 'value', { expires: 7, path: '' })
```
쿠키 읽기:
```javascript
Cookies.get('name') // => 'value'
Cookies.get('nothing') // => undefined
```
표시되는 모든 쿠키 읽기:
```javascript
Cookies.get() // => { name: 'value' }
```
\_참고: 쿠키를 작성할 때 사용되었을 수도 있고 아닐 수도 있는 쿠키 속성 중 하나를 전달하여 특정 쿠키를 읽는 것은 불가능합니다:\_
```javascript
Cookies.get('foo', { domain: 'sub.example.com' }) // `domain`은 아무런 효과가 없습니다...!
```
이름이 `foo`인 쿠키는 코드가 호출된 위치에서 볼 수 있는 경우에만 `.get()`을 통해 사용할 수 있으며, 읽을 때 도메인 및/또는 경로 속성은 영향을 미치지 않습니다.
쿠키 삭제:
```javascript
Cookies.remove('name')
```
현재 페이지의 경로에서 유효한 쿠키 삭제:
```javascript
Cookies.set('name', 'value', { path: '' })
Cookies.remove('name') // 실패!
Cookies.remove('name', { path: '' }) // 삭제됨!
```
\_중요! 쿠키를 삭제할 때 [기본 속성](#cookie-attributes)에 의존하지 않는 경우, 쿠키를 설정할 때 사용했던 것과 정확히 동일한 `path`, `domain`, `secure`, `sameSite` 속성을 전달해야 합니다:\_
```javascript
Cookies.remove('name', { path: '', domain: '.yourdomain.com', secure: true })
```
\_참고: 존재하지 않는 쿠키를 제거해도 예외가 발생하지 않으며 어떤 값도 반환되지 않습니다.\_
## 네임스페이스 충돌 (Namespace conflicts)
`Cookies` 네임스페이스와 충돌할 위험이 있는 경우, `noConflict` 메서드를 사용하면 새 네임스페이스를 정의하고 원래 네임스페이스를 유지할 수 있습니다. 이는 위젯이나 SDK의 일부 등으로 타사 사이트에서 스크립트를 실행할 때 특히 유용합니다.
```javascript
// js-cookie api를 다른 변수에 할당하고 원래의 네임스페이스 복원하기
```

nal "window.Cookies"
var Cookies2 = Cookies.noConflict()
Cookies2.set('name', 'value')
```
\_참고: AMD 또는 CommonJS를 사용할 때는 `.noConflict` 메서드가 필요하지 않으므로, 해당 환경에서는 노출되지 않습니다.\_
## 인코딩
이 프로젝트는 [RFC 6265](http://tools.ietf.org/html/rfc6265#section-4.1.1)를 준수합니다. 쿠키 이름이나 쿠키 값에 허용되지 않는 모든 특수 문자는 [percent-encoding](http://en.wikipedia.org/wiki/Percent-encoding)을 사용하여 각각의 UTF-8 16진수 값으로 인코딩됩니다.
쿠키 이름 또는 쿠키 값에 허용되면서 여전히 인코딩되는 유일한 문자는 퍼센트 `%` 문자이며, 퍼센트 입력을 리터럴로 해석하기 위해 이스케이프됩니다.
기본 인코딩/디코딩 전략은 [js-cookie에 의해 읽히고 쓰여진 쿠키 간에만](https://github.com/js-cookie/js-cookie/pull/200#discussion\_r63270778) 상호 호환되도록 만들어졌습니다. 기본 인코딩/디코딩 전략을 재정의하려면 [컨버터](#converters)를 사용해야 합니다.
\_참고: [RFC 6265](https://tools.ietf.org/html/rfc6265#section-6.1)에 따라, 쿠키가 너무 크거나 동일한 도메인에 쿠키가 너무 많으면 삭제될 수 있습니다. [자세한 내용은 여기에서 확인할 수 있습니다](https://github.com/js-cookie/js-cookie/wiki/Frequently-Asked-Questions#why-are-my-cookies-being-deleted).\_
## 쿠키 속성
쿠키 속성 기본값은 `withAttributes()`를 통해 API 인스턴스를 생성하여 전역으로 설정하거나, 마지막 인수로 일반 객체를 전달하여 `Cookies.set(...)`을 호출할 때마다 개별적으로 설정할 수 있습니다. 호출별 속성은 기본 속성보다 우선합니다.
### expires
쿠키가 삭제될 시점을 정의합니다. 값은 생성 시점부터의 일수로 해석될 수 있는 [`Number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global\_Objects/Number)이거나 [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global\_Objects/Date) 인스턴스여야 합니다. 생략할 경우, 쿠키는 세션 쿠키가 됩니다.
하루보다 짧은 시간 동안 유지되는 쿠키를 생성하려면 [위키의 FAQ](https://github.com/js-cookie/js-cookie/wiki/Frequently-Asked-Questions#expire-cookies-in-less-than-a-day)를 확인하세요.
\*\*기본값:\*\* 사용자가 브라우저를 닫을 때 쿠키가 삭제됩니다.
\*\*예시:\*\*
```javascript
Cookies.set('name', 'value', { expires: 365 })
Cookies.get('name') // => 'value'
Cookies.remove('name')
```
### path
쿠키가 표시되는 경로를 나타내는 [`String`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global\_Objects/String)입니다.
\*\*기본값:\*\* `/`
\*\*예시:\*\*
```javascript
Cookies.set('name', 'value', { path: '' })
Cookies.get('name') // => 'value'
Cookies.remove('name', { path: '' })
```
\*\*Internet Explorer 관련 참고 사항:\*\*
> 기본 WinINET InternetGetCookie 구현의 모호한 버그로 인해, IE의 document.cookie는 파일 이름이 포함된 경로 속성으로 설정된 경우 쿠키를 반환하지 않습니다.
([Internet Explorer 쿠키 내부 구조 (FAQ)](http://blogs.msdn.com/b/ieinternals/archive/2009/08/20/wininet-ie-cookie-internals-faq.aspx)에서 발췌)
즉, `/check.html`과 같이 파일 이름이 포함된 경로인 경우 `window.location.pathname`을 사용하여 경로를 설정할 수 없습니다(최소한 해당 쿠키는 올바르게 읽을 수 없습니다).
실제로 신뢰할 수 없는 입력값이 쿠키 속성을 설정하도록 허용해서는 안되며, 그렇지 않으면 [XSS 공격](https://github.com/js-cookie/js-cookie/issues/396)에 노출될 수 있습니다.
### domain
쿠키가 표시되어야 하는 유효한 도메인을 나타내는 [`String`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global\_Objects/String)입니다. 쿠키는 모든 서브도메인에서도 표시됩니다.
\*\*기본값:\*\* Internet Explorer를 제외하고, 쿠키가 생성된 페이지의 도메인 또는 서브도메인에서만 쿠키가 표시됩니다(아래 참조).
\*\*예시:\*\*
`site.com`에서 쿠키가 생성되는 경우를 가정해 보겠습니다:
```javascript
Cookies.set('name', 'value', { domain: 'subdomain.site.com' })
Cookies.get('name') // => und

efined ('subdomain.site.com'에서 읽어야 함)
```
\*\*Internet Explorer 기본 동작에 대한 참고 사항:\*\*
> Q3: 쿠키에 DOMAIN 속성을 지정하지 않으면, IE는 어쨌든 모든 중첩된 서브도메인으로 쿠키를 전송하나요?
> A: 네, example.com에 설정된 쿠키는 sub2.sub1.example.com으로 전송됩니다.
> Internet Explorer는 이 점에서 다른 브라우저들과 다릅니다.
([Internet Explorer Cookie Internals (FAQ)](http://blogs.msdn.com/b/ieinternals/archive/2009/08/20/wininet-ie-cookie-internals-faq.aspx)에서 발췌)
즉, `domain` 속성을 생략하면 IE에서는 서브도메인에서 쿠키가 보인다는 뜻입니다.
### secure
`true` 또는 `false` 중 하나이며, 쿠키 전송 시 보안 프로토콜(https)이 필요한지 여부를 나타냅니다.
\*\*기본값:\*\* 보안 프로토콜 요구사항 없음.
\*\*예시:\*\*
```javascript
Cookies.set('name', 'value', { secure: true })
Cookies.get('name') // => 'value'
Cookies.remove('name')
```
### partitioned
`true` 또는 `false` 중 하나이며, 쿠키가 파티셔닝된 스토리지(partitioned storage)를 사용할지 여부를 나타냅니다. `secure: true`도 함께 설정해야 합니다.
\*\*기본값:\*\* 파티셔닝된 스토리지 사용 안 함.
\*\*예시:\*\*
```javascript
Cookies.set('name', 'value', { partitioned: true })
Cookies.get('name') // => 'value'
Cookies.remove('name')
```
### sameSite
브라우저가 크로스 사이트 요청(cross-site requests)과 함께 쿠키를 보낼지 여부를 제어할 수 있게 해주는 [`String`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global\_Objects/String)입니다.
기본값: 설정되지 않음.
\*\*최신 브라우저는 여기서 아무것도 지정하지 않아도 "Lax"를 기본값으로 설정하고 있다는 점에 유의하세요.\*\*
\*\*예시:\*\*
```javascript
Cookies.set('name', 'value', { sameSite: 'strict' })
Cookies.get('name') // => 'value'
Cookies.remove('name')
```
### 기본값 설정하기
```javascript
const api = Cookies.withAttributes({ path: '/', domain: '.example.com' })
```
## Converters
### Read
기본 디코딩 구현을 재정의하는 새로운 api 인스턴스를 생성합니다. `Cookies.get()` 및 `Cookies.get('name')`과 같이 올바른 디코딩이 필요한 모든 get 메서드는 각 쿠키에 대해 지정된 컨버터를 실행합니다. 반환된 값은 쿠키 값으로 사용됩니다.
`escape` 함수를 사용해서만 디코딩할 수 있는 쿠키 중 하나를 읽는 예시:
```javascript
document.cookie = 'escaped=%u5317'
document.cookie = 'default=%E5%8C%97'
var cookies = Cookies.withConverter({
read: function (value, name) {
if (name === 'escaped') {
return unescape(value)
}
// 다른 모든 쿠키는 기본값으로 폴백
return Cookies.converter.read(value, name)
}
})
cookies.get('escaped') // 北
cookies.get('default') // 北
cookies.get() // { escaped: '北', default: '北' }
```
### Write
기본 인코딩 구현을 재정의하는 새로운 api 인스턴스를 생성합니다:
```javascript
Cookies.withConverter({
write: function (value, name) {
return value.toUpperCase()
}
})
```
## TypeScript declarations
```bash
npm i @types/js-cookie
```
## Server-side integration
[Servers Docs](SERVER\_SIDE.md)를 확인하세요.
## Contributing
[Contributing Guidelines](CONTRIBUTING.md)을 확인하세요.
## Releasing
릴리스는 `Release` GitHub Actions 워크플로(OIDC를 사용한 신뢰할 수 있는 퍼블리싱)를 통해 생성해야 합니다.
GitHub 릴리스는 초안(draft)으로 생성되므로 수동으로 게시해야 합니다! (그래야 게시 전에 적절한 릴리스 노트를 작성할 수 있습니다.)
## Supporters

[![](https://raw.githubusercontent.com/wiki/js-cookie/js-cookie/Browserstack-logo%402x.png)](https://www.browserstack.com/)

무제한 브라우저 테스트를 무료로 제공해 주신 [BrowserStack](https://www.browserstack.com/)에 깊은 감사를 드립니다.
## 작성자
- [Klaus Hartl](https://github.com/carhartl)
- [Fagner Brack](https://github.com/FagnerMartinsBrack)
- 그리고 멋진 [기여자들](https://github.com/js-cookie/js-cookie/graphs/contributors)

js-cookie

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README