Using EQCSS as a JavaScript Module with Webpack

Since version 1.5.0 EQCSS has been written in a modularized way. It follows the UMD module style so it's able to be loaded by module loaders as a module with is own scope. If it's loaded outside of a module loader (by itself as a <script> in the browser) it will attach itself to the global object and run in the global scope.

What does modularization do?

There are a few advantages to using JavaScript modules, compared to writing all of your JavaScript in the global scope. For EQCSS, which functions like a shim or polyfill, it's important that the JavaScript of the plugin end up loaded in the final page, but unlike a lot of other npm modules you don't need to work with EQCSS in your backend very often.

There are two methods that help add additional control over when the EQCSS plugin recalculates styles: EQCSS.apply() and EQCSS.throttle(). The first, EQCSS.apply() will recalculate the styles the plugin is watching immediately. The second, EQCSS.throttle() allows us to make a throttled request to recalculate styles that is capped at running once every 200ms.

If you are using EQCSS without needing to manually trigger when it recalculates from Javascript it may be easier to load it via CDN, or load EQCSS.min.js directly in your HTML with a <script> tag like another shim or polyfill. But if you find yourself needing to trigger EQCSS manually from your JavaScript and you're working with a modularized JavaScript workflow, the following steps will show you how you can add EQCSS into a fresh project, load EQCSS with your module loader, and access EQCSS.apply() and EQCSS.throttle() from their own scope in your JavaScript!

Create a project folder

To start, let's create a folder called example on our web server:

mkdir example

Now that we have a folder created for this demonstration, let's move into it

cd example

Initialize npm

To facilitate the installation of EQCSS and webpack, and to run our build script we will be using npm. To get started with npm you need to initialize it inside your folder with npm init. By adding -y we can accept all the default options and get to work faster.

npm init -y

After this has run, npm should have created a file named package.json with the following content in the folder you're working in:

Create an app/ folder

In order to test if EQCSS can be loaded, and to make sure our methods are scoped correctly we'll need to create a few files: a JavaScript file, a stylesheet, and an HTML file. The first of these will be our JavaScript file, so let's create a folder in our main folder called app where we can store our JavaScript.

mkdir app

Create index.js

And next we'll create a JavaScript file called index.js inside our app folder.

The first line, var eq = require('eqcss') tells Webpack to look for EQCSS.js inside node_modules/eqcss/, which will locate the EQCSS plugin. Once Webpck sees that our plugin is UMD-formatted it will scope the plugin in a way that allows us to use it from index.js without being in the gobal scope.

In this example, our plugin and its methods have been imported as eq, and so in order to test if we can access EQCSS.apply() and EQCSS.throttle() in the correct scope we do an if (eq.apply) {}. If we can access that method from the file we're working in, the code in the brackets will run. Here I've had it print a message in the JavaScript console that we can check when the page has loaded in the browser, and I've done the same for eq.throttle to test if we can access EQCSS.throttle().

Create a stylesheet

Finally, we need some EQCSS styles for our demo page to load to see if the plugin is working once bundled and loaded in our web page. Let's create a file called styles.css in our main folder.

touch styles.css

Add EQCSS styles

And to this stylesheet let's add the following scoped style:

@element 'body' {
$this {
background: lime;
}
}

If this style and EQCSS.js are loaded correctly, the <body> element of our page should have a nice light green colour telling us everything is working.

Add build script to package.json

Now that we have our JavaScript and CSS written we can open our package.json file and add a script that will build our JavaScript so we can test if it's working. Inside the scripts object we'll add a new entry called build, when we are in the main folder of our project and we run npm run build this is the code that will be executed:

"build": "webpack app/ dist/bundle.js"

The command we are using is webpack app/ dist/bundle.js which will look for all of the files in app/ and bundle them (and the files they import) into one file called bundle.js inside a folder named dist/ (which webpack will create for us if it doesn't exist already).

Add styles and bundle to HTML

Build with npm

Now we're ready to build and test the site. To run Webpack using the script we added to npm we can use the following command in the main folder of our project:

npm run build

This should build the file dist/bundle.js which is loaded by index.html

Visit site in browser

Now to test to see if everything has worked correctly we only need to point our web browser to the index.html file in our main project folder. If the background is green then the EQCSS.js plugin and our EQCSS styles have loaded in and are running correctly.

Example site: http://staticresource.com/example

And to test that the module scope is working correctly we can check the JavaScript console to see the messages we asked it to print if EQCSS.apply() and EQCSS.throttle() are scoped and defined:

bundle.js:52 EQCSS.apply() available
bundle.js:57 EQCSS.throttle() available