1 | # NGX Cookie Service
|
2 |
|
3 | <p align="center">
|
4 |
|
5 | ![build](https://github.com/stevermeister/ngx-cookie-service/workflows/CI/badge.svg?branch=master)
|
6 | <a href="https://www.npmjs.com/ngx-cookie-service">
|
7 | <img src="https://img.shields.io/npm/v/ngx-cookie-service.svg?logo=npm&logoColor=fff&label=NPM+package&color=limegreen" alt="Ngx Cookie Service on npm" />
|
8 | </a>
|
9 | <a href="https://gitter.im/ngx-cookie-service/community">
|
10 | <img src="https://badges.gitter.im/ngx-cookie-service/community.svg" alt="Chat in Gitter" />
|
11 | </a>
|
12 | [![ngx-cookie-service channel on discord](https://img.shields.io/discord/873021904708059177.svg?style=flat-square)](https://discord.gg/N3xc4Jfb)
|
13 |
|
14 | </p>
|
15 |
|
16 | Angular service to read, set and delete browser cookies. The experienced team
|
17 | behind [Studytube](https://www.studytube.nl/) will take care of our cookie service from now on.
|
18 |
|
19 | > Note: `ViewEngine` support has been removed on 13.x.x. See [compatability matrix](https://github.com/stevermeister/ngx-cookie-service#supported-versions) for details
|
20 |
|
21 | # Installation
|
22 |
|
23 | ```bash
|
24 | npm install ngx-cookie-service --save
|
25 |
|
26 | # or
|
27 |
|
28 | yarn add ngx-cookie-service
|
29 | ```
|
30 |
|
31 | Add the cookie service to your `app.module.ts` as a provider:
|
32 |
|
33 | ```typescript
|
34 | import { CookieService } from 'ngx-cookie-service';
|
35 |
|
36 | @NgModule({
|
37 | ...
|
38 | providers:
|
39 | [CookieService],
|
40 | ...
|
41 | })
|
42 |
|
43 | export class AppModule {
|
44 | }
|
45 | ```
|
46 |
|
47 | Then, import and inject it into a constructor:
|
48 |
|
49 | ```typescript
|
50 | constructor(private
|
51 | cookieService: CookieService
|
52 | )
|
53 | {
|
54 | this.cookieService.set('Test', 'Hello World');
|
55 | this.cookieValue = this.cookieService.get('Test');
|
56 | }
|
57 | ```
|
58 |
|
59 | That's it!
|
60 |
|
61 | ## Demo
|
62 |
|
63 | https://stackblitz.com/edit/angular-ivy-1lrgdt?file=src%2Fapp%2Fapp.component.ts
|
64 |
|
65 | ## Supported Versions
|
66 |
|
67 | `ViewEngine` support has been removed on 13.x.x. For Angular versions 13.x.x or later use the latest version of the
|
68 | library. For versions <=12.x.x, use 12.0.3 version
|
69 |
|
70 | | Angular Version | Supported Version |
|
71 | | ---------------------- | ----------------- |
|
72 | | 13.x.x or later (Ivy) | 13.x.x or later |
|
73 | | <=12.x.x (View Engine) | 12.0.3 |
|
74 |
|
75 | # API
|
76 |
|
77 | ## check( name: string ): boolean;
|
78 |
|
79 | ```typescript
|
80 | const cookieExists: boolean = cookieService.check('test');
|
81 | ```
|
82 |
|
83 | Checks if a cookie with the given`name` can be accessed or found.
|
84 |
|
85 | ## get( name: string ): string;
|
86 |
|
87 | ```typescript
|
88 | const value: string = cookieService.get('test');
|
89 | ```
|
90 |
|
91 | Gets the value of the cookie with the specified `name`.
|
92 |
|
93 | ## getAll(): {};
|
94 |
|
95 | ```typescript
|
96 | const allCookies: {} = cookieService.getAll();
|
97 | ```
|
98 |
|
99 | Returns a map of key-value pairs for cookies that can be accessed.
|
100 |
|
101 | ## set( name: string, value: string, expires?: number | Date, path?: string, domain?: string, secure?: boolean, sameSite?: 'Lax' | 'Strict' | 'None' ): void;
|
102 |
|
103 | ## set( name: string, value: string, options?: { expires?: number | Date, path?: string, domain?: string, secure?: boolean, sameSite?: 'Lax' | 'None' | 'Strict'}): void;
|
104 |
|
105 | ```typescript
|
106 | cookieService.set('test', 'Hello World');
|
107 | cookieService.set('test', 'Hello World', { expires: 2, sameSite: 'Lax' });
|
108 | ```
|
109 |
|
110 | Sets a cookie with the specified `name` and `value`. It is good practice to specify a path. If you are unsure about the
|
111 | path value, use `'/'`. If no path or domain is explicitly defined, the current location is assumed. `sameSite` defaults
|
112 | to `Lax`.
|
113 |
|
114 | **Important:** For security reasons, it is not possible to define cookies for other domains. Browsers do not allow this.
|
115 | Read [this](https://stackoverflow.com/a/1063760) and [this](https://stackoverflow.com/a/17777005/1007003) StackOverflow
|
116 | answer for a more in-depth explanation.
|
117 |
|
118 | **Important:** Browsers do not accept cookies flagged sameSite = 'None' if secure flag isn't set as well. CookieService
|
119 | will override the secure flag to true if sameSite='None'.
|
120 |
|
121 | ## delete( name: string, path?: string, domain?: string, secure?: boolean, sameSite: 'Lax' | 'None' | 'Strict' = 'Lax'): void;
|
122 |
|
123 | ```typescript
|
124 | cookieService.delete('test');
|
125 | ```
|
126 |
|
127 | Deletes a cookie with the specified `name`. It is best practice to always define a path. If you are unsure about the
|
128 | path value, use `'/'`.
|
129 |
|
130 | **Important:** For security reasons, it is not possible to delete cookies for other domains. Browsers do not allow this.
|
131 | Read [this](https://stackoverflow.com/a/1063760) and [this](https://stackoverflow.com/a/17777005/1007003) StackOverflow
|
132 | answer for a more in-depth explanation.
|
133 |
|
134 | ## deleteAll( path?: string, domain?: string, secure?: boolean, sameSite: 'Lax' | 'None' | 'Strict' = 'Lax' ): void;
|
135 |
|
136 | ```typescript
|
137 | cookieService.deleteAll();
|
138 | ```
|
139 |
|
140 | Deletes all cookies that can currently be accessed. It is best practice to always define a path. If you are unsure about
|
141 | the path value, use `'/'`.
|
142 |
|
143 | # FAQ
|
144 |
|
145 | ## General tips
|
146 |
|
147 | Checking out the following resources usually solves most of the problems people seem to have with this cookie service:
|
148 |
|
149 | - [article about cookies in general @MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies) (recommended read!)
|
150 | - [common localhost problems @StackOverflow](https://stackoverflow.com/questions/1134290/cookies-on-localhost-with-explicit-domain)
|
151 | - [problems with secure cookies @StackOverflow](https://stackoverflow.com/questions/8064318/how-to-read-a-secure-cookie-using-javascript)
|
152 | - [how do browser cookie domains work? @StackOverflow](https://stackoverflow.com/questions/1062963/how-do-browser-cookie-domains-work)
|
153 | - [get cookies from different paths](https://github.com/7leads/ngx-cookie-service/issues/7#issuecomment-351321518)
|
154 |
|
155 | The following general steps are usually very helpful when debugging problems with this cookie service or cookies in
|
156 | general:
|
157 |
|
158 | - check out if there are any [open](https://github.com/stevermeister/ngx-cookie-service/issues)
|
159 | or [closed](https://github.com/stevermeister/ngx-cookie-service/issues?q=is%3Aissue+is%3Aclosed) issues that answer
|
160 | your question
|
161 | - check out the actual value(s) of `document.cookie`
|
162 | - does it work if you use `document.cookie` manually (i.e. in a console of your choice)?
|
163 | - set explicit paths for your cookies
|
164 | - [explain to your local rubber duck why your code should work and why it (probably) does not](https://en.wikipedia.org/wiki/Rubber_duck_debugging)
|
165 |
|
166 | # I am always getting a "token missing" or "no provider" error.
|
167 |
|
168 | Package managers are a well known source of frustration. If you have "token missing" or "no provider" errors, a simple
|
169 | re-installation of your node modules might suffice:
|
170 |
|
171 | ```
|
172 | rm -rf node_modules
|
173 | yarn # or `npm install`
|
174 | ```
|
175 |
|
176 | ## I have a problem with framework X or library Y. What can I do?
|
177 |
|
178 | Please be aware that we cannot help you with problems that are out of scope. For example, we cannot debug a Symfony or
|
179 | Springboot application for you. In that case, you are better off asking the nice folks over
|
180 | at [StackOverflow](https://stackoverflow.com/) for help.
|
181 |
|
182 | ## Do you support Angular Universal?
|
183 |
|
184 | We are working on it. If you are interested in helping us out, see [PR](https://github.com/stevermeister/ngx-cookie-service/pull/177)
|
185 |
|
186 | # Opening issues
|
187 |
|
188 | Please make sure to check out our FAQ before you open a new issue. Also, try to give us as much information as you can
|
189 | when you open an issue. Maybe you can even supply a test environment or test cases, if necessary?
|
190 |
|
191 | # Contributing
|
192 |
|
193 | We are happy to accept pull requests or test cases for things that do not work. Feel free to submit one of those.
|
194 |
|
195 | However, we will only accept pull requests that pass all tests and include some new ones (as long as it makes sense to
|
196 | add them, of course).
|
197 |
|
198 | - [Open a new pull request](https://github.com/stevermeister/ngx-cookie-service/compare)
|
199 |
|
200 | # Author
|
201 |
|
202 | This cookie service is brought to you by [7leads GmbH](http://www.7leads.org/). We built it for one of our apps, because
|
203 | the other cookie packages we found were either not designed "the Angular way" or caused trouble during AOT compilation.
|
204 |
|
205 | # Contributors
|
206 |
|
207 | Thanks to all contributors:
|
208 |
|
209 | - [pavankjadda](https://github.com/pavankjadda)
|
210 | - [paroe](https://github.com/paroe)
|
211 | - [CunningFatalist](https://github.com/CunningFatalist)
|
212 | - [kthy](https://github.com/kthy)
|
213 | - [JaredClemence](https://github.com/JaredClemence)
|
214 | - [flakolefluk](https://github.com/flakolefluk)
|
215 | - [mattbanks](https://github.com/mattbanks)
|
216 | - [DBaker85](https://github.com/DBaker85)
|
217 | - [mattlewis92](https://github.com/mattlewis92)
|
218 | - [IceBreakerG](https://github.com/IceBreakerG)
|
219 | - [rojedalopez](https://github.com/rojedalopez)
|
220 | - [Nikel163](https://github.com/Nikel163)
|
221 |
|
222 | # License
|
223 |
|
224 | [MIT](https://github.com/stevermeister/ngx-cookie-service/blob/master/LICENSE)
|
225 |
|
\ | No newline at end of file |