ngx-cookie-handler

Implementation of Angular 1.x $cookies service to Angular 17.0.0

This is a fork of https://github.com/salemdar/ngx-cookie and maintaining

Table of contents:

• Get Started
  • Installation
  • Usage
  • Server Side Rendering
• CookieService
  • get()
  • getObject()
  • getAll()
  • put()
  • putObject()
  • remove()
  • removeAll()
• Options

Get Started

Installation

You can install this package locally with npm.

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

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-handler";

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-handler";

@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);
  }
}

Server Side Rendering

ngx-cookie-handler 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-handler working with SSR.

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

Setup

Install ngx-cookie-handler-ssr library:

npm install ngx-cookie-handler-ssr --save

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

/* app.server.module.ts */

import { CookieBackendModule } from "ngx-cookie-handler-ssr";

@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, next) => {
  const { protocol, originalUrl, baseUrl, headers } = req;

  commonEngine
    .render({
      bootstrap,
      documentFilePath: indexHtml,
      url: `${protocol}://${headers.host}${originalUrl}`,
      publicPath: browserDistFolder,
      providers: [
        { provide: APP_BASE_HREF, useValue: baseUrl },
        { provide: "REQUEST", useValue: req },
        { provide: "RESPONSE", useValue: res },
      ],
    })
    .then((html) => res.send(html))
    .catch((err) => next(err));
});

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

CookieService

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

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;

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;

getAll()

Returns a key value object with all the cookies.

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

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;

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;

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;

removeAll()

Remove all cookies.

/**
 */
removeAll(): void;

Options

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

• path - {string} - The cookie will be available only for this path and its sub-paths. By default, this is the URL that appears in your <base> tag.
• domain - {string} - The cookie will be available only for this domain and its sub-domains. For security reasons the user agent will not accept the cookie if the current domain is not a sub-domain of this domain or equal to it.
• expires - {string|Date} - String of the form "Wdy, DD Mon YYYY HH:MM:SS GMT" or a Date object indicating the exact date/time this cookie will expire.
• secure - {boolean} - If true, then the cookie will only be available through a secured connection.
• sameSite - {"Lax"|"Strict"|"None"} - Designates cookie for first party (Lax|Strict) or third party contexts.
• httpOnly - {boolean} - If true, then the cookie will be set with the HttpOnly flag, and will only be accessible from the remote server. Helps to prevent against XSS attacks.
• storeUnencoded - {boolean} - If true, then the cookie value will not be encoded and will be stored as provided.