Shellscape Software

Plugin to a Fresh Webpack Development Server

2018-11-27T00:00:00+00:00

The developer experience is something that should be continuously improved upon. It is after all, just as important to the daily lives of developers as the user experience is to end-users of our efforts. For bundlers, a great development server and the experience that goes along with one is crucial.

Nearly a year ago, I sat down to try and remedy the development server experience for Webpack by authoring webpack-serve. The webpack-serve project was meant to be a complete replacement for webpack-dev-server; a project that suffers from oodles of quirks and edge cases, development stagnation, extreme legacy support requirements, and an aging architecture increasingly difficult to maintain. Unfortunately, what started as an effort to simplify with webpack-serve was revealed to have its own shortcomings. It was too large a departure from what devs had come to expect, many concepts behind it were too abstract, and it just tried to be too fancy. Following a handoff to the Webpack organization, it was sadly, immediately deprecated. (For users of webpack-serve, the project is now being maintained on this fork.) For all of its faults, webpack-serve was still a step above webpack-dev-server, and was a step in the right direction.

From all that has emerged webpack-plugin-serve - A Development Server fully-contained in a Webpack plugin.

Code Cadre Confab

Unbeknownst to me there was a solid chunk of users who enjoyed what webpack-serve was trying to accomplish. In late September I was approached by a few talented Brazilian developers who were super bummed about Webpack’s decision to shutter webpack-serve. Their idea was to, at the least, fork and maintain webpack-serve. For their taste, webpack-serve was a better choice than webpack-dev-server, despite its own set of quirks. And so we talked about how a fork might look. The idea quickly emerged that this could be a platform to launch a standard experience for many bundlers, not just restricted to Webpack, and it could be accomplished within a plugin.

Targeting Webpack was the most logical starting point. We had a lot of accumulated knowledge about how a server should and shouldn’t interact with Webpack compilers and bundles, and of maintaining webpack-dev-server and authoring webpack-serve. Between that and the real-world, day-to-day user perspective that Matheus and Sibelius were able to provide, we were able to create something really great. Much of this plugin is just “plumbing,” but it’s how that plumbing is arranged that makes this project a stand-out in the space.

Our contributing team on this effort consists of:
@bebraw
@sseraphini
@matheus1lva
@shellscape

(And let me just say how great working with those folks it is! Please give them a follow.)

Scintillatingly Savory

If you’re new to Webpack, it would be a great move to read up on how to use Plugins. webpack-plugin-serve is a Webpack Plugin, a self-contained development server triggered by a Webpack build, and part of the Webpack process. Users must add an instance of the plugin to their Webpack configuration. A configuration might look something like this:

const { WebpackPluginServe: Serve } = require('webpack-plugin-serve');
const options = { ... };

module.exports = {
	entry: [
		'app.js',
		'webpack-plugin-serve/client' // ← important: this is required, where the magic happens in the browser
	],
  plugins: [
    new Serve(options)
  ],
  watch: true  // ← important: webpack and the server will continue to run in watch mode
};

When a Webpack build is initiated, the plugin sets itself up. That includes a Koa application, built-in and user-defined middleware is setup, and a few other static goodies that need to be ready to go down the line. Once a build starts, a web server is spun up and attached to the Koa application, a WebSocket server instance is attached to the web server, and the plugin begins listening to the compiler instance for notification of a refreshed build. If Hot Module Replacement is enabled, it’ll communicate changes via WebSocket to the client/browser and you’ll see changes based on the options passed to the plugin.

There are a myriad of different options available to configure and use the server. We’ve also prepared a few recipes that users can reference to get started, and we’re keen to add more.

Decidedly Different

First and foremost, it’s a plugin. Before starting development to we searched quite a bit to try and find a pre-existing, similar solution. We believe this is a novel approach for Webpack. As a plugin it doesn’t have the learning curve of a separate Command Line Interface and there are no subsets of flags to learn or understand to use it. Plugins are one of the first things that new Webpack users learn about - a perfect entry-point for a bolt-on development server. And by leveraging the compiler directly the server can offload responsibilities, like file watching, to the compiler and can avoid reinventing the wheel, thus reducing complexity.

Just as with webpack-serve, we chose to use WebSockets for server-client communication (the magic that enables Hot Module Replacement instructions in the client/browser). Unlike webpack-serve, we were able to leverage a new “serverless” WebSocket server implementation. We learned from webpack-serve that while the intention behind a secondary WebSocket server was good, it increased complexity and issues with very little benefit.

We also took the approach of building in support for the most popular feature sets of the other two development server options. Only this time around, there’s no getting fancy with it:

User-defined and user-ordered middleware is available, though vastly simplified as compared to webpack-serve
Useful overlays for errors and warnings, and progress are included out of the box, and were developed using a somewhat-standardized approach, and have a sexy, uniform look and feel for a consistent experience.

Features like HTML History API Fallback, Proxying, and Compression have support baked in, though we differ in that options are passed straight through to the underlying dependencies. That makes use and documentation much easier for the end user, as there’s no intermediate layer to have to understand.
Built-in Troubleshooting for common errors:

I’d also argue that this approach is far cleaner than the others that preceded it. We’ve given a lot of consideration to how the feature set might be expanded and have put an architecture in place that should allow for new features to be supported without adding the kind of complexity that cripples maintainability. We learned quite a bit from the shortcomings of both webpack-dev-server and webpack-serve, and really made an effort to improve upon them.

Lastly, and what is sure to be a slightly controversial choice, we chose to support only the Active LTS versions of Node, which is presently v8 and v10, and the Current version (Node v11 as of this post date). We’ve covered why in our FAQ.

Forthright Finale

Moving forward we’re open to adding more features, or developing the modules to provide pass-through features, as use-cases arise. The Node server space is so rich in functionality that we should be able to easily expand webpack-plugin-serveor, most importantly, provide excellent direction for how users can apply needed functionality, easily. Aside from that, the stack is pretty solid. I’m sure the Webpack user-base will surprise us with scenarios we haven’t considered.

We’re just a few developers hoping to provide a better experience for everyone, and would really appreciate folks spreading the word about it. Please don’t hesitate to open an issue or hit us up on Twitter. And if you’d like to help us improve the project, please consider contributing.

Cheers!

Ice Skating Waiter image, via http://historydaily.org/ice-skating-cocktail-waiters

How Webpack and JSF Stole Code, Returned It, and Assigned Bad Copyright

2018-11-03T00:00:00+00:00

Or, Why You Should be Dubious About Contributor License Agreements.

In a corner of the webpack ecosystem lives a small, mostly unnoticed module: webpack-log. webpack is a JavaScript Foundation project and contributions to webpack are subject to the JSF Contributor License Agreement (CLA). In August 2018, a webpack-contrib admin copied code from one of my modules into that project wholesale, verbatim, and without retaining the license. This is a short cautionary story of my efforts trying to get that corrected.

It is likely that this post will be attacked by those passionate about webpack and by those in the organization who dislike me personally. There are many good people whose livelihoods depend upon webpack, the organization, and the donations it receives. If you or your company are donating to the project, please continue to do so. However, if you feel the information in this post demands improvement of the organization, please ask them to do better.

I do not like the spotlight in tech, and I do not seek it. However, I do feel that the information in this post needs to be shared. This post will not name names and will not call out individuals for action, or a lack thereof. Rather, already public information will speak for those involved.

Update (Nov 3rd 2018 23:12 UTC): Since posting and sharing this article, the webpack project has taken steps to remedy the situation. It’s regrettable that it took this article to gain action, but it is appreciated. I don’t have knowledge as to whether or not JSF had a part in the remedy. This article should still serve as a cautionary tale on licensing, copyright, and Contributor License Agreements.

Backstory

I want to quickly share some backstory that I have not shared publicly prior, so that the issue, situation, and links contained in this post have some context for the reader.

In mid June of 2017 I was contacted by webpack leadership to assist on an emergency fix for a somewhat serious SSL security flaw in webpack-dev-server, because I had made some prior contributions to that project. Shortly thereafter I was invited to be a maintainer and, following that a webpack-contrib admin and webpack core team member. I was also introduced to the contributor payment program at the time and actively participated. As a new husband with our first child on the way, that program was massively helpful in starting our new family and I benefited from it.

I created a bunch of new modules for the webpack community in webpack-contrib, and made a concerted effort to challenge the status quo in the project and in the User Experience. One of those modules happened to be webpack-log. To quote a favorite movie, “I fight for the users”. But I was naive. I pushed too hard, too fast and vastly underestimated the deep nepotism and significant hero-worship that exists in the webpack organization. The culmination of which occurred at the same time the organization started to run out of funding, forcing in a change in how donations were allocated and distributed that I vehemently disagreed with. As a core team member, it was my responsibility to make my dissent known. A later, ill-fated effort I undertook to replace the default CLI for webpack resulted in poor communication within the core team, poor decisions by leadership, and was ultimately the straw that convinced me to walk away from the team.

Communication from my end was not perfect. I can be brash, passionate, and have a deep sense of pride and ownership in code that I write. I acknowledge my flaws. Despite 18 months of dedication and work, several new projects for the benefit of users, and huge gains for the webpack user experience, I was subsequently accused of violating a non-existent Code of Conduct, cheating users and the project, labeled a thief, a poor developer, and toxic by most of the organization’s members. Those members who disagreed did not speak publicly in my defense.

I was shunned, an outcast - open dissent is not welcome in webpack.

Enter webpack-log

I got involved in webpack because it was starting to be used by the company I was working for at the time. I was aghast as just how bad the user experience for webpack was. In December 2017 I put together webpack-log to try and give some consistency to the log output webpack and ecosystem tools were generating, and to make my eyes bleed a little less while using it.

Just prior, I had created loglevelnext, which was at the time a fork of the still much-loved and wildly-popular loglevel. I forked because at the time I had proposed changes to loglevel that the maintainer couldn’t agree with. (I love open source for that!). loglevelnext was a project created for work and used primarily by colleagues internally on development environments. I leveraged loglevelnext in webpack-log as a dependency. The feature set was apt and it suited the goals I had for webpack-log both in the console and in the browser.

And so, webpack-log went on to be used in the new webpack-contrib projects I created, webpack modules I maintained, and in several third-party modules, and it sat quietly in the corner.

Curiously Copied Code

Now, I’m not a whore for download counts, but I do check in on them from time to time out of curiosity and for various other reasons. In September, a month after the copy commit to webpack-log, I noticed a steep drop in loglevelnext downloads, and that webpack-log was no longer a dependent of the module. Naturally; I investigated.

Following my falling-out with the webpack organization, nearly all of the projects I contributed were marked [DEPCRECATED], users were notified they were now unmaintained, and code I had contributed was summarily erased from git history altogether. In that same month, loglevelnext was copied wholesale into webpack-log, and removed as a dependency. Weird, but OK.

But not OK. My license for loglevelnext wasn’t retained. My code was effectively stolen. A curious event given the previously mentioned deprecation and git history rewrites.

I immediately thought about filing a DCMA. I would have been well within my right to do so, but that would ultimately hurt the users. Instead, I cringed and decided to open an issue.

The Issue

The Github issue started out plainly enough. Surprising, the organization’s own members weren’t even on the same page as to how the license should be attributed, or whether a standard MIT license could be used with the JavaScript Foundation’s Contributor License Agreement. The maintainer behind the copy commit tried to make it right by adding my name to the project’s LICENSE file, but bungled the attempt. By adding my name to that license file in the way done, they had granted me (and another individual) copyright over the entire project. One might think that’s no big deal, and in the grand scheme of things it’s probably not - but it isn’t correct licensing. What should have been done instead, would have been to include the LICENSE file from loglevelnext in the directory of the copied code. That would have limited my copyright to only my code. Alternatively, they could have pasted the copyright as a header in the file in question.

The crux of the situation now is that by copying loglevelnext into the webpack-log project, effectively hard-forking and adopting the project under JSF-owned webpack-contrib, the user asserted that they could circumvent the JSF adoption process by copying MIT-licensed code into a project and submitting the code under a CLA.

To quote a JSF board member in the issue:

The JS Foundation has a process for adopting projects. Copying the code into a JSF-supported organization while removing the old license (or inserting the JSF license) is definitely not the process. To ensure that we have the legal rights to the software, we need the author(s) to transfer ownership.

What seems to have happened here is that a large amount of someone else’s code was copied from an outside project to this one without attribution, and without the license specified in their code. So now it de-facto appears to have the JSF license (since it’s in this repo) but is not code licensed to the JSF. You can’t avoid having the JSF adopt someone else’s project by copying the whole project source code into yours.

And that’s where the MIT license and the JSF CLA get really, really murky. After that the issue gets testy.

I admit; I was snarky in my final reply before the issue was closed. I should have done better there. I have real trouble abiding false statements about myself, and having someone so completely naive about the situation misrepresenting my intentions. Unfortunately, after that exchange, naming-calling by an organization member ensued and the issue was closed and locked (notably without rebuke). The result of that issue was a ban from webpack and webpack-contrib organization repositories.

The copyright issue however persists, and the webpack/webpack-contrib organization’s members have not addressed it further.

Legal Eagles

After being summarily banned by both webpack and webpack-contrib organizations, I took my grievances to the next logical recourse: JavaScript Foundation’s legal department. Since webpack is a JSF project, I thought their legal department should surely be able to remedy this, given that one of their members are in support of a resolution.

Everyone I conversed with in JSF’s legal department was extremely polite and communication was excellent. That’s pretty much where the positive experience ended. After a month of inaction, I contacted them to let them know of my intention to write this article. Purely as a courtesy and stated as much. A few days later, a new representative for their outside counsel contacted me and stated that some responsibilities had changed hands. They asked for more time and I enthusiastically granted it; I had thought an additional week would be plenty. But after nearly two weeks passed with no visible action, nor resolution, nor statement of position from JSF, I have to consider the interaction with JSF a failure. Unfortunately, concerns shared about inaction from JSF legal seem to prove true.

Given that JSF ultimately holds authority over code contributed under the CLA, this should be a cause for some concern about copyright and the enforcement of the CLA and how it, and your contributions under it, will be handled by JSF and projects belonging to it, moving forward.

In Closing

Be dubious about signing a Contributor License Agreement. Be especially dubious about signing one in which the organization members don’t fully understand their own CLA, and about which the organization who owns the CLA won’t act upon it.

I’ve since moved most of my personal projects to the copy-left Mozilla Public License, which should (hopefully) help to prevent this kind of scenario in the future within any project underneath the JavaScript Foundation.

And finally, if any of my own code or repositories are in violation of copyright or have failed to cite or include license correctly, please let me know and it shall be remedied quickly.

Cheers!

Printing Press Image By African American Photographs Assembled for 1900 Paris Exposition [Public domain], via Wikimedia Commons

Webpack, Now With Extended Flavor!

2018-07-02T00:00:00+00:00

Warning: GIFs and pop-culture references incoming

I’m just crazy psych’d to announce a new feature available to users of webpack-command and webpack-serve. Like, Ken Wheeler in a crisp new pair of America short-shorts excited.

A webpack configuration file can now extend the properties and collections from other sharable or common configurations, and can be done right in the config without installing any additional plugins, modules, or utilities.

The premise here is the same as you’ll find in ESLint and we make no bones about stating that this feature was modeled after ESLint and how that project manages extending configs. The concept of a sharable config directly supported in this manner by a tool goes at least as far back as ESLint 0.21.0 in May of 2015. That’s a while back, and there are certainly early examples. It’s about time that landed for webpack users.

The Chimi-Effing-Changas

So here’s how this works - Take a super bare-bones base config:

module.exports = {
  name: 'base',
  mode: 'development',
  ... <all kinds of fun webpack props>
}

And a config that we want to inherit (or extend from) our base config:

module.exports = {
  extends: <path to base config>
  name: 'batman',
  plugins: [ new BatmanWebpackPlugin() ]
}

And you ✨magically✨ end up with:

module.exports = {
  name: 'batman',
  mode: 'development',
  plugins: [
    new BatmanWebpackPlugin(),
    ... <base plugins>
  ],
  ... <base fun webpack props>
}

OMG that’s so incredible and underwhelming!

Let’s say that you work for a company that maintains a Software As A Service application that’s customized per-client and requires slightly different builds, which are deployed to their own instance. (“Sales Engineers” encounter this often). You might find yourself in the less-than-ideal situation of a base webpack configuration that ends up being copied and pasted, and then tweaked just a tad in each copy, for each client. Now you’ve got the same build logic spread all over digital-hell and back. Messy.

Introduce a sharable config, complexity is instantly reduced, and the client configs now only appear to contain only what needs to be customized.

Alternatives and Existing Solutions

As mentioned before, the concept at its core is not new. A number of NPM modules exist which perform similar functions. The most popular of which is webpack-merge. Many others are obscure and haven’t yet found the same kind of user base that webpack-merge has developed. If you’d rather go with a module and some code around your config, webpack-merge is a great option and we wanted to make sure that project got a shout out.

We didn’t use an existing module to implement this, however. The reasons were many, but the big ones were:

@webpack-contrib/config-loader already handled the task of resolving configs (Functions, Promises, etc)
We found the reduce-right approach functionally superior and performant
Filtering approaches from other modules were more mature, but not as flexible, and so we desired a different architecture to build on
Introducing config property examination for determining extents (base, sharable configs) would have disrupted existing modules significantly

Lobster and Cracked Crab for Everyone

Shared or base configs can also extend other configs, and those can extend yet other configs, and so on, and so on. Recursive extending config happy fun time!

So along with infinitely recursive extendable configs, this feature also has the ability to filter different portions of an extended config by different rules. And of course you can control which filter rules to use. To use filters you’ll have to specify your 'extends' slightly different:

module.exports = {
  extends: {
    configs: <some path>,
    filters: { plugins: 'constructor', rules: 'none' },
  },
  ...
}

You get the idea. Use an Object for 'extends' instead of an Array or String, and specify which filters to affect and what their filtering rule should be. Boom. Done.

The existing filters can perform a rudimentary de-dupe on module.rules and plugins. The default rules filter compares module.rule tests and the plugins filter has the ability to filter on plugin constructor name. You can read more about filtering here.

Presently there are only two filters but we really want to add more based on what you all need. We can’t emphasize that enough.

Have Fun Storming the Castle

There’s no limit to what sharable configurations can look like, or how deeply nested they can be. All-in-all this gives webpack users a lot more flexibility and freedom when authoring many configs. So that’s fun.

There’s also room for improvement, and the use-cases we had to work with to start were limited, and we know that. That said, if this feature can be improved to help you work with webpack a little bit easier or you have filter suggestions, please let us know

Cheers!

webpack-serve Up a Side of Whoop-Ass

2018-02-12T00:00:00+00:00

All aboard the S.S. Shipit. Come, break my things. I present webpack-serve: A lean, modern, and flexible webpack-dev-server alternative. And it’s gonna serve up a big ‘ol side of whoop-ass on your development experience for webpack.

webpack-serve is everything that webpack-dev-server@next was supposed to be, in my mind anyhow. But webpack-dev-server (WDS) had one thing holding it up that was always seen as a negative: over the years so many features were packed into it, that it became a bit of a pill to maintain. Coupled with the inability to embrace modern features, due in part to users with extreme legacy needs, webpack-dev-server is essentially stuck where it is.

A new approach flips the script in a number of ways…

Don’t care about the backstory and just want the goods? Skip to The New Hotness.

Koa

Gone is express and the unneeded complexity and heft of the module in this context. It was convenient, but lighter-weight alternatives weren’t available when WDS was conceived. webpack-serve makes use of Koa and all of it’s bare-bones, greased lightning speed glory.

To make things easy while working with Koa, webpack-serve uses koa-webpack under the hood, which handles wiring up webpack-dev-middleware and a new horse in the race; webpack-hot-client.

API-First Design

One of the long-standing gripes about WDS was the fact that the API and the CLI have never (maybe at one time?) been aligned. There are features that only work on the CLI, options only supported by the CLI, and vise-versa. Not so with webpack-serve. The CLI acts as a CLI should - as a gateway to the API. Naturally there are some limitations as to what can be passed as an option via the CLI, but there is alignment out of the gate none the less.

webpack-hot-client

webpack-hot-client was explicitly written for webpack-serve with the intention of ditching the old Hot Module Replacement client scripts contained within webpack proper to make use of modern features in modern browsers. Namely WebSocket. That does mean that there are some user limitations, but more on that later.

Using this module also means we get some automatic sugar. hot-client injects the necessary client scripts and webpack plugins required to enable HMR. One less thing the user has to handle.

Add Ons

I mentioned earlier on that WDS was a kitchen sink approach. Add-ons seeks to balance the force as the opposite. It’s lean by nature and will only ever contain the most common, most sought after features in a development server. But how you say? Teams of monkeys and hamsters painstakingly ran the numbers. Educated guesses were made. In the future this may be backed up by analytics and real numbers.

And so, add-ons. The idea of an add-on for this server allows the user complete control over the middleware, and the order of that middleware, should they so need. Things like compression, bonjour broadcasting, history api fallback, and request proxying have no business as a core feature. Instead, the user can easily add features to their server. Have a look at some example add-ons which duplicate many of the features found in WDS that are omitted from webpack-serve.

The New Hotness

Using webpack-serve is easier than taking down that first huge Tolberone you bought when you were a kid because hey a big-ass prism of chocolatey goodness was too good to pass up and you can’t like just eat half of it right?

We Better Install It First

$ npm install webpack-serve@next --save-dev

We’re still in pre-release beta, this-could-go-sideways mode, so you’ll need that @next part.

You can also install it globally, though it’s not recommended, and will use a local install if one exists.

CLI

$ webpack-serve --config configs/webpack.config.js

API

'use strict';

const serve = require('webpack-serve');
const config = require('./configs/webpack.config.js');

serve({ config });

Those Damn Gotchas

The tagline for this project, A lean, modern, and flexible webpack development server, is revealing. We’ve covered lean and flexible but there’s that modern bit. The scripts injected into the client webpack bundle(s) loaded by the server rely on browser-native WebSocket. That means the minimum browser requirements are tied to that feature support. This is a hard requirement, and naturally will limit the user-base - those with the need to support the afore mentioned legacy browsers won’t be able to leverage webpack-serve.

Go On, Get You Some

So that’s the gist, the long and the short of what this module is and why it exists. Install it. Tinker. Break it. Open an Issue, or even better, a Pull Request. Make it go bananas.

Cheers!

Signal to Bug Ratio

2017-04-24T00:00:00+00:00

Preface: I work with Signal through my regular job, I’m not promoting the product or service in any way. Signal is a platform for implementing and managing tags and data for marketing, tracking, and affiliates. Debugging Signal events can be very problematic, exacerbated by a lack of tools, guidance on best practices, and engineering support.

Oodles of Noise

Signal events are the de facto method for a client (a web page) to interact with a signal implementation. Typically you bind an event to window and use some JavaScript to trigger an event on window in the client. Sounds easy, yeah? If you happen to work within an environment in which an engineering team doesn’t manage and test data being sent along with these events, debugging that eventData can be far more difficult than it should be. There’s a simple solution to debugging eventData that introduces responsible patterns and ease of use, which go beyond console.log.

Knowledge Gap

I’d like to say right-off-the-bat that my intentions in this section are not to belittle anyone at Signal, but rather raise the flag about related gaps in knowledge within Signal’s support team.

If you approach Signal about a tag implementation, an error with a tag, or pretty much any in-product code need, you’ll wind up talking with an “Implementation Consultant.” For most basic questions and implementation needs, these folks do a good job helping out. However, they are not engineers. Rarely do we receive code from them, or review code they’ve added to our Signal implementation, that would pass review in any corner of our engineering department. Again, this is not to knock their skill level - they aren’t advertised as engineers. But it’s important to understand the distinction, and important to consult engineers for architectural needs and best-practice guidance.

The Console.log Conundrum

At one point in time, our Signal implementation went from being an engineering-first, engineering-owned product, to a Marketing and Analytics owned product. Those teams did a fine job using Signal to drive the associated sites forward with very little JavaScript experience. However, their guidance was coming from non-engineers as well, and at no fault of their own, many anti-patterns were implemented. One of the more egregious was the overuse of console.log.

Our Signal managing teams were advised to use console.log wherever they wanted to view the value/content of eventData for each event that came through Signal. That resulted in well over 50 instances of console.log sprinkled throughout just one of five Dashboards. That’s a hell of a lot of console noise for a single page. Imagine engineers for the site trying to figure out where all the noise was originating, having no knowledge of the Signal implementation nor what it was doing. Bananas!

Simple Engineering Save

Since our implementation is not (yet!) engineering-owned, we can’t run tests and such on the data in a pre-production environment. Some would argue that Signal has some pre-production ability, but even “Previewing” tags and events still runs live in production. So we needed a method for our Marketing and Analytics teams to be able to debug in a familiar way (which is unfortunately console.log) but in a controlled manner that doesn’t affect the world.

The idea is dead simple. Sprinkle bananas.signal.debug(...) all over, anywhere, go bananas! It won’t output to the console until explicitly enabled. That can be done in two ways; by adding ?debug=true to the URI and refreshing, or by calling bananas.signal.enable() in the console before executing an action on the page that will trigger a Signal event.

Only the debugging user will ever see the output. Zero console pollution.

Mind Bottling

You know when things are so crazy it gets your thoughts all trapped, like in a bottle - Blades of Glory

Signal consultants suggested a few variants on the same theme but over all their solutions were either too similar, or too confusing for the non-engineer custodians of our Signal implementation. It’s surprising that something similar and as simple as this isn’t already part of Signal’s client library and available for folks who are using the product without engineering support.

Please feel free to use the script above in your implementation. Or, if you have a better solution, please comment!

Cheers!

Strike a Harmony with Node.js and Harmonica

2017-04-05T00:00:00+00:00

With every new version of Node.js, the platform quietly provides access to experimental features that ship with v8 which may not be quite ready for production use. That doesn’t mean we can’t use those features today, though. And there’s a nearly effortless way to access them.

For those that may be new to Node.js or those who haven’t yet delved into the inner workings of Node.js - the platform runs atop Google’s JavaScript engine, V8 by default. V8 is constantly improving and typically ships with features which may not be stable or ready for production environments, that require command-line flags to enable. Those flags are the harmony flags.

Prior to Node.js v7.6, the asyc/await feature - the feature I’d been most looking forward to - was locked behind the--harmony-async-await flag. There’s a good likelihood that ES6 Modules will arrive in much the same way.

Harmony Flags

Determining what harmony flags are supported by a version of Node.js is easy:

node --v8-options | grep "in progress"

For example, I’m currently on Node.js version 7.8. Running that command, the list of harmony flags shows as follows:

→ node --v8-options | grep "in progress"
  --harmony_array_prototype_values (enable "harmony Array.prototype.values" (in progress))
  --harmony_function_sent (enable "harmony function.sent" (in progress))
  --harmony_sharedarraybuffer (enable "harmony sharedarraybuffer" (in progress))
  --harmony_simd (enable "harmony simd" (in progress))
  --harmony_do_expressions (enable "harmony do-expressions" (in progress))
  --harmony_restrictive_generators (enable "harmony restrictions on generator declarations" (in progress))
  --harmony_regexp_named_captures (enable "harmony regexp named captures" (in progress))
  --harmony_regexp_property (enable "harmony unicode regexp property classes" (in progress))
  --harmony_for_in (enable "harmony for-in syntax" (in progress))
  --harmony_trailing_commas (enable "harmony trailing commas in function parameter lists" (in progress))
  --harmony_class_fields (enable "harmony public fields in class literals" (in progress))

To enable a harmony flag, Node.js typically has to be run from the command-line with the flag and the target entry script as such:

node index.js --harmony_array_prototype_values

Or to enable all harmony flags:

node index.js --harmony

And that can just get tedious for tooling, cross-team development, etc.

An Easy Instrument

Harmonica is an NPM Module that allows developers to use --harmony flags programmatically, which means an end to the need for specifying command-line options for experimental harmony features. If you’ve ever wanted to use experimental features within Gulp tasks, or have a need to run an app through wrappers like forever, this module takes the command-line headache out of the equation.

Setting up Harmonica is painless. Within your entry file (index.js, app.js, etc) place a call to harmonica:

require('harmonica')();

That’s the equivalent to node --harmony. Should you need only specific flags, pass an Array of strings representing the flags you want to enable, without the leading hyphens, as the first parameter.

require('harmonica')([
  'harmony_function_sent',
  'harmony_do_expressions'
]);

And from there, let the module handle initializing the harmony flags you wish to use, with no need to specify them within the terminal or command prompt.

Not All Roses and Rainbows

It’s really important to note that harmony features are not production ready. And as folks have pointed out, some of the experimental / unstable features that are hidden behind harmony flags can come with issues that affect security, performance, etc. It’s never advisable to use harmony features in a production environment unless thoroughly vetted.

Now get to dabbling with the latest that Node.js has to offer!

Cheers!

Floaties for Gulp Users

2017-01-08T00:00:00+00:00

In large or distributed teams, sharing knowledge about tooling can be a challenge. When a toolchain or pipeline gets to be big and contains a lot of code, that challenge grows with the size of the codebase. Providing a solution is as easy as describing your tasks.

gulp-assist

I recently put together gulp-assist as a tool to address that issue. An extension of sorts for Gulp, gulp-assist displays meaningful information on a tooling setup in a stylish format. How meaningful is completely up to the developer providing it.

What about the --tasks and --tasks-simple flags that Gulp already has? Those are great if one wants a basic idea of the structure of the tooling, but gives us nothing if we want to know about the individual tasks.

Floaties and Lifejackets

That all sounds lovely, but what’s this thing look like? GIMME’DA CASSHHH!. As run in the terminal:

And for each individual task including flags, and their descriptions:

Is purty no?

To Inflate, Pull Down On The Tab

This thing really is easy to use, and the few extra keystrokes it costs will undoubtedly save time down the road.

const gulp = require('gulp');

// initialize the module
require('gulp-assist')();

gulp.task('lint', () =>
	// ...
);

gulp.assist('lint', {
  desc: 'Analyzes code for errors and convention violations.',
  flags: {
    src: 'Specifies a directory / module to inspect, within the `src` directory.'
  }
});

Define your tasks as per usual, then register the task with gulp-assist. It’s important to note that gulp-assist needs the task defined with Gulp before it can be registered with gulp-assist. That’s an intentional design decision, but I’m always open to suggestions.

Alternatives

The great thing about Gulp is that there’s a slew of alternatives for any one thing you might want to get done. With that, you might enjoy gulp-help more so than my extension. It hooks the gulp.task method to allow for additional parameters that describe a task.

I didn’t care for this approach as I prefer separation of concerns and dislike modifying established API. I also prefer the output of gulp-assist (but I’m obviously biased).

Cheers!

Pants Optional: Working Remotely

2016-11-28T00:00:00+00:00

I’ve been working remotely for nearly 7 years now, and I couldn’t imagine ever going into an office on a daily basis again. It’s a magical setup that affords incredible freedom, and far more responsibility. I love working remotely, and I’m going to share with you my strategy for working in my own, pants-optional office.

I could never work from home, I’d never get anything done.

That’s the response I typically get from anyone I’ve ever told about my setup. I’ve come to acquire several key lessons and skills that make working remotely a joy, so much so that I doubt I’ll ever again take employment where reporting to an office is a requirement, if I can at all help it.

Never Say Never

The “I could never do it” response from folks isn’t surprising. The last thing most of us want to do at home is think about work. In fact, many smart types will tell you that it’s an unhealthy thing to do. And for those who work the typical 9 to 5 routine, I’d probably agree. But I live the software developer life, and I’ve come to find a method that makes it very easy to be successful remotely.

When Work Isn’t Work

If work is work, you shouldn’t be doing it from home. I’m lucky enough to do something that I’m fairly decent at, and that which I really enjoy. That’s really key. Enjoying the work lets you turn on and off at will without contaminating your home with “the office”. You’ll be able to let ideas flow throughout the day and night. The official hours of your physical office will become more guidelines, whereby you need to stay available, but that which you’re not constrained by.

Pants Are Actually Optional

Just don’t forget them if you’re planning on taking video conference meetings. You don’t want to be that person that has to get up to shut the window and inadvertently shows off those new adventurous undies.

But in all seriousness, get comfortable. Choose a workspace that works best for you. Remember that you’re not in an office! I personally choose to work from my dining table with lots of light and fresh Florida air. Some of my peers prefer a cordoned off basement office. Your workspace should be what keeps you the most comfortable throughout the day.

Part of a great workspace is surrounding yourself with things you love. My kitchen is about 20 feet from my laptop - my inner fat kid loves that. That also means that I have water and other beverages readily accessible. I’ve also got a solid TV on the wall and typically have Netflix going all day long. For me, some kind of white noise and the occasional mental break in close proximity keeps me sane throughout the day.

Creature Feature

Get a pet! They’re an incredible stress reliever and amazing outlet for problem solving. Don’t be afraid to be that crazy person who talks to their animals. Leelu frequently helps me out in a mental bind.

Communicate, Silly

Communication. Communication. Communication. You must go out of your way to communicate with your peers, your supervisors, even the person working at the reception desk in the office. There are reasons, of course:

Communication Builds Trust

Trust in you from your peers is key, and while it would be grand if we were all judged by our merits, many people can’t trust until there’s a base of communication that’s usual and comfortable.

Communication Builds Rapport

Until you’re in the office and have the chance at in-person face time with everyone you work with, you’re the faceless (or single faced avatar) internet person who apparently gets paid by the same company bi-weekly. You may be fortunate and work for a company that has access to video conferencing, but even then you’re still a floating head in a window. Great communication builds a familiarity with your peers that will ultimately aid in collaboration.

Frequent Communication Creates Value

Frequent communication is paramount. Vanishing for extended stretches of time has a negative effect. Remember that you’re not in the office and people can’t see what you’re up to. For all they know you’re out at the pool floating on a giant inflatable swan. When you reach out throughout the day, you’re reminding people that you’re there. When you share what you’re working on frequently, you’re reminding people of the work you’re doing.

Hellooooooo

Working remotely can sometimes feel like a scene out of 28 Days Later. The feeling of isolation is something every remote worker needs to combat on a daily basis. Sometimes it’s a slow day in the office, and others it’s that the physical office is too busy. It’s easy in that frequent situation to get discouraged, frustrated, or just plain bummed out. That’s a good opportunity to step away and right your ship.

Since us remotes are also neglected socializing throughout the day, make up for that deficit when work is done for the day. I’m a social guy and staying in or isolated for too long gets me stir-crazy. I make a concerted effort to socialize after-hours. Befriend some bartenders or others that work outside the 9-to-5 cycle. If you’ve a family, visit with some neighbors or take the kiddies out for something fun around other people.

Halt, and Catch Fire

Take breaks. Take lunches. Take naps. Decline meetings. Run errands. Play with the dog. Go for a walk. Go for a run. Get a hobby and indulge it. Watch an episode of The Walking Dead. Have an adult beverage if you feel the urge. I personally never like to work for more than two hours straight. Halting keeps me fresh and keeps me sane.

Stopping and taking a breath is one of my keys to the gig. Those incredible freedoms I mentioned earlier come into play here. Of course this depends on the company you work for and the folks above or around you in the hierarchy, but take advantage of the ability to do throughout the day what those in an office aren’t able to. Just bear in mind that your responsibility to the work doesn’t end. If you’re going to play a little hookey, remember to make time later to cover your deliverables.

Expand Your Organizational Skills

When no one’s available to chat, you don’t always have the luxury of stopping work and waiting. You’ll have to develop solid organizational skills that will allow you to revisit things that need discussing, or to resume tasks that you’re blocked on down the line. A great degree of self-management is necessary regardless of the kind of management structure you’re working in. A cautious level of independence will go a long way. You won’t always have the time or the opportunity to discuss choices, problems, or solutions with your peers. Which brings us to…

Peer Dependencies

(That’s an NPM pun, for the nerds reading this)

Your peers are going to mean success or failure in a remote gig. When interviewing, make sure you’re asking questions as well. You’ll want to interview the folks doing the interviewing to make sure they know how to work with remote developers. Some companies are freshly wading into hiring remotes, others are seasoned, and yet others have no idea what they’re getting into. Management should be on board with and see value in remote employees. It also helps to jump into a gig with peers that have experience working with remotes. Talk to the folks that will be managing you and your projects to get a feel for how they expect to work with you. Never be afraid to share your ideas early on.

Time For a Whisky

I hope that the lessons I’ve learned can give others in or considering remote work something to think about and help out if needed.

If you’ve been thinking about remote work, there are a plethora of resources that can help:

@RemoteTeams
CultivateNow
Awesome Remote Jobs
Remote-friendly companies
WeWorkRemotely
Remote OK
Jobspresso
Working Nomads

And those are just a few. Good luck!

Cheers!

Rebuilding a Personal Brand

2016-11-18T00:00:00+00:00

Complacency. It’s the worst. Grab a coffee, we’re about to board the failboat. We all know that company brands are of paramount importance. But personal brands are often overlooked. They speak to your abilities, they’re a realtime, interactive, functional resume. And your brand speaks volumes about who you are. What happens when a personal brand falls by the wayside? I learned the hard way.

It’s never crowded along the extra mile. - Wayne Dyer

My personal brand peaked in 2012. I was working with/on the jQuery UI project, I was attending events (thanks much in part to my employers at the time), I was doing some occasional speaking, and my online presence was never more prolific. And then it all went to shit.

Ground Up

I started getting a modicum of notoriety in the Freeware space in the early 2000s with some Windows apps I had written, and it’s what landed me my first job out of college. I built shellscape.org around that, and used it as a landing for all of my projects. As I added more projects, I added a small blog to the site.

It was really “the jQuery Company” that helped build my brand the most. I was one of those people who thought that Twitter was a passing fad and that the concept was silly. But the company asked assertively that I sign up and be active promoting the company’s work, and my own. They pushed me to speak at small gatherings and they got me going to conferences and talking to heavy hitters in the front end development space.

I had solid Twitter followers. I had enough traffic to my site to pull in $200 a month in AdWords.

I’ve Made a Terrible Mistake

At the crux of it, I became complacent. I moved on from the afore mentioned conference-enabling-employer to a really interesting startup, riding on the success of my previous position and my personal brand out in the open. It was a big pay raise and I was doing exactly the work I wanted to do. I was pumped.

It was during the 9 month stint with the startup that I began to let my brand slip. I wasn’t writing blog posts, I wasn’t really contributing to any notable open source projects, I stopped working with jQuery UI. I stopped participating on Twitter in my field. I was happy with my job and my pay, and bought a tear-down investment home that sucked up every minute of my spare time. I was adulting, but I was neglecting the thing that got my career to where it was.

Unfortunately the startup folded on a random Wednesday. I was not prepared for it. Fortunately, and due in large part to my visibility to peers in tech, I was quickly scooped up by a Twitter follower I had never spoken to prior. After a few weeks of interviews, and several competing offers, I started working at Gilt.

I was again awarded an increase in benefits and I was doing insanely cool work. I mean the stuff that makes you want to skip sleep for a week, that makes eating seem like an inconvenience. And there again, I slipped into deeper complacency with regard to my brand.

The Sky is Falling

Gilt was always a tumultuous business; it’s well-documented on a myriad of business websites and blogs. In late 2015 the company underwent significant layoffs. PANIC MODE. Then in early 2016 Gilt was purchased by a larger corporation. Without going into detail - lots of people were very unhappy.

After sticking it out for the first quarter, I decided it was prudent to start looking at what was out there. I was really excited; there were great companies hiring at competitive salaries and even though the field for remote work was narrow (I’ve been working remotely since 2009) it looked like I was in good shape. Fast-forward two months and I was still looking. I’d been passed up by numerous companies. Some passed straight up, and for some I didn’t shine bright enough over other local candidates to warrant a hire. Let alone that I’d fallen into a maintenance culture with day-to-day work, which left me at a slight disadvantage as I wasn’t up and up with the latest tech. But I’d always been able to convince folks that I could pick up easily what I didn’t know (and I could/still can).

There was a deficit somewhere, and I had to identify it.

Mirror Mirror

After a significant amount of reflection and speaking with peers, I zeroed in on three conditions that were affecting my hiring process:

I was way behind on the latest tech.
I had become awful at interviewing.
My personal brand was non-existent.

Now see, I hadn’t had to give a work example or perform a test project for evaluation - ever. Not a single time in my entire career before recently. Sure, I’ve done some live coding but that’s never been a big deal. All of a sudden companies are asking me to build projects for interviews. Only a few took the time to look through my Github account and the work there. I had lost my brand, I had lost the wow factor. Another odd anomaly was that I hadn’t received a single referral. Movement throughout my entire career had been through referrals.

I wasn’t an attractive candidate. Nothing was making me stand out from the crowd. I didn’t seem like an authority on what companies wanted, because I’d become an authority only on proprietary tech within my current position. I lost the edge.

And as such, I was cold-calling folks for interviews who had never heard of me, and who’s recruiting gatekeepers weren’t fluent in the work that I had been doing. Hell, some of them didn’t even know what a “remote employee” was.

The Lessons, They Have Me

I quit looking for new opportunities. I decided instead to use the time I usually reserved for movies or heading to the bar to instead create a foundation for rebuilding what I had lost. And so I spent a few weeks recreating this website. I realigned to treat it as a weekly priority. I talked to a ton of successful bloggers in a range of niches and got solid advice. I spoke with some creative types on how to create a unique feel for the site.

I started publishing again. I started open sourcing and creating projects around segments of the work I was doing daily, and most importantly: whatever I was tinkering with on the side. I started posting to Twitter, LinkedIn, Medium, and Facebook. I got my ass into gear.

Important Things are Important

A personal brand in tech is so damned important. It’s a window into who you are and what you’re doing. It’s a launchpad for anyone who wants to get to know you, before you know, actually speaking to you first. It’s only been a few months and I’m already amazed how my work is making the rounds. It’s a small audience, but it’s an audience and I’m only going to continue to work to increase that.

Don’t be me with cable tv, don’t be this me. If you don’t have an established brand, create one. If you have one, maintain it!

Cheers!

Increasing Build IQ with Travis CI

2016-11-16T00:00:00+00:00

Continuous Integration is a must these days. And for social, open source projects it’s crucial. Our tool of choice for automated testing is Travis CI. Like most tools, Travis does what it does well. Unfortunately it’s not very “smart”. Heaven help you if you have a large or modular project with a multitude of tests - you’ll be waiting an eternity between builds.

And that’s exactly what we ran into. We have a repository that contains 30 NPM modules, each with their own specs (tests). These modules are part of an aging assets pipeline that I briefly mentioned last week. As such each module is subject to a litany of tasks each time a change is made. Travis CI is hooked into the repo and for each Pull Request would run specs for every module, assuring that there are no errors in the code changes contained in the PR. When you’re only working on one or two modules the run-time for the tasks is relatively low; typically 1 - 2 minutes. That of course depends on things such as npm install time, as each module requires an install for testing. Multiply that by 30 and you start to see where the problem arises.

Waiting Sucks

Without targeted build testing we’re left waiting or task-shifting until the build completes successfully. Our need was clear: figure out what files were affected, map and filter the results, and run only the specs for the modules changed in any particular Pull Request or push. That’s where travis-target comes into play.

Here’s a snippet of our repo structure, for reference:

ui-tracking
|--src
   |--common
      |--event_registry
      |--tracking_metadata
   |--tracking
      |--cart
      |--etc..

Target Acquired

In order to target modules, we need to know what their normalized names are; the names that we publish them to NPM under. Because of some legacy stuff baked into our pipeline, we store modules at group/name but publish them as group.name. So let’s fire up travis-target (bear in mind we’re using ES6 syntax that Node v7 supports).

const target = require('travis-target');
const pattern = /^src\//;

let targets = await target();

Let’s pretend that the common.event_registry and tracking.cart modules were both modified in one Pull Request (a common pattern for us) - our results would could look like this:

[
  'README.md',
  'src/common/event_registry/js/event_registry.js',
  'src/common/event_registry/js/registry.js',
  'src/common/event_registry/package.json',
  'src/tracking/cart/js/cart.js',
  'src/tracking/cart/package.json'
]

But that’s just silly, so let’s give travis-target some options to work with:

const target = require('travis-target');
const pattern = /^src\//;

let targets = await target({
  pattern: pattern,
  map: (result) => {
    let parts;

    result = result.replace(pattern, '');
    parts = result.split('/');

    return parts.slice(0, 2).join('.');
  }
});

By passing pattern in options, we’re telling travis-target to filter on (or return only those results which match) the regular expression pattern. That gives us an initial result set of directories starting with src/.

[
  'src/common/event_registry/js',
  'src/tracking/cart/js'
]

You’ll notice that the initial example of results contained some duplicate directories; travis-target cleans that up for you.

Next, we specify the map function on options. That’ll let us transform the each element in the Array of results so that it’s ready to use. Our results would now look like this:

[
  'common.event_registry',
  'tracking.cart'
]

Great Justice

Using this last result set, we now know which modules were affected in the PR, and we know which modules to run specs for. Our next steps are firing off a sequence of shell commands using @exponent/spawn-async, which plays nicely with async/await patterns now supported in Node v7.1 with the --harmony-async-await flag.

Since we implemented this pattern, build times for our PRs are in the 1-2 minute range; a vast improvement and one sure to bring developer happiness in some small degree.