Karl
Karl
is an ES6 Image preloader. It requires zero dependencies.
Install
$ npm i @runmeetly/karl
$ yarn add @runmeetly/karl
TL;DR
import PngFile from "./images/pngs/image.png";
import SvgFile from "./images/svgs/image.svg";
import { Karl } from "@runmeetly/karl";
Karl.preload(PngFile);
Karl.preload(SvgFile);
Karl.preload("/path/to/image/file.png");
Karl.preload(BASE64_PNG_OR_SVG_DATA);
Karl.preloadMaterialTextIcon("close");
Karl.preloadMaterialTextIcon("add");
Karl.preloadMaterialTextIcon("arrow_up");
Karl.withBackend(MyCustomBackend).preload(PngFile);
Karl.withBackend(MyCustomBackend).preloadMaterialTextIcon("person");
API
Karl
has a small API surface - but can prove rather powerful.
Karl
exposes a couple functions, preload()
, preloadMaterialTextIcon()
,
and withBackend()
.
preload
accepts a single parameter of basically anything - as
long as it ultimately represents image data
. A path to a file,
a Webpack parsed import, base 64 encoded png or svg data - anything.
It optionally accepts callbacks for onLoaded
and onError
events.
It is optional to attach callbacks, and in many cases you won't need to.
Karl
will always attempt to preload the image data you pass it silently.
Once you call preload
, the image will be cached for later use and will
persist for as long as the backend and the browser allows.
preloadMaterialTextIcon
accepts a single parameter which is the name of a
material-icons
text icon. It will preload the icon by creating a hidden div
at the bottom of your document body. This will help prevent instances where
upon the first load of the material-icon, you would briefly see the actual
text while the CSS icon is loading. Once you call preloadMaterialTextIcon
,
the div will be inserted only once and will persist for as long as the
backend and the browser allows.
NOTE: preloadMaterialTextIcon
does not set up the project to work with
Material Icon fonts automatically - you must do this setup manually.
withBackend
is a more advanced method, and accepts an object which
conforms to the PreloaderBackend
interface. A backend implementation
is backed by whatever kind of storage you want - the default
implementation is simply in-memory. A backend has both contains
and
insert
functions. contains
is called with a key
parameter from
the preload
method - and should return a boolean based on whether that
key
is already cached in the backend. insert
is called with a key
and a value
, and should insert the value into the backend and mark it
with the key.
The withBackend
returns a new Karl
, which exposes the preload
and
preloadMaterialTextIcon
methods and is powered by your provided backend.
For most cases, you will be fine using the default backend, which is
automatically injected for you when you call Karl.preload()
or
Karl.preloadMaterialTextIcon()
.
Caveats
Browsers are ultimately in control of when and how they allocate their
resources. If you ask Karl
to preload a whole bunch of images - the
browser can at its discretion evict previously loaded images.
Karl may not be perfect, but he's trying his best.
Credit
Karl
is primarily developed and maintained by
Peter at
Meetly.
License
Copyright 2019 Meetly Inc.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.