Home

Awesome

ngx-cookie CI npm version Downloads Codacy Badge Codacy Badge

Implementation of Angular 1.x $cookies service to Angular

Table of contents:

<a name="get-started"></a> Get Started

<a name="installation"></a> Installation

You can install this package locally with npm.

# To get the latest stable version and update package.json file:
yarn add ngx-cookie
# or
# npm install ngx-cookie --save

<a name="usage"></a> Usage

CookieModule should be registered in an angular module with withOptions() static method. These methods accept CookieOptions objects as well. Leave it blank for the defaults.

import { NgModule }      from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';

import { CookieModule } from 'ngx-cookie';

import { AppComponent }  from './app.component';

@NgModule({
  imports: [ BrowserModule, CookieModule.withOptions() ],
  declarations: [ AppComponent ],
  bootstrap: [ AppComponent ]
})
export class AppModule { }

import { Component } from '@angular/core';
import { CookieService } from 'ngx-cookie';

@Component({
    selector: 'my-very-cool-app',
    template: '<h1>My Angular App with Cookies</h1>'
})

export class AppComponent { 
  constructor(private cookieService: CookieService){}
  
  getCookie(key: string){
    return this.cookieService.get(key);
  }
}

<a name="ssr"></a> Server Side Rendering

ngx-cookie supports usage during Server Side Rendering (SSR / Angular Universal). Getting Server Side Rendering itself set up the first time can be tricky and is outside the scope of this guide. Here, we'll assume that you've got a working SSR setup similar to the Angular Universal Starter project, and you're just trying to get ngx-cookie working with SSR.

Note: during normal, client side usage, ngx-cookie manipulates the client cookies attached to the document object. During SSR, ngx-cookie will manipulate cookies in http request or response headers._

Setup

Install ngx-cookie-backend library:

yarn add ngx-cookie-backend
# or
# npm install ngx-cookie-backend --save

Then edit app.server.module.ts and add CookieBackendModule.withOptions() to imports:

/* app.server.module.ts */

import { CookieBackendModule } from 'ngx-cookie-backend';

@NgModule({
  imports: [
    AppModule,
    ServerModule,
    CookieBackendModule.withOptions()
  ],
  bootstrap: [AppComponent]
})
export class AppServerModule {}

Next, we need to make providers for the 'REQUEST' and 'RESPONSE' objects created by the expressjs server during SSR. To do this, edit server.ts to create providers for 'REQUEST' AND 'RESPONSE'.

/* server.ts */
import { REQUEST, RESPONSE } from '@nguniversal/express-engine/tokens';

// All regular routes use the Universal engine
server.get('*', (req, res) => {
  res.render(indexHtml, {
    req,
    res,
    providers: [
      {provide: APP_BASE_HREF, useValue: req.baseUrl},
      {provide: REQUEST, useValue: req},
      {provide: RESPONSE, useValue: res}
    ]
  });
});

And that's it! all your application's calls to CookieService should now work properly during SSR!

<a name="examples"></a> Examples

Normal usage example is under projects/test-app

SSR usage example is under projects/backend-test-app

<a name="cookieservice"></a> CookieService

There are 7 methods available in the CookieService (6 standard methods from Angular 1 and 1 extra removeAll() method for convenience)

<a name="get"></a> get()

Returns the value of given cookie key.

/**
 * @param {string} key Id to use for lookup.
 * @returns {string} Raw cookie value.
 */
get(key: string): string;

<a name="getobject"></a> getObject()

Returns the deserialized value of given cookie key.

/**
 * @param {string} key Id to use for lookup.
 * @returns {Object} Deserialized cookie value.
 */
getObject(key: string): Object;

<a name="getall"></a> getAll()

Returns a key value object with all the cookies.

/**
 * @returns {Object} All cookies
 */
getAll(): any;

<a name="put"></a> put()

Sets a value for given cookie key.

/**
 * @param {string} key Id for the `value`.
 * @param {string} value Raw value to be stored.
 * @param {CookieOptions} options (Optional) Options object.
 */
put(key: string, value: string, options?: CookieOptions): void;

<a name="putobject"></a> putObject()

Serializes and sets a value for given cookie key.

/**
 * @param {string} key Id for the `value`.
 * @param {Object} value Value to be stored.
 * @param {CookieOptions} options (Optional) Options object.
 */
putObject(key: string, value: Object, options?: CookieOptions): void;

<a name="remove"></a> remove()

Remove given cookie.

/**
 * @param {string} key Id of the key-value pair to delete.
 * @param {CookieOptions} options (Optional) Options object.
 */
remove(key: string, options?: CookieOptions): void;

<a name="removeall"></a> removeAll()

Remove all cookies.

/**
 */
removeAll(): void;

<a name="options"></a> Options

Options object should be a type of CookieOptions interface. The object may have following properties: