Load stylesheets asynchronously and store them in web storage

Usage no npm install needed!

<script type="module">
  import storeCss from '';



Build Status

🎒 Load stylesheets asynchronously and store them in web storage.

You can try it out in this test page First open a new tab and your development tools, go to the Network tab and enter the url, then reload the page to see how many requests are saved. You can also checkout the console to see what's going on.


# npm
npm i store-css --save

# yarn
yarn add store-css

Or include it as a script with // as source.


Import the css method and pass the url where your stylesheet is located.

import { css } from 'store-css'

const url = '//'
css({ url })

The package will unsure the stylesheet is loaded without render blocking the page.

But the magic happens when you use the storage option.


When you pass a storage, the script will save the content of the stylesheet in web storage. In future visits the styles will be retrieved from there instead of making a network call!

import { css } from 'store-css'

const url = '//'
const storage = 'session'
css({ url, storage })

storage option can be both 'session' or 'local'.

What happens if the web storage space is full? What happens if a browser has a buggy web storage implementation? No worries, the script will fallback to normally loading a link element. It always works.

This is great to avoid flicks unstyled content in repeated views, and as the script is really small it's a really good option for head inlining in static sites.


If you are calling a stylesheet from a different origin you will need this.

import { css } from 'store-css'

const url = '//'
const storage = 'session'
const crossOrigin = 'anonymous'
css({ url, storage, crossOrigin })

Make sure to test which string or identifier works better for the provider.


If you want styles to be aplied for a specific media environment, pass the query as an option.

import { css } from 'store-css'

const url = '//'
const storage = 'session'
const media = '(max-width: 739px)'
css({ url, storage, media })

On the first round the media attribute will be passed to the link element, on future visits the stylesheet content will be wrapped before injecting a style tag.


By default the styles will be injected before the first script present in the page, but you can change this if you need some specific position for them to not affect the cascade effect of the styles.

import { css } from 'store-css'

const url = '//'
const storage = 'session'
const ref = document.getElementById('#main-styles')
css({ url, storage, ref })

Styles will be place before the ref element.


If you need to debug the package behavior you can pass a logger method. This function will receive an error as a first argument and a message as a second one.

import { css } from 'store-css'

const url = '//'
const storage = 'session'
const logger = console.log
css({ url, storage, logger })

This approach is really good for both custom logic on logging and to avoid unnecessary code in production.

import { css } from 'store-css'

const url = '//'
const storage = 'session'
const config = { url, storage }

if (process.env.NODE_ENV ==! 'production') {
  config.logger = (error, message) => {
    if (error) console.error(message, error)
    else console.log(message)


In production the logger method won't be added and code will be eliminated by minifiers.

Browser support

This package works all the way from modern browsers to Internet Explorer 9.


To contribute Node.js and yarn are required.

Before commit make sure to follow conventional commits specification and check all tests pass by running yarn test.