npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

electricity

v3.5.1

Published

An alternative to the built-in Express middleware for serving static files. Electricity follows a number of best practices for making web pages fast.

Downloads

484

Readme

Electricity

Build Status Coverage Status

An alternative to the built-in Express middleware for serving static files. Electricity follows a number of best practices for making web pages fast.

The built-in Express middleware for serving static files is great if you need basic support for serving static files. But if you want to follow Best Practices for Speeding Up Your Web Site you need something that can concat, gzip, and minify your static files. Electricity does all this and more without the need to create a complicated build process using Grunt or a similar build tool.

Basic Usage

Typically, in an Express app you'd serve static files using the built-in middleware. Like this:

const express = require('express');

app.use(express.static('public'));

To begin using Electricity simply replace the default static middleware:

const express = require('express');
const electricity = require('electricity');

app.use(electricity.static('public'));

View Helper

A common best practice for serving static files is to set a far future Expires header: http://developer.yahoo.com/performance/rules.html#expires

When you set a far future Expires header you have to change the file name whenever the contents of the file change. Electricity makes this easy for you by automatically adding an MD5 hash of the file's contents to the file name. You have access to this file name using a view helper method that builds URLs for you. If you're using EJS it looks something like this:

<img src="<%= electricity.url('/images/image.png') %>" />
<link href="<%= electricity.url('/styles/style.css') %>" rel="stylesheet" />
<script src="<%= electricity.url('/scripts/script.js') %>"></script>

Which ultimately gets rendered as something like this:

<img src="/images/image-423251d722a53966eb9368c65bfd14b39649105d.png" />
<link href="/styles/style-22a53914b39649105d66eb9368c65b423251d7fd.css" rel="stylesheet" />
<script src="/scripts/script-5d66eb9368c22a53914b39d7fd6491065b423251.js"></script>

Features

Electricity comes with a variety of features to help make your web pages fast without the need to setup a complicated build process.

  • HTTP Headers: Electricity sets proper Cache-Control, ETag, and Expires, headers to help avoid unnecessary HTTP requests on subsequent page views.
  • Minification of JavaScript and CSS: Electricity minifies JavaScript and CSS files in order to improve response time by reducing file sizes.
  • Gzip: Electricity gzips many content types (CSS, HTML, JavaScript, JSON, plaintext, XML) to reduce response sizes.
  • Snockets: Electricity supports Snockets (A JavaScript concatenation tool for Node.js inspired by Sprockets). You can use Snockets to combine multiple JavaScript files into a single JavaScript file which helps minimize HTTP requests.
  • Sass: Electricity supports Sass (Sassy CSS). Among other features, Sass can be used to combine multiple CSS files into a single CSS file which helps minimize HTTP requests. NOTE: We currently only support .scss files (not .sass files written in the older syntax).
  • React JSX: Electricty transforms React JSX for you automatically using babel-core without the need for client-side translation or build steps.
  • CDN Hostname: If you're using a CDN (Content Delivery Network) that supports a custom origin (like Amazon CloudFront) you can specify the hostname you'd like Electricity to use when generating URLs.
  • Watch: Electricity watches for changes to your static files and automatically serves the latest content without the need to restart your web server (useful during development). Electricity also understands Sass and Snockets dependency graphs to ensure the parent file contents are updated if a child file has been modified.

Advanced Usage

Default options look like this:

const options = {
    babel: {},
    hashify: true,
    headers: {},
    hostname: '',
    sass: {},
    snockets: {},
    uglifyjs: {
        enabled: true
    },
    uglifycss: {
        enabled: true
    }
};

You can override the default options to look something like this:

var options = {
    babel: { // Object passed straight to @babel/core options: https://babeljs.io/docs/en/options
        generatorOpts: {
            compact: true
        },
        parserOpts: {
            errorRecovery: true
        }
    },
    hashify: false, // Do not generate hashes for URLs
    headers: { // Any additional headers you want a specify
        'Access-Control-Allow-Origin': 'https://example.com'
    },
    hostname: 'cdn.example.com', // CDN hostname
    sass: { // Object passed straight to node-sass options
        outputStyle: 'compressed',
        quietDeps: true
    },
    snockets: { // Object passed straight to snockets options: https://www.npmjs.com/package/snockets
    },
    uglifyjs: { // Object passed straight to uglify-js options: https://github.com/mishoo/UglifyJS#minify-options
        enabled: false // Do not minify Javascript
    },
    uglifycss: { // Object passed straight to uglifycss options: https://github.com/fmarcia/uglifycss
        enabled: false // Do not minify CSS
    }
};

Pass options to the middleware like this:

app.use(electricity.static('public', options));

HTTP Headers

Electricity sets proper Cache-Control, ETag, and Expires headers to help avoid unnecessary HTTP requests on subsequent page views. If you'd like to specify literal values for specific HTTP headers you can set them in the headers option. This is useful if you need to specify a Access-Control-Allow-Origin header when loading fonts or JSON data off a CDN.

app.use(electricity.static('public', {
    headers: { 'Access-Control-Allow-Origin': '*' }
}));

CSS URI Values

Electricity will automatically rewrite URIs in CSS to use SHA1 hashes (if a matching file is found). For example:

background-image: url(/background.png);

becomes this to allow caching and avoid unnecessary redirects:

background-image: url(/background-423251d722a53966eb9368c65bfd14b39649105d.png);

CDN Hostname

If you specify a hostname like this:

const express = require('express');
const electricity = require('electricity');

const options = {
    hostname: 'cdn.example.com'
};

app.use(electricity.static('public'), options);

Then render URLs using the view helper like this:

<img src="<%= electricity.url('/images/image.png') %>" />
<link href="<%= electricity.url('/styles/style.css') %>" rel="stylesheet" />
<script src="<%= electricity.url('/scripts/script.js') %>"></script>

Your HTML will ultimately get rendered using absolute URLs like this:

<img src="https://cdn.example.com/images/image-423251d722a53966eb9368c65bfd14b39649105d.png" />
<link href="https://cdn.example.com/styles/style-22a53914b39649105d66eb9368c65b423251d7fd.css" rel="stylesheet" />
<script src="http://cdn.example.com/scripts/script-5d66eb9368c22a53914b39d7fd6491065b423251.js"></script>