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

    2.0.4 • Public • Published

    Cookie Toss

    A package that makes sharing local data across domains a thing of ease.

    This package outputs...

    • A script to be hosted in an HTML document on a central domain, the "hub domain", where all user data is stored.
    • A module to be used in applications on "satellite" domains, which retrieves and sets localStorage values on the hub domain.
    A Note on the Name

    Yes, yes - it's called "Cookie Toss", but it uses localStorage. In the first iteration, cookies were used, but due to current and upcoming changes to browser cookie policies, not to mention larger hard drive allowances for LS, it made more sense to move it to be localStorage based.

    "Cookie Toss" it will remain, though.


    localStorage values are the pieces of data we save to a user's hard drive for later usage by our application. Each value we save is scoped to the domain the user is on when the save takes place. Likewise, when retrieving the values, we're restricted to only access those values saved to the domain our code is running on.

    This is great, as it disallows a user's shopping site from grabbing data from, say, their social media site, without the consent of the user or the social media site.

    Where this becomes painful - sometimes a site owner owns two sites and wants to let the user pass easily between them with all of their saved data. If, for instance, you have a suite of sites with different domains and the user signs in on one, you'd rather not make them sign in again as they traverse to another. This makes for bad UX for users who want a seamless experience.

    Enter cookie-toss. This package allows you to store all user data on a central (hub) domain, and set or access it from dependent (satellite) domains. It also allows you to consolidate your data retrieval logic on the central domain, so that all satellite domains need simply fetch it. This allows for a much more DRY approach.


    cookie-toss provides both code for the iframe hosted on the hub domain, as well as the data getters and setters for the satellite domains.

    The minimum setup just involves deploying the iframe code with a list of white-listed satellite domains to your hub domain, and using the get and set functions in apps on the satellite domains.


    You can find full examples of usage in the /examples directory of the repo. Note the "Smoke Tests" section below for how to run examples locally.

    Setting and Getting Data from the Satellite Applications

    Iframe on

    import { createIframe } from "cookie-toss";
    // Sites allows to access data on the hub domain:
    const dependentDomains = ["", ""];
    // Sets up the contents of the iframe:
    createIframe({ dependentDomains });
    // That's it!  Including this code in an HTML file on your central domain readies you for data sharing across domains.

    Somewhere in the app on

    import { set } from "cookie-toss";
    const result = await set({
      // This is the URL at which you've hosted the output of `createIframe`, above:
      iframeUrl: '',
      dataKey: 'chocolate-chip-oatmeal',
      data: {
          c: 'is for localStorage',
          and: 'that\'s good enough for me.'

    Somewhere in the app on

    import { get } from "cookie-toss";
    const result = await get({
      iframeUrl: '',
      dataKey: 'chocolate-chip-oatmeal',
    /* Logs:
        c: 'is for localStorage',
        and: 'that\'s good enough for me.'

    Under the hood, the get and set functions script-inject the iframe into the page, then send it requests to access its localStorage space. The iframe contains code to interpret the requests, and get and set data as instructed.

    However, one of the strengths of cookie-toss is that it allows you to make the iframe the source of truth, alleviating potential race conditions and non-DRY behavior in your satellite apps. This is done by using handlers in the iframe to do the cookie fetching, so that satellite apps can take the data acquisition process for granted. Read on...

    Iframe Handlers

    By setting a handler for a dataKey in the iframe, your satellite apps can call for data, and the hub iframe will handle the getting of the data. This means no one app has to set the data before others can retrieve it.

    Iframe on

    import { createIframe } from 'cookie-toss'
    // A function of the user's choosing, which returns a primitive or stringify-able value:
    import { createUserUuid } from 'my-data-getter'
    const dependentDomains = ['', '']
        dataConfigs: [
                dataKey: 'userUuid',
                handler: createUserUuid,
                expires: 365 // One year

    In the above case, the iframe will now host our data getter, createUserUuid. The value returned by this synchronous or async function will be stored at the 'userUuid' key in the iframe, and become available to all satellite domains.

    We now can add the following code to and The first satellite to call the iframe will trigger the iframe to execute createUserUuid and cache the response on the hub. In the second call, the iframe will reply immediately with the cached value:

    Somewhere in the app on

    import { get } from "cookie-toss";
    const result = await get({
      iframeUrl: '',
      dataKey: 'userUuid',
    console.log(result) // 123e4567-e89b-12d3-a456-426655440000



    The function for producing the code that lives in the iframe on the hub domain. Include the output in an HTML document, and deploy to your hub domain.

    options Parameters

    option description required type example
    dependentDomains An array of the domains allowed to access data on the hub domain. Do not include protocols or paths. true Array [ '' ]
    dataConfigs An array of configurations for each data value the iframe will manage. false Array See below.
    dataConfigs[n].dataKey The localStorage key the data will be stored under. Also used when retrieving the value. true String 'snickerdoodle'
    dataConfigs[n].handler The function that retrieves the data to be cached in localStorage. Optionally receives an argument the app sends when requesting the datum. Data returned from the handler must be stringify-able or primitive. true Function (userName) => axios(`${myEndpoint}?user=${userName}`)
    dataConfigs[n].expires The number of days before the data expires. Defaults to 30 years. false Number 7




    The function used by the application for setting the localStorage value on the hub domain.


    Do not use `set` if the `dataKey` is included a `dataConfigs` configured in the `createIframe` function on the hub. In this case, the iframe becomes the setter, and the application needs only use the `get` function (below) to retrieve the data.

    options Parameters

    option description required type example
    iframeUrl The full URL on the hub domain where the iframe lives. true String ''
    dataKey The localStorage key the data will be stored on under the hub domain. true String 'samoa'
    data The value to be stored. true Any primitive or stringify-able value. { c: 'is for cookie' }


    Data sent with request to the hub domain, after being subjected to localStorage caching. Note this will be the value after it has been subjected to JSON.stringify, JSON.parse and the application of the expiry.


    The function used by the application for getting the datum from the hub domain. Must reference a dataKey previously set by the set function or configuring in a dataConfigs object passed to the createIframe function.

    options Parameters

    option description required type example
    iframeUrl The full URL on the hub domain where the iframe lives. true String ''
    dataKey The name under which the datum is stored on the hub domain. true String 'samoa'
    handlerPayload The value that the iframe's dataConfig's handler will receive. Only applicable to dataKeys with dataConfig objects passed into the createIframe function on the hub domain. false Any primitive or stringify-able value. { userType: 'B' }
    resetData If true, will purge the data, forcing the iframe's handler to re-retrieve the data value. Only applicable to dataKeys with dataConfig objects passed into the createIframe function on the hub domain. false Boolean true


    Data previously stored at the dataKey on the hub domain. If this is an object, it will be subjected to JSON.parse prior to arriving back in the app.

    To Test

    Unit tests

    [TBD] I'm the worst.

    Smoke Tests

    For some hacky smoke testing, add the following entries to your etc/hosts file:

    In one terminal run:

    npm run dev-iframe

    In a second terminal run:

    npm run dev-app

    Navigate to, and observe the output on the page.

    You'll note no values are stored in the localStorage of If you navigate to, you'll find all example values stored there.


    To build the bundle, run:

    npm run build

    The output can be found in the /lib folder.


    To deploy a new version:

    • Update the with the recent changes.
    • Update the package.json with the new version number.
    • Run the following bash command:
    npm run deploy


    npm i cookie-toss

    DownloadsWeekly Downloads






    Unpacked Size

    75.5 kB

    Total Files


    Last publish


    • jmealy