I recently ported a midsized, vanilla Node.js app from CommonJS to ES Modules. Here’s what I learned and how you can modernize your project step by step.

What’s the difference between CommonJS and ES Modules?

While CommonJS is de facto everywhere in the Node.js universe, it’s safe to say that ES Modules are the future. They’re now the official standard format to package JavaScript code for reuse. No matter if in the browser or in Node.js, both systems allow you to import and export code from different files, making it possible to split your project into junks of self-contained functionality.

// CJS
const utils = require('../utils')
const funcA = () => {}
const funcB = () => {}
module.exports = { funcA, funcB }

// ESM
import { utilA } from '../utils/index.js'
export const funcA = () => {}
export const funcB = () => {}

You might already use ES Modules in the browser (probably with the help of webpack or a module bundler of your choice). I therefore won’t go into further details. Mahdhi Rezvi has a great blog post explaining the differences of both systems in depth if you aren’t familiar with them. What matters for this guide is that the current version of Node.js has a solid support for ES Modules. The feature isn’t hidden behind a flag anymore and the official docs are marking ECMAScript modules as “stable”.

It’s time to bring your app into the future of JS development 🚀

Tips along the way

• Most changes are small, but there’re a lot of them. It will take a while to adjust all exports and imports and your code won’t run in the meantime. You shouldn’t start this task at the end of the day.
• I recommend to use prettier and eslint. It’s optional, but it will make your life a lot easier. We need to modify every single file and those tools help us to keep the formatting consistent, while also checking errors we overlooked. Especially the eslint plugin “eslint-plugin-import” has rules that are relevant for us. Rules that verify our imports. Make sure to configure at least import/no-unresolved, import/no-commonjs and import/extensions.

{
  ...
  "plugins": ["import"],
  "rules": {
    "import/no-unresolved": 2,
    "import/no-commonjs": 2,
    "import/extensions": [2, "ignorePackages"]
  }
}

Step by step: From CommonJS to ES Modules

1) Prepare your code

Everything is easier when you and your code are prepared.

• Check that your Git working copy is empty, start a new branch, update your dependencies and ensure that your tests are succeeding.
• Install the latest Node.js version (at least the current LTS) and verify that your app is running smoothly after the update.

Commit all changes, brew yourself a coffee and take a deep breath. It’s showtime🧑‍💻

2) Update the package.json

Tell Node.js that all files are ES Modules by adding "type": "module" to the package.json. You can alternatively use the .mjs file extension for all your files, but I prefer the former.

{
  "name": example",
  "version": "1.0.0",
  "type": "module",
  ...
}

3) Convert all imports and exports

You can do this by hand when your project only has a few files, but it’s a painful process for any midsized Node.js app.

cjs-to-es6 is a CLI that converts JavaScript files from CommonJS to ES6 Modules. It’s unmaintained, but still the best tool I could find. It successfully ported around 80% of my files. That’s fine. Both modules systems are different and not everything can be converted 1:1.

Run the tool with the verbose flag to see which files failed: cjs-to-es6 --verbose src/.

4) Fix imports and exports

As already mentioned—Both modules systems are different. It’s impossible to convert all files automatically. While cjs-to-es6 is a big help, it’s still necessary to look at each file individually. Here’re a few issues I had and how I fixed them:

File extensions

cjs-to-es6 converts const package = require('package') to import package from 'package' and const localFile = require('../utils/localFile') to import localFile from '../utils/localFile'. That’s fine. At least for the external package.

Local file imports require a file extension. Every import must end with .js (or .mjs depending on your choice). You might haven’t seen this before, because it’s not necessary in the browser (when using a module bundler), but this is how ES Modules work. File imports are URLs.

Do this:

import something from './something.js'

Don’t do this:

import something from './something'

Directory indexes

Directory indexes must be fully specified. Importing ../utils won’t magically import the index.js anymore.

Do this:

import * as utils from '../utils/index.js'

Don’t do this:

import * as utils from '../utils'

Object exports

It was common to export an object of functions when a file had multiple functions to expose. You can still export objects, but this isn’t the correct way anymore. Instead, add export in front of every function or variable you want to export. This has the advantage that you can now import them individually via import { funcA, funcB } from '../utils/index.js' or all at once via import * as utils from '../utils/index.js'.

Do this:

export const funcA = () => {}
export const funcB = () => {}

Don’t do this:

const funcA = () => {}
const funcB = () => {}

export default {
  funcA,
  funcB
}

Broken imports of external modules

You might need to adjust the import of some external npm packages depending on how they export their code. Checking the GitHub repo for existing issues usually does the job. Sometimes it can also help to try a few common ESM imports to see where the code you’re looking for is hidden behind.

In my case it only got confusing when the module exported an object (see “Object exports”). In this case you can’t import a property or function directly via import { funcA } from 'package'. You instead need to import the object and access the function you’re looking for later on.

This works when the export is an object:

import signale from 'signale'

const instance = new signale.Signale()

This won’t:

import { Signale } from 'signale'
import * as signale from 'signale'

JSON imports

This made me a bit sad. It’s currently not possible to import JSON files, but there’re three ways to get around this problem:

• Use fs to read the content of a JSON file and parse it using JSON.parse
• Use JS modules instead of JSON and export an object
• Use the experimental --experimental-json-modules Node.js flag

ESLint

I had to rename my eslintrc.js to eslintrc.cjs, because ESLint doesn’t support ES Modules, yet. Using a JSON instead of a JS configuration also does the job.

Note that we can’t support .mjs configuration files yet due to ESLint currently being synchronous in nature. — kaicataldo

NYC Code Coverage

Are you using nyc (the Istanbul command line interface that reports the code covered by your tests)? It’s not ready for the future, yet. The good thing is that V8 (the JavaScript engine behind Node.js) has code coverage built-in. You can take advantage of it using c8. A CLI similar to nyc. And because it relies on the build-in V8 code coverage it always works with the newest syntax supported by Node.js.

Miscellaneous

I’m sure that you will run into specific issues not covered by this guide. Every code is different. Make sure to take a look at the Node.js documentation before searching the web. It’s up-to-date and contains everything you need to know on one page.

5) Verify your changes

It’s time to check if everything went well. Use prettier to clean up your code and let eslint check your imports (this is where eslint-plugin-import is a big help). Run your app to see if there’re obvious errors. I’m sure that your app won’t launch on the first try. There’s always a file that has been overlooked 🙄

Congratulation

You successfully ported your Node.js app to ES Modules 👏 I hope this article made the process a bit easier. Let me know what you think and what issues bothered you during the conversion!

This guide explains the little magic behind the hover effect I’ve made for the menu of the Ackee site. Let’s start! 🚀

Track the position

We need to know the position of the cursor to build a directional effect. This can be done in JS.

The CSS variable --x now contains the position of the mouse relative to the element. It will update whenever the mouse enters and leaves the element.

Reality however showed me that it looks a little bit weird when x is near, but not exactly left (0) or right (elem.clientWidth). Let’s fix this by adding a tolerance.

The styling

text-decoration: underline can’t be animated. We’re therefore adding a line below the element using an ::after pseudo element.

1. Remove the default styling of the link
2. Add a custom underline
3. Use --scale to show and hide the underline (starting with 0 = hidden)
4. Use --x to define the origin of the scale transform (the position of the mouse)
5. Show the underline by changing the --scale variable

The result

That’s it already. A few lines of code and hovering links makes fun, again. Add the missing HTML and enjoy:

Directional link effects with CSS variables was originally published in Prototypr on Medium, where people are continuing the conversation by highlighting and responding to this story.

November last year I finally had the opportunity to go part time and to spend three days a week on my goal. For three months ⏱

My personal ambition was to learn Swift and iOS development in the given time and to test and approve my new knowledge by publishing an app to the App Store 📲

Prior knowledge

Swift isn’t my first language. I’m a Front-End developer specialised in JavaScript development. I’ve worked with other object-oriented languages before and I also know how to design user-interfaces.

I guess it’s important to say that ~36 days aren’t enough when you don’t have any background in programming. And it’s by far not enough time to become a Swift expert. But don’t be scared. Swift is a language that’s good to read and learn. The amount of tutorials is fantastic for such a young language.

Rocking Swift and iOS

Step 1

For the beginning I recommend to start with a tutorial series or book that takes you by hand and guides you through all the basics. Something you can follow step by step. It helps you to get familiar, without getting lost in all the topics.

I’ve used Design+Code to get started. It covers everything from design and basics to advanced Swift features. And with $9 per month it’s also a very cheap way to bring yourself to the next level. Design+Code was a great help for me, but the course isn’t completely up-to-date. You might run into issues when using the latest version of Xcode and Swift.

Whatever you choose to get started, choose something you can follow and rely on. This gives you a feeling of progress as you’re doing one step at a time. Don’t pick videos or articles from different sources. They may vary in their quality and make it harder in the beginning.

Step 2

One of the best resources for Swift comes straight from the source: The official Swift Book from Apple is by far one of the best programming language books. It contains everything you need to know about Swift. And it won’t cost you anything.

You can start reading it from day one or you can continue with it after you’re done with the first step. This way you will get that “Ahhh” feeling as everything you’ve learned before becomes clearer 🤓

Understanding a language makes your life easier. So why don’t start with the book? Be honest: You’re learning a language because you want to do cool stuff. Not because you want to read a documentation. That’s why it’s good to start practical first.

Step 3

Design plays an imported role in iOS development. Take a look at the apps featured by Apple. They are all very well designed. To succeed on the App Store you need to keep up with them or at least try to.

The Human Interface Guidelines provided by Apple are a must-read before you start with the design of your app.

Apple also provides a lot of helpful resources and insights on their website.

Step 4

There is no better way to learn something than to build and ship. That’s why this step was the one I was most excited about: It was time to start with my app. Two months were left ⏱

At this point you should already be familiar with the basics of Swift and iOS development, but keep in mind that this is your first app. It should be basic and possible to build in short time. Search the internet whenever you’re running into a problem or question. I’ve done this million times during this stage. The “Resources” section includes a few links to help you.

I decided to build a days tracker. An app that counts the passed days since an event occurred. How else should you know when you’ve visited the dentist the last time? Or when you’ve called you parents?

The app is called “The Last Time”. And yes, it’s available on the App Store 🎉

Resources

Here’s a list of resources I’ve used to learn Swift and iOS. My favourites are marked with a star.

• Design+Code is good to get started
• The Swift Programming Language book contains everything you need to know about Swift 🌟
• Cocoacasts offer a clear roadmap to anyone interested in learning Swift development
• The Human Interface Guidelines provided by Apple are must read before you start with your design
• iOS Design Guidelines is a short version of the HIG from Apple, written by Ivo Mynttinen
• Designing for iPhone (iOS 12 native components UI styles) shows you what’s possible to build without writing tons of custom UI
• Sean Allen’s YouTube channel contains fantastic, short tutorials and a great Swift News series 🌟
• Lets Build That App has practical videos that teach you how to build real features 🌟
• iOS Compressed is perfect when you want to learn something in short time
• The.Swift.Dev. is a blog with tutorials and more
• How to Design Scannable App Screenshots is helpful to read before you publish your app

Conclusion

I’m happy that I took the opportunity. I’ve learned so many things in three months that I can’t wait to build more. It’s way easier to continue once you know the basics. Give Swift a try!

Getting the markup right

A good form starts with the right markup.

1. Turn off autocorrect

Turn off autocorrect when you don’t need it: It’s annoying when the system tries to correct something it can’t know. This includes names of persons, streets, companies and cities. Whenever you write an <input> ask yourself: Is the potential value of the input part of a dictionary? When the answer is “No” turn off the autocorrection.

2. Turn off autocapitalize

Turn off autocapitalize when you don’t need it. This might apply to e-mail fields only, but it’s helpful to avoid that the first character of an email is written capitalized.

3. Use autocomplete

The autocomplete attribute lets you control how the browser should populate a given form field. It’s the key for a correctly working autocompletion. Common values for the attribute are name, email, username, new-password and current-password, but the list of values you can use is almost endless.

4. Use required

The required attribute specifies that an input field has to be filled out before submitting the form. Try to use it instead of a JavaScript validation (when possible). It’s better to let the browser do its job instead of reinventing the wheel with a custom validation. Browsers are doing a lot out of the box: A tooltip appears and the input scrolls into view when a user tries to submit an empty required field.

It’s also recommended to indicate that a value is required by adding a hint for the user near the input or its label. Yes, even when all fields are required.

4. Use type and pattern

Touch devices can show a different, optimized keyboard layout for each form field once you told them to do so. For example: They numeric keyboard of the iPhone 6S has a hit-area that is 521% larger than the default touch keyboard. It’s perfect for inputs that accept numeric values only.

Optimized keyboard layouts can be triggered using the type and pattern attributes. There’s also a new inputmode attribute, but it can’t be used in many browsers, yet.

• Use pattern=”[0–9]*” or inputmode=”numeric” to trigger the numeric keyboard
• Use type="email" to trigger the email keyboard
• Use type="url" to trigger the URL keyboard

5. Use labels

Designers and developers like to omit the <label> as it makes the form cleaner and the code and styling simpler, but it plays an important role for users. A form control that solely relies on a placeholder is unidentifiable once it’s filled. This is especially a problem when the form has been filled using autocompletion: Users can’t tell if an input is filled correctly until they remove the value.

6. Use placeholders

Placeholders are hints for users. They should always show a potential value in the expected format. Placeholders like +49 or https:// are perfect to tell your users that they should start phone numbers with the country calling code and links with a protocol.

7. Use disabled

Use the disabled attribute to deactivate inputs. Not a class. I repeat: Not a class. disabled can be applied to all kind of form controls and tells the browser to keep a user from using an element. Adding an additional class to do the styling is fine, but remember that you can also select the element using input[disabled] in CSS.

Getting the usability right

The correct markup already sets the base for a good usability.autocorrect, autocapitalize and autocomplete make it easy to fill the form, using type and pattern ensures that touch devices show an optimized keyboard layout and a placeholder lets the user know what we should insert. But that’s not enough. There’s still a lot you can do wrong when it comes to the styling and overall structure. Here’re three great resources to improve the UX of your forms:

Design Better Forms

Common mistakes designers make and how to fix them. More 👉

UX Movement

User experience blog that helps you improve your interface by demonstrating how good and bad design practices affect user behavior. More 👉

Baymard Institute

E-commerce UX research — uncovering what designs cause usability issues and how to create “State of the Art” e-commerce experiences. The free articles also contain some great posts related to forms and inputs. More 👉

Getting the styling right

Styling a form is a nightmare. Elements ship with their own styling which variates from system to system and from browser to browser. There’s even a multi-page guide on MDN explaining “Why is it so hard to style form widgets with CSS?”.

I’ve spend so much time styling forms that I decided to build a base of default styles for common input elements: formbase eliminates cross browser bugs, inconsistencies across systems and applies a beautiful default styling to several input elements. Zero dependencies, no JavaScript, just CSS.

An alternative to formbase is Boilerform: A little HTML and CSS boilerplate that has been started by an idea from Chris Coyier (A Boilerform Idea). It turned into a project that tries to take the pain away from working with forms.

Markup examples

I would like to end this post with a few examples showing common input fields and their correct attributes. Go back to this section whenever you’re writing a form to ensure that your markup follows the best practices.

Name

Tip: Always use a single name field instead of splitting single input entities.

Company

Postal code

Note: Some countries use letters in their postal code. Make sure to remove the pattern when the user should be able to enter a postal code of one of those countries.

City

Street

Country

Phone

E-Mail

Birthday

How can we achieve a similar effect to make our website stand out, too? Well, it’s not as hard as you might think!

Track the position

The first thing we need is the position of the mouse.

document.querySelector('.button').onmousemove = (e) => {

  const x = e.pageX - e.target.offsetLeft
  const y = e.pageY - e.target.offsetTop

  e.target.style.setProperty('--x', `${ x }px`)
  e.target.style.setProperty('--y', `${ y }px`)
 
}

1. Select the element and wait till the user moves his mouse across it
2. Calculate the position relative to the element
3. Save the coordinates in CSS variables

Yes, only 9 lines of code to let your CSS know where the user positions his mouse. The amount of effects you can achieve with this information is enormous. But let us finish the CSS first…

Animate the gradient

We now have the coordinates stored in CSS variables and we can use them everywhere in our CSS.

.button {
  position: relative;
  appearance: none;
  background: #f72359;
  padding: 1em 2em;
  border: none;
  color: white;
  font-size: 1.2em;
  cursor: pointer;
  outline: none;
  overflow: hidden;
  border-radius: 100px;

  span {
    position: relative;
  }

  &::before {
    --size: 0;

    content: '';
    position: absolute;
    left: var(--x);
    top: var(--y);
    width: var(--size);
    height: var(--size);
    background: radial-gradient(circle closest-side, #4405f7, transparent);
    transform: translate(-50%, -50%);
    transition: width .2s ease, height .2s ease;
  }

  &:hover::before {
    --size: 400px;
  }
}

1. Wrap the text inside a span to avoid that the gradient appears above it
2. Start with a width and height of 0px and bring it up to 400px when the user hovers the button. And don’t forget to set a transition to make it appear with a swoosh 💨
3. Use the coordinates to follow the mouse
4. Apply a radial-gradient to the background and use a closest-side circle. Closest-side fills the whole before without getting beyond it.

The result

That’s it! Add the missing HTML and enjoy your button:

Enormous possibilities

You can build so many effects just by reacting to the position of the mouse. It’s gorgeous and makes so much fun to play with 👌

Here’s a similar animation I’ve used on the website of basicScroll:

Tobias Reich on Twitter

May the hover be with you https://t.co/2jrmVorLRW

Or go fancy and build a 3D parallax button:

Tobias Reich on Twitter

3D parallax button with JS controlled CSS variables @CodePen 🎉 https://t.co/qE0woiNip8 https://t.co/Wyi0xjRzPq

The possibilities are endless. Let us know what you did with it in the comments below 👇

Questions and answers

Why animating width and height instead of using transform: scale()?

The performance when animating width and height is bad and you should always try to use transform where possible. So why am I not doing it like I should? The problem is that browsers are rendering elements (that are transforming) in an accelerated layer. This layer can cause problems when the button has non-rectangular edges.

Edit: There’re ways to use transform, but some browsers don’t like it. Not applying a transition to transform is one potential solution. There’s also a workaround for Safari that might fix those clipping issues.

Why changing top and left instead of using transform: translate()?

See explanation above 👆

Can I follow you on Twitter?

Sure.

Stunning hover effects with CSS variables was originally published in Prototypr on Medium, where people are continuing the conversation by highlighting and responding to this story.

As a front-end developer there is nothing more annoying than losing the control of your HTML after your code has been implemented in the back-end. This typically happens when the HTML isn’t shared between front-end and back-end. But it‘s not the fault of a back-end developer. It‘s the fault of the front-end which failed to provide a good integration into the targeted CMS. Our mission at comwrap was to solve this problem.

The problem

Our existing workflow followed a pattern that allowed us to develop the front-end without caring too much about its later use. HTML, CSS and JS wasn’t tied to a specify CMS. Want to use a different templating engine? No problem, as long as the output (HTML) is the same as before.

The issue with this workflow was that both projects were disconnected. Changing HTML always required to update the implementation in the back-end, too. And that gets out of control as soon as you have to touch more than one line of HTML. You need to communicate every adjustment you’ve made and you need to check if everything has been changed accordingly. And no matter how good you are, spotting a different tag, class or attribute inside the reimplementation is almost impossible. All those little deficiencies quickly sum up to issues that are hard to debug. “It works fine in the front-end” or “I can’t reproduce it” are the resulting answers after a bug has been reported.

“It works fine in the front-end” — Every Front-End developer, always

The challenge

Each team had different preferences and we were looking for a solution that works great for both. In the front-end we preferred to stay with our existing front-end build process that is powered by Rosid. The back-end on the other hand already worked with a component system called Fractal and expected a similar interface and integration. Indeed, Fractal already had what we were looking for. It’s a UI that helps you to build and document components. We tried hard to integrate the system into our build-process, but we had to accept that Rosid and Fractal aren’t playing well together.

The concept of components

Fractal showed us what a solution could look like. It forces the developer of the front-end to write small, reusable components. The back-end then uses the same components and renders them with real data, instead of the dummy data used in the front-end. The components can later be assembled in a variety of ways to build anything from larger components right up to whole pages. This concept isn’t tied to Fractal or a UI in general, but the interface helps you assemble, preview and document those components in a visual way. Brad Frost calls this “atomic design”. I highly recommend the book he wrote to learn more about robust design systems.

The solution

Our research and the concept of Fractal showed us that we were actually looking for two things:

1. Components: A way to share the same HTML between front-end and back-end. This requires a templating engine that works on both sides.
2. UI: A way to visualize components. Great for the whole team as it makes communication easier when you can show what you are talking about.

We decided to use Twig as our templating engine as most developers were already familiar with it.

Finding a UI was way harder than finding a templating engine. In the end we made the step and developed our own system. After two projects we can say with certainty that this was the right move.

Malvid

Let me introduce you to Malvid, our own UI solution. A Node.js module powered by modern technologies, focused on components and rendered blazingly fast with React. We took everything that made Fractal great for us and tried to do it even better. A static site compiler that generates a web-app from a given folder structure of components.

Malvid shows all relevant information at a glance: Your components on the left and a preview, the template, data and notes of the selected component on the right.

Conclusion

Changing a workflow isn’t something that happens over night. It requires a lot of input from your teams, research and brainstorming. But don’t lose yourself in details! You will never know if it works before trying it and you can’t solve everything at once. Your new workflow might crack existing problems, but it also introduces new ones.

Sharing components between front-end and back-end was the right move for us. No matter if Fractal, Pattern Lab or Malvid—try to find a way that works for your company. The switch might be worth it.

1. Hard-coded pre-processing
2. Missing live-reloading

Rosid can be integrated into your project in two ways: Using the CLI or using the API of Rosid. This guide covers the first way and shows you how create and serve a simple project.

1. Install Rosid

First, install or update to the newest version of Node.js. Rosid is written in Node.js, but you only need to know the basics of Node.js and JavaScript to use Rosid. Once it has finished installing, create a new folder, open it in the terminal and run the following npm commands. If you wonder what npm is: It’s a package manager that ships with Node.js. You should already have it installed now 🤘

# Create a package.json file
npm init --yes

# Install Rosid and save it as a dependency in the newly created package.json
npm install rosid --save

2. Setup your project

Rosid is now installed in your project, but needs a few files to do anything useful. Create a new folder called src and add a index.html and main.scss to it. Fill the HTML file with …

<!doctype html>
<html lang="en">
	<head>

		<meta charset="utf-8">
		<title>Rosid</title>

		<link rel="stylesheet" href="main.css">

	</head>
	<body>

		<h1>Hello Rosid!</h1>

	</body>
</html>

… and your SCSS file with …

$background: #55c185;
$color: #fff;

body {
	background: $background;
}

h1 {
	color: $color;
}

3. Install a handler

Rosid is now installed and two files have been added to your project in a folder called src. The HTML needs no processing. It works out of the box and Rosid will send it straight to the browser. The SASS file on the other side needs to be transformed to CSS, because browser don't know anything about SASS.

Let’s use npm again to install an existing handler that handles the transformation of SASS files.

# Install the SASS handler
npm install rosid-handler-sass --save

4. Create a configuration

The handler is now installed, but Rosid has no clue how to use it. It’s up to you to tell Rosid about your newbie. You do so by creating a rosidfile.json in the root of the project. It should contain anything Rosid needs to know.

[
	{
		"name": "SASS",
		"path": "*.{css,scss,sass}",
		"handler": "rosid-handler-sass",
		"opts": {
			"in": ".scss"
		}
	}
]

• name is just a help for you. Rosid logs the activity of the handler with the name you've chosen.
• path uses the same patterns the shell uses. It matches all files with a css, scss or sass extension. Your main.scssis a match and Rosid will transform it with the handler specified in the handler property.
• opts are options. They're different form handler to handler. rosid-handler-sass loads .sass files by default. The in option changes this behaviour to .scss as this is the extension of your file.

5. Start Rosid

It’s time to fire up Rosid. Rosid has been installed into the node_modules directory and you can run the Rosid CLI it contains.

# Start Rosid
./node_modules/.bin/rosid serve src/

Rosid starts and opens your default browser. You should see “Hello Rosid!” in it with a white font on a green background.

6. Compile your project

You don’t need to use the server of Rosid. Export static files using your existing transform-functions and host your site anywhere!

# Compile your project
./node_modules/.bin/rosid compile src/ dist/

What’s next

This was just a taste of what Rosid can do for you. Try the official Skeleton project for more practical examples. Skeleton is a HTML5 Boilerplate built upon Rosid. JS (with Babel, UglifyJS), SASS (with cssnano, Autoprefixer) and EJS can be used right out of the box.

I had the same problem with my modules: The quality of the tests suffered, because it was annoying to write them. This really shouldn’t be the case. I’ve looked at solutions and started to use temp. You might know it if you have ever written tests for file-based modules. temp generates a unique path under the system temporary directory and supports automatic removal 🎉

I liked this solution, but I realized that it’s only half of what I needed. Generated files had to be filled manually and creating complex structures required multiple API calls. Why does it have to be so complicated? Why not using an object to describe a whole structure at once?

The solution

fsify is my attempt to make file-based testing easy.

• Files and folders can be persistent or temporary
• Nested structures can be described in an array of objects
• Files can be filled with content
• Files and directories can have custom or random names
• It works with the output of the Linux and Unix tree command

Creating a structure

.
├── dirname
│   └── filename
└── filename

The given tree can be created with fsify in a few lines of code.

const fsify = require('fsify')()

const structure = [
    {
        type: fsify.DIRECTORY,
        name: 'dirname',
        contents: [
            {
                type: fsify.FILE,
                name: 'filename',
                contents: 'data'
            }
        ]
    },
    {
        type: fsify.FILE,
        name: 'filename',
        contents: 'data'
    }
]

fsify(structure)
    .then((structure) => console.log(structure))
    .catch((err) => console.error(err))

1. Create a new instance of fsify
2. Describe the structure in an array of objects
3. Run fsify with the defined structure

Writing a test

Let’s use Mocha, Chai and fsify together. The imaginary module we want test requires a HTML file and a JSON file with the name of the HTML file + “.data.json”.

.
├── <filename>.html
└── <filename>.data.json

Both files need to be filled with content appropriate to their file type. The main function of the module gets called with the path to the HTML. It should return the original markup filled with data.

const os     = require('os')
const assert = require('chai').assert
const index  = require('./../src/index')

const fsify = require('fsify')({
    cwd        : os.tmpdir(),
    persistent : false,
    force      : true
})

describe('index()', function() {
    
    it('should load HTML and fill it with data from associated data file', function() {
    
        const data = {
            key: 'value'
        }
        
        const structure = [
            {
                type: fsify.FILE,
                name: 'index.html',
                contents: '<p>{{ key }}</p>'
            },
            {
                type: fsify.FILE,
                name: 'index.data.json',
                contents: JSON.stringify(data)
            }
        ]
        
        return fsify(structure).then((structure) => {
            
            return index(structure[0].name)
            
        }).then((output) => {
            
            assert.strictEqual(output, `<p>${ data.key }</p>`)
            
        })
        
    })
    
})

At first we create an instance of fsify with several options.

• cwd: os.tmpdir() All files should be created in the operating system’s default directory for temporary files
• persistent: false Files shouldn’t be persistent. They will be deleted when the process exits.
• force: true Force the deletion of files outside the current working directory

Setup done ✅

Our test starts with data and structure. This part isn’t much different to the first example and should explain itself.

Structure defined ✅

In the last part of the test we call fsify with the structure. The function resolves an array of objects equal to the input, but with an absolute path as the name.

Structure created ✅

We use the absolute path (structure[0].name) and call our imaginary module with it. It resolves the HTML filled with data.

Module tested ✅

Going further

fsify is not only for tests. It can actually create any structure you need and also works perfect in production 🤘

What about random filenames?

The uuid module can be used to create random filenames.

Can I use the output of tree?

Yes. tree has -J flag which prints out an JSON representation of the tree.

Can I set a custom encoding, mode or flag?

encoding, mode and flag are supported. You can specify those options for directories and files.

I’ve made a test project to learn more about them and tried not to use any SASS variables at all. Here’re some of the benefits I discovered:

Eliminate redundant styling

The principle you know from functions in programming languages applies to CSS Custom Properties: Define once, reuse often. No need to write the same code over and over again 😌

Before

.button {
    display: inline-block;
    padding: .5em 1em;
    color: white;
}

.button--red {
    background: red;
    box-shadow: inset 0 0 2px red;
}

.button--blue {
    background: blue;
    box-shadow: inset 0 0 2px blue;
}

After

.button {
    display: inline-block;
    padding: .5em 1em;
    color: white;
    background: var(--color);
    box-shadow: 0 0 2px var(--color);
}

.color-red { --color: red; }
.color-blue { --color: blue; }

The new approach brings several advantages:

• All button styles are now in one place
• Redundant styling has been removed
• Color classes can be used for all elements with dynamic colors

You can even define a fallback value for all your buttons 🤘

background: var(--color, black);
box-shadow: 0 0 2px var(--color, black);

Conditional values

Custom properties can be made conditional with @media and @supports. Changing a variable in a conditional rule affects the properties in which you’ve used the variable. It’s the same behavior as in the previous example. Just with conditional rules.

.warning {
    display: var(--display, none);
    background: red;
}

.warning::before {
    content: 'Your browser does not support ' var(--feature) '.';
}

@supports not (display: flex) {
    .warning {
        --display: block;
        --feature: 'CSS Flexbox';
    }
}

@supports not (display: grid) {
    .warning {
        --display: block;
        --feature: 'CSS Grid Layout';
    }
}

A bridge between HTML and CSS

It’s possible to define CSS Custom Properties in the HTML style attribute to use them in your CSS. Think about an element with a gradient, where the first color is always different. You could apply a gradient using JS or inline styles, but this would either cause a flash of unstyled content or HTML that contains styling.

Before

<!-- HTML -->
<div class="gradient" style="background: linear-gradient(to bottom, red, blue)"></div>
<div class="gradient" style="background: linear-gradient(to bottom, yellow, blue)"></div>

/* CSS */
.gradient {
    width: 100%;
    height: 100px;
}

After

<!-- HTML -->
<div class="gradient" style="--color: red"></div>
<div class="gradient" style="--color: yellow"></div>

/* CSS */
.gradient {
    width: 100%;
    height: 100px;
    background: linear-gradient(to bottom, var(--color), blue);
}

It’s not only easier to read, it also improves the code quality and clarity:

• The gradient definition is back in the CSS file where it belongs to
• Redundant styling has been removed from the HTML

JS controlled variables

CSS Custom Properties can be used in calc() functions to perform a calculation with them. That’s cool, but what if you want more power? JavaScript to the rescue! 💪

JS allows to read and write CSS variables. This gives you all the capabilities of a programming language to generate the content of your variables. It’s so powerful, you can even build a parallax scrolling library with it.

Here’s a demo combing CSS Custom Properties with JavaScript to generate a random gradient on the client-side:

Conclusion

Custom properties are way more than SASS variables. I highly recommend to play around with them in a project. Developing a complete page with them gives you a much better feeling than a simple CodePen experiment. Try to avoid SASS variables to see what you can and can’t do with CSS variables.

A new design

The first big redesign was back in 2012. Another refresh happened late 2013. Now, 4 years later, it was time to move away from the initial branding. It has done its job, but started to look outdated.

I tried to redesign the site several times, but was never satisfied with the result. You sometimes need to put a project aside to collect new inspiration and fresh ideas. It thankfully worked out: The main part of the final design happened in only few hours. I was super happy with it and took it directly into development 🦊 Bright and light colors, whitespace and abstract forms dominate the new design. Concept and layout stayed.

No CMS

Kirby was my CMS of choice for a long time. It still is, but as a developer I’m able to maintain code without any UI or level of abstraction. Especially as I’m the only one working on LaudableApps. There was no reason for me to use a CMS, again.

Static website generators are a big thing and they make hosting simple. You can upload your sites anywhere and don’t need to worry much about security and performance.

Harp.js is a fantastic solution, but limited to its build-in preprocessors. I’ve developed a similar generator called Rosid to solve the issues I had with it. Rosid invokes functions before serving files to the browser. This allows you to transform anything, without saving. And the best: You decide what the function does.

React and SSR

React is my framework of choice when it comes to user interfaces on the web. There’s not much interactivity on LaudableApps. Using a JS library to render HTML for it is unnecessary… but fun 😎

I’ve ensured that all the code I’ve written was isomorphic. This makes it possible to run the JavaScript on both server-side and client-side. Or with other words: The back-end and front-end share the same code. Why? Because I don’t want to send an empty site to the user that then gets filled with HTML when the JS has loaded. When both sides already share the same code, why not pre-executing it on the server? The magic keyword is SSR 💫 Server-side rendering means that we send a filled site to the user that then gets re-rendered when the client JS kicks in. When the used library is smart enough (and React is), it only re-renders what’s necessary.

I previously mentioned that I’m using a static website generator, which means that there’s no server-side. I instead execute the server-side once and save the output to static HTML files. Lets call it pre-executed SSR and pretend it’s a thing…

CSS in JS

It’s crazy. Now that everyone has started to write HTML in JS, people got over-motivated and try to squeeze as much as possible into one language. To be honest: I was skeptical about this, but I thought I should give it a try.

Glamor looked like a good library to get started with. I can’t tell if it’s the best in its class, but it worked fine and I got no trouble with it. And yes, writing CSS in JS has its advantages:

• JS is all you need. You can throw away your SASS workflow.
• Generating CSS based on props you pass to components is delightful.
• All the power of JavaScript is usable, including everything from npm. kowler is one great example of modules you can use. The possibilities are endless.

But it’s not all fun and games 😒

There’re many libraries. Finding the right one takes a while. Some of them don’t even support pseudo classes and media queries. Others don’t allow to extract CSS files. You will run into problems which haven’t existed before. I claim that you never thought: “How can I save the damn CSS into a file?”. Now you will.

Another disadvantage was that glamor uses objects to define styles. Objects are powerful in JS, but it can get pretty ugly when you start to use :hover or @media in them.

css({
  display: 'flex',
  justifyContent: 'space-between',
  alignItems: 'center',
  background: 'rgba(0, 0, 0, .04)',
  ':hover': {
    background: 'rgba(0, 0, 0, .08)',
  },
  [`@media (max-width: 800px)`]: {
    flexDirection: 'column',
    textAlign: 'center'
  }
})

Template strings are an alternative. They are easier to read and some libraries support them, too. It depends on the library and you should take this into mind when choosing one. There’s also a way to use them in glamor, but it’s considered as buggy.

css`
  display: flex;
  justify-content: space-between;
  align-items: center;
  background: rgba(0, 0, 0, .04);
  :hover {
    background: rgba(0, 0, 0, .08);
  }
  @media (max-width: 800px) {
    flex-direction: column;
    text-align: center;
  }
`

Conclusion

I’m happy that I finished the project without getting lost in new libraries. I tried a bunch of new stuff and had some trouble getting SSR and CSS in JS right. The hardest part was the rethinking. How to write JS that works on server and client? How to style elements without a real CSS file?

Let me know what you think and feel free to ask me further questions on Twitter.