TypeScript icon, indicating that this package has built-in type declarations

    1.3.0 • Public • Published


    cookie-lit is a library for parsing and serialization of server and client side cookies. It is heavily inspired by cookie and js-cookie and tries to combine both projects into one solution.


    $ npm install cookie-lit
    # Using yarn
    $ yarn add cookie-lit



    import CookieJar from 'cookie-lit';
    // Create a new cookie jar
    const jar = new CookieJar();
    // Set cookies
    jar.set('my-cookie', 'a value');
    jar.set('my-second-cookie', 'another value');
    // Get a cookie by name
    // ➞ '{ "my-cookie": "a value" }'
    // Get all cookies currently in the jar
    // ➞ '{ "my-cookie": "a value", "my-second-cookie": "another value" }'
    // Remove a cookie by name

    Set a cookie with options

    import CookieJar from 'cookie-lit';
    const jar = new CookieJar();
    const cookie = jar.set('my-cookie', 'value', {
      expires: 1,
      secure: true,
    // ➞ 'my-cookie=value; Expires=Wed, 15 Jan 2020 18:10:22 GMT; Secure'

    You can read all about the possible options in the API chapter.

    Create a pre-filled jar of cookies

    You can pre-fill a cookie jar by passing in a valid cookie string.
    This is useful when dealing with cookies coming from a HTTP request object.

    export default (req, res) => {
      // req.headers.cookie ≙ 'my-cookie=value'
      const jar = new CookieJar(req.headers.cookie);
      const cookies = jar.get();
      // ➞ '{ "my-cookie": "value" }'


    new CookieJar(cookies?)

    Create a new cookie jar instance. You can pre-fill a cookie jar by passing in a valid HTTP Cookie header string or object containing cookie key-value pairs.

    const jar = new CookieJar('my-cookie=value');
    console.log(jar.get()); // '{ "my-cookie": "value" }'
    const jar = new CookieJar({ my-cookie: 'value' );
    console.log(jar.get()) // '{ "my-cookie": "value" }'

    jar.set(name, value, options?)

    Set a cookie name-value pair. The method will serialize the given pair into a Set-Cookie header string that is also returned from the method so you can use it to set a cookie as a HTTP response header. If called client side, the cookie pair will be added to document.cookie automatically for you.


    The name of the cookie


    The value to set the cookie to. If the value is of type object, we call JSON.stringify on it.


    An optional object specifying additional cookie attributes.


    Us the encode property to specify a function that will be used to encode the value set by jar.set(). See RFC6265 Section 4.1.1 and RFC6265 Section 6.1 for detailed instructions on cookie value best-practices and limitations.

    By default, we are using the global encodeURIComponent function, which will encode a string by replacing each instance of certain characters by UTF-8 representations.


    Specifies the Domain Set-Cookie attribute. By default, no domain is set and most clients will consider the cookie to apply to only the current domain.

    jar.set('my-cookie', 'value', { domain: '' });
    // ➞ 'my-cookie=value;'

    Specifies the Expires Set-Cookie attribute. You can either set a specific Date instance or a Number that will be interpreted as days from time of creation.

    By default, no expiration date is set. Most clients will consider this a session cookie and remove the cookie as soon as the browser window is closed.

    // Expires one day from creation.
    jar.set('my-cookie', 'value', { expires: 1 });
    // ➞ 'my-cookie=value; Expires=Mon, 01 Jan 2020 00:00:00 GMT'

    Note: If both expires and maxAge are set, maxAge takes precedence, but it is possible that not all clients obey this rule. So if both are set, they should be set to the same date and time.


    Specifies the HttpOnly Set-Cookie attribute. When truthy, the attribute is set.

    jar.set('my-cookie', 'value', { httpOnly: true });
    // ➞ 'my-cookie=value; HttpOnly'

    Note: When setting httpOnly to true, clients will not allow JavaScript to see this cookie.


    Specifies the Max-Age Set-Cookie attribute in seconds. The given number will be converted to an integer by rounding down.

    jar.set('my-cookie', 'value', { maxAge: 60 });
    // ➞ 'my-cookie=value; Max-Age=60'

    Note: If both maxAge and expires are set, maxAge takes precedence, but it is possible that not all clients obey this rule. So if both are set, they should be set to the same date and time.


    Specfies the Path Set-Cookie attribute. If the path attribute is omitted, the client will use the "directory" of the request-uri's path component as the default value.

    jar.set('my-cookie', 'value', { path: '/' });
    // ➞ 'my-cookie=value; Path=/'

    Note: Although seemingly useful for isolating cookies between different paths within a given host, the Path attribute cannot be relied upon for security.


    Specifies the SameSite Set-Cookie attribute. Use one of the following possible values:

    • true will set the attribute to "Strict"
    • false will not set the attribute
    • lax will set the attribute to "Lax"
    • none will set the attribute to "None"
    • strict will set the attribute to "Strict"
    jar.set('my-cookie', 'value', { sameSite: true });
    // ➞ 'my-cookie=value; SameSite=Strict'

    Note: Browsers are migrating to have cookies default to SameSite=Lax. If a cookie is needed to be sent cross-origin, opt out of the SameSite restriction using the None directive. The None directive requires the Secure attribute.


    Specifies the Secure Set-Cookie attribute. When truthy, the attribte is set.

    Note: When setting secure to true, complient clients will not send the cookie over HTTP and you will not allow JavaScript to see this cookie on http://localhost.

    jar.get(name?, options?)

    Get all cookie name-value pairs currently stored in the cookie jar. By specifying the name argument you can query for a specific cookie value.

    // document.cookie = 'my-cookie=value'
    // ➞ '{ "my-cookie": "value" }'


    An optional cookie header name to query a specific cookie value for.


    An optional object specifying additional query options.


    Specifies a function that will be used to decode a previously-encoded cookie value into a JavaScript string or object.

    By default this function is the global decodeURIComponent.

    Note: If the decode function throws an error, the original value will be returned.

    jar.remove(name, options?)

    Delete a cookie from document.cookie and the cookie jar. The method will return an appropriate Set-Cookie header string to remove the cookie.

    // document.cookie = 'my-cookie=value'
    // jar.get() = '{ "my-cookie": "value" }'
    // ➞ 'my-cookie=; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Max-Age=0'
    // document.cookie = ''
    // jar.get() = '{}'


    The name of the cookie to be deleted.


    An optional object containing additional cookie attributes. These attributes must match the attributes set on the cookie to be deleted.

    jar.set('my-cookie', 'value', { path: '' });
    // This will fail, as the `path` attributes don't match.
    // This will remove the cookie.
    jar.remove('my-cookie', { path: '' });

    Note: Removing a non-existent cookie neither raises any exception nor returns any value.

    This project was bootstrapped with @jvdx/core.




    npm i cookie-lit

    DownloadsWeekly Downloads






    Unpacked Size

    49.2 kB

    Total Files


    Last publish


    • joelvoss