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

2.1.1 • Public • Published


A smart wrapper for the browser's localStorage that allows you to set and get items as they are with optional expiration times.

NPM version Known Vulnerabilities npm NPM downloads issues license Gitter


To install this module through npm, simply use the following command:

$ npm install --save boxcrate

To use it as an ES6 module you can either install it through npm or download it directly and import it as so:

import BoxCrate from './node_modules/boxcrate/boxcrate.js';


After installing BoxCrate, a new instance can be created like so:

const boxcrate = new BoxCrate();

There are two optional initialization options for BoxCrate which deal with the expiration of data.

If you don't specify a type of expiration check to perform, none will be u sed.

Also note that you can choose to not put an expiration date on any item you set which means it will not expire ever.

param type description default
options Object
options.expiredCheckType string The type of expiration check to perform. (Either 'passive' or 'active') null
options.expiredCheckInterval number If you select the passive expiration check type, you can specify the interval of time in which data is checked for expired items. 1000

The options for expiredCheckType are as follows:

  1. 'passive': With the type set to 'passive', whenever an item is set to be retrieved from localStorage, it is checked to see if it is expired and if so deleted and never retrieved.

    • Advantage: Very passive type of check, minimal performance cost.

    • Disadvantage: The item could be expired for a long time and still be accessible directly in the localStorage through the browser if the user checks it themselves.

  2. 'active': Every x seconds the localStorage will be checked for expired values and if found, they will be removed.

    • Advantage: Very active type of check, expired values are removed almost instantly.

    • Disadvantage: Performance cost is highest.


BoxCrate aims to replicate the API of localStorage so it feels seamless switching over.


Returns a reference to the storage. Note, this should not be modified as it will affect the original storage also.


const storage =;


Returns the number of items saved in BoxCrate's storage.


const numOfItems = boxcrate.count;


Set item lets you save an item to BoxCrate's storage using a key, value, and optional expiration time.

One of the advtanges of using BoxCrate is when saving an item to the storage, you can save it as is. Normally with localStorage you can only save strings but BoxCrate lets you save strings, numbers, arrays, and objects as they are and they will be retrieved in the same format.

The only exception to this are Symbols which cannot be saved and retrieved as is as they are unique and when retrieving it the Symbol would not be equal to the original Symbol.

param type description default
key string A unique key to use for the saved item.
value string The item to save.
msToExpire number The time, in milliseconds, until this key value pair should be removed from the storage.


const pizzaToppings = ['Cheese', 'Pepperoni', 'Spinach'];
boxcrate.setItem('toppings', pizzaToppings);


Retrieve an item from BoxCrate's storage. The item will be retrieved in the same format it was saved.

param type description default
key string The key of the saved item to retrieve.


const toppings = boxcrate.getItem('toppings');
// => ['Cheese', 'Pepperonoi', 'Spinach']


Remove a saved item from the storage by its key.

param type description default
key string The key of the saved item to remove.




Remove all saved items from BoxCrate's storage.




Since BoxCrate's tests are run in the browser, you have to run:

$ npm run test

and then in your browser, go to http://localhost:8888/test/index.html to run the test suite.



Package Sidebar


npm i boxcrate

Weekly Downloads






Unpacked Size

89.1 kB

Total Files


Last publish


  • robert.corponoi