DEV Community: SitePoint

Build a Chrome Extension to Streamline Your Workflow

SitePoint — Thu, 14 May 2020 07:56:06 +0000

By James Hibbard. This article was originally published on SitePoint.

When I began as a JavaScript editor at SitePoint, our submission process was something of a mess — articles coming from every direction in a variety of formats. So we decided to standardize things and settled on submission via GitHub in Markdown.

This was a step forward, but we still needed to convert the Markdown into HTML for our WordPress back end. The powers that be at SitePoint HQ at the time had vetoed the installation of any WordPress plugins, which made us consider if we could accomplish this task with a browser extension. Luckily we could!

In the following post, I'm going to demonstrate how you can build your own Chrome extension to add additional functionality to WordPress. I'll also introduce you to SP-Tools, the extension we use at SitePoint to make life as an editor that little bit easier.

The Anatomy of a Chrome Extension

Despite what you might think, building a Chrome extension isn't difficult. Let's start by looking at the various components.

Parts of the following section are borrowed from another tutorial I wrote about building a Chrome extension using Vue.js.

The core piece of any Chrome extension is a manifest file. This is in a JSON format and provides important information about an extension, such as its version, resources, or the permissions it requires.

A manifest file won't do much on its own, so we can use a content script to add some functionality. Content scripts are files that "run in the context of web pages". That is to say, you specify the URL in your manifest file, then when your browser visits a page whose address matches the URL you specified, the content script is injected into the page and run.

To demonstrate these concepts, let’s start by writing a Chrome extension to do something on the SitePoint main site.

Make a new folder called my-extension and two files, manifest.json and main.js:

mkdir my-extension
cd my-extension
touch manifest.json main.js

Open up manifest.json and add the following code:

{
  "name": "My Extension",
  "version": "0.0.1",
  "manifest_version": 2,
  "content_scripts": [
    {
      "matches": [ "*://*.sitepoint.com/*" ],
      "js": [ "main.js" ]
    }
  ]
}

The name, version and manifest_version are all required fields. The name and version fields can be whatever you want; the manifest version should be set to 2 (as of Chrome 18).

The content_scripts key allows us to register a content script (main.js), which will be run whenever we visit SitePoint. Notice how we can use match patterns to specify parts of the URL, such as the protocol.

Now let’s add the following code to main.js to make the browser say hello whenever we visit SitePoint:

alert('Hello there!');

Finally, let’s install the extension. Open Chrome and enter chrome://extensions/ in the address bar. You should see a page displaying the extensions you’ve installed.

As we want to install our extension from a file (and not the Chrome Web Store) we need to activate Developer mode using the toggle in the top right-hand corner of the page. This should add an extra menu bar with the option Load unpacked. Click this button and select the my-extension folder you created previously. Click Open and the extension will be installed.

Now when you visit SitePoint, this will happen:

Congratulations! You just made a Chrome extension.

Background Scripts and Message Passing

So, that dialogue box is pretty annoying right? To finish off this section, let's add a context menu entry to fire it off manually, instead of having it appear on every page load.

This introduces us to another important component of Chrome extensions — background scripts. These scripts can react to browser events (such as a user clicking a context menu entry) and they have full access to Chrome's APIs. However, they don’t have access to the current page, and rely on message passing to communicate with content scripts.

Update the manifest like so:

{
  "name": "My Extension",
  "version": "0.0.1",
  "manifest_version": 2,
  "permissions": [ "contextMenus" ],
  "content_scripts": [
    {
      "matches": [ "*://*.sitepoint.com/*" ],
      "js": [ "main.js" ]
    }
  ],
  "background": {
    "scripts": ["background.js"],
    "persistent": false
  }
}

Notice that we’re requesting the contextMenus permission, as we want to add something to the context menu, and that we’ve registered a non-persistent background script. Making the background script non persistent allows it to be unloaded when it’s not needed.

Next, create a background.js file and add:

chrome.runtime.onInstalled.addListener(() => {
  chrome.contextMenus.create({
    id: 'greet',
    title: 'Say hi',
    contexts: ['page'],
    documentUrlPatterns: ['*://*.sitepoint.com/*'],
  });
});

chrome.contextMenus.onClicked.addListener((info, tab) => {
  if (info.menuItemId === 'greet') {
    chrome.tabs.sendMessage(tab.id, { text: 'greet' }, (res) => {
      console.log(res);
    });
  }
});

We register the context menu entry when the extension is installed, then add an event listener to send a message to our content script whenever the entry is clicked.

Change main.js like so:

chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
  if (msg.text === 'greet') {
    alert('hi');
    sendResponse('I greeted the user');
  }
});

Here, we listen for a message from our background script. If it has a text of "greet", we then fire off the alert and send back a message informing the background script that we did what was requested.

To try this out, head back to the extensions page (at chrome://extensions/), then click the reload icon and reload any SitePoint page. When you right click, you should now see a context menu entry.

Enhancing WordPress' Functionality with a Chrome Extension

Now that we’ve familiarized ourselves with the basic components of a Chrome extension, let's look at how we can make some additions to WordPress' functionality.

To follow along with this section, you’ll need a working installation of WordPress. I installed mine locally. It’s running on an Apache server at http://localhost/wp.

The code for this extension can be found on GitHub.

Adding a Markdown Converter

Let's start by adding a Markdown converter to the WordPress editor. True to the experience on SitePoint, I'll be using the "classic" editor (achieved by installing the Disable Gutenberg plugin) and the Text view.

To begin, create the following folder structure for our new extension:

wp-enhance
├── lib
│   ├── jquery.min.js
│   └── showdown.min.js
├── manifest.json
└── scripts
    └── main.js

On the command line:

mkdir wp-enhance
cd wp-enhance
mkdir lib scripts
touch lib/showdown.min.js lib/jquery.min.js
touch scripts/main.js
touch manifest.json

As you can see, we’ll be using the Showdown markdown converter and jQuery (because I'm lazy).

The first order of business is to grab the latest minified version of these libraries (Showdown and jQuery) and add the contents to the appropriate files.

Next, add the following code to manifest.json:

{
  "manifest_version": 2,
  "name": "WP Enhance",
  "description": "A Chrome extension to enhance WordPress' functionality",
  "version": "0.0.1",
  "content_scripts": [
    {
      "matches": [ "http://localhost/wp/wp-admin/post-new.php" ],
      "js": [
        "lib/jquery.min.js",
        "lib/showdown.min.js",
        "scripts/main.js"
      ]
    }
  ]
}

There's nothing spectacular going on here. The extension is set to run when we visit http://localhost/wp/wp-admin/post-new.php, and we're including the two libraries we just downloaded.

Finally, in scripts/main add the following:

'use strict';

const $editorToolbar = $('#ed_toolbar');
const $mainTextArea = $('#content');

function getShowdownConverter() {
  const converter = new showdown.Converter();

  // Set any options here, for example to add table support
  converter.setOption('tables', true);

  return converter;
}

function addMDButton() {
  const mdConverter = getShowdownConverter();
  const $convertButton = $('<input />', {
    type: 'button',
    value: 'MD',
    class: 'ed_button button button-small',
    title: 'Convert MD to HTML',
    click() {
      const md = $mainTextArea.val();
      const html = mdConverter.makeHtml(md);
      $mainTextArea.val(html);
    },
  });
  $editorToolbar.append($convertButton);
}

addMDButton();

Here, we’re creating a new button and appending it to the WordPress editor's toolbar. When it’s clicked, we’re calling Showdown's makeHtml method, which we pass the contents of the content area. This returns us some HTML, which we then insert back into the editor.

Load the extension and visit the new post page. You should see something like this:

I'm sure you'll agree, that's a reasonably impressive result in just a few lines of code.

Adding a Date Picker to the Publish Widget

Next, we're going to enhance the publish widget with a datepicker. This will replace the series of drop-downs and input boxes that you normally see when you click the Edit link next to the "Publish immediately" message in WordPress' Publish widget.

The first thing we’ll need to do is to download a datepicker. For this demo I'll be using this one. You can download the necessary files from here. Unzip that file and place build/jquery.datetimepicker.full.min.js into our lib folder. Then create a new css folder in the extension and place build/jquery.datetimepicker.min.css into it.

Our extension should now look like this:

wp-enhance
├── css
│   └── jquery.datetimepicker.min.css
├── lib
│   ├── jquery.datetimepicker.full.min.js
│   ├── jquery.min.js
│   └── showdown.min.js
├── manifest.json
└── scripts
    └── main.js

Now include these files in the manifest:

{
  "manifest_version": 2,
  "name": "WP Enhance",
  "description": "A Chrome extension to enhance WordPress' functionality",
  "version": "0.0.1",
  "content_scripts": [
    {
      "matches": [ "http://localhost/wp/wp-admin/post-new.php" ],
      "js": [
        "lib/jquery.min.js",
        "lib/showdown.min.js",
        "lib/jquery.datetimepicker.full.min.js",
        "scripts/main.js"
      ],
      "css": [ "css/jquery.datetimepicker.min.css" ]
    }
  ]
}

Finally, we need to alter our content script (main.js) to look like this:

const $editorToolbar = $('#ed_toolbar');
const $mainTextArea = $('#content');
const $timeStampDiv = $('#timestampdiv');
const $wpSchedulePostDropdown = $('.timestamp-wrap');
let $datepicker;

const $dd = $('#jj');
const $mm = $('#mm');
const $yyyy = $('#aa');
const $hh = $('#hh');
const $mn = $('#mn');

function getShowdownConverter() { ... }

function addMDButton() { ... }

function addDatePicker() {
  $datepicker = $('<input />', {
    id: 'bandaid-datepicker',
    type: 'text',
    placeholder: 'Date and time',
  });

  $datepicker.datetimepicker();
  $timeStampDiv.prepend($datepicker);
}

addMDButton();

$wpSchedulePostDropdown.hide();
addDatePicker();

$datepicker.on('change', function updateDateFields() {
  // String in format yyyy/mm/dd hh:mm
  const dateString = this.value;

  $yyyy.val(dateString.substr(0, 4));
  $mm.val(dateString.substr(5, 2));
  $dd.val(dateString.substr(8, 2));
  $hh.val(dateString.substr(11, 2));
  $mn.val(dateString.substr(14, 2));
});

What we’re doing is getting a reference to the input elements that WP uses to manage the time and date of the scheduled post. We’re then hiding these elements and initializing the datepicker. Whenever a user selects a date, the hidden field is updated and the post can be scheduled.

Reload the extension, then refresh the WordPress new post page. What you have now should look like this:

Again, an impressive result for not much code.

Testing the Extension

One of the things I noticed early on with our SP-Tools extension was that, when WordPress got updated, things would break. So, I got to thinking how I could test the extension and decided that some end-to-end tests with Nightwatch would make sense.

In the following section, I'll demonstrate how we can test our extension in the same way.

First, we'll need to generate a package.json file. In the extension root, run npm init -y. Next, let's install Nightwatch and the ChromeDriver as dev dependencies:

npm install --save-dev nightwatch chromedriver

Now make a testdirectory and add a nightwatch.config.js file, as well as a wp.js file for our test code:

mkdir test
touch test/nightwatch.config.js test/wp.js

Add the following to the config file:

module.exports = {
  src_folders: 'test',
  output_folder: 'test',
  page_objects_path: '',
  custom_commands_path: '',
  custom_assertions_path: '',

  webdriver: {
    start_process: true,
    port: 9515,
    server_path: 'node_modules/.bin/chromedriver',
    log_path: false,
    cli_args: [],
  },

  test_settings: {
    default: {
      desiredCapabilities: {
        browserName: 'chrome',
        chromeOptions: {
          args: [
            'load-extension=./',
            '--test-type',
          ],
        },
      },
    },
  },
};

The important part is 'load-extension=./',, which tells Nightwatch to load our extension into the test browser.

And add the following to wp.js (replacing my login credentials with your own):

module.exports = {
  'Test WordPress Mods': (browser) => {
    browser
      // Login to WP Dashboard
      .url('http://localhost/wp/wp-login.php')
      .setValue('#user_login', 'jim')
      .setValue('#user_pass', 'secret')
      .click('#wp-submit')

      // Go to New Post Page
      .url('http://localhost/wp/wp-admin/post-new.php')

      // Test MD > HTML conversion
      .setValue('#content', '## level 2 heading\n### level 3 heading')
      .click('input[value="MD"]')
      .assert.valueContains('#content', '<h2 id="level2heading">level 2 heading</h2>')
      .assert.valueContains('#content', '<h3 id="level3heading">level 3 heading</h3>')

      // This is here so that you can take a look at the browser
      .pause(5000)
      .end();
  },
};

Now run the tests using:

node_modules/.bin/nightwatch --config test/nightwatch.config.js

You should see an instance of the Chrome browser open and Nightwatch perform the tests we’ve specified. The result of the tests is output to the terminal.

Hopefully Nightwatch's DSL is pretty self explanatory. You can read more about it in their documentation. If you fancy a challenge, try adding tests for the datepicker.

Note that I've hardcoded my credentials here. If you use this for anything other than demonstration purposes, it'll be a good idea to move these to a config file that’s not committed to GitHub.

And don't forget you can find the code for everything I’ve demonstrated so far on GitHub.

Notable Features of SitePoint's Chrome Extension

As I'm sure you've realized, your mileage will vary regarding how useful you find such a browser extension. Most people will have (slightly) different needs and will be able to install WordPress plugins to solve most of the problems they encounter.

Nonetheless, in this final section, I'd like to outline some of the features we have added to our SP-Tools extension in the hope that they might inspire or even be useful for others.

A Capitalize and Check button. This converts the post title to title case.
A headline analysis tool, which gives you a score out of 100 for your title and offers suggestions for improvements.
A Capitalize Subheadings button, which checks the remaining headings in the article for title capitalization.
A Copy Link button, which copies the post's current permalink to the clipboard.
A Rebuild Link button, which rebuilds the post's permalink. This is useful, for example, when WordPress creates a permalink based on a draft heading which subsequently changes.
An extensible molly-guard, which performs a number of checks and disables/enables the publish button accordingly. Among other things, it checks for:
- a sensible post permalink
- the presence of relative URLs in the editor pane
- the presence of empty links in the editor pane
- the presence of <h1> tags in the editor pane
- the presence of [special] shortcode tags in the excerpt
A Copy Tags button, which gives you a comma-separated list of tags copied to the clipboard.
A rel="sponsored" button, which toggles the rel attribute of all links in a post as being sponsored.

If you'd like to check it out, you can find our extension on GitHub. There are a few other goodies in there, such as context menu entries, some code to turn off the infinite scroll on our main site and, of course, tests with Nightwatch.

Conclusion

In this tutorial, we’ve looked at the various components that make up a Chrome extension. I’ve demonstrated how we can build and test our own Chrome extension to enhance the basic functionality of a WordPress install. I’ve also introduced you to SP-Tools, SitePoint's own Chrome extension, which we use to make various editing tasks somewhat easier.

If you find our extension useful, or adapt it to do anything else, I'd love to hear from you on Twitter.

10 Top Chrome Extensions for Your Web Development Workflow

SitePoint — Fri, 06 Sep 2019 02:59:36 +0000

By James Hibbard. Originally published on SitePoint.

As web developers we work in a very fast paced industry and staying on top of things can sometimes be a challenge. That's why I believe we should take full advantage of whatever tools we have at our disposal to help keep our heads above water. Today I'm going to present ten Chrome extensions that are geared to optimizing your web development workflow, hopefully making you that little bit more productive.

What are Chrome Extensions?

As can be read on Chrome's developer portal, extensions are small software programs that can customize your browsing experience. This can be anything from a spelling and grammar checker that checks your writing as you type, to a password manager that saves your login details for your favorite sites.

There are literally thousands of extensions available for Chrome, all of which can be downloaded for free from the Chrome Web Store. You can check which extensions you currently have installed by visiting the following link in your browser: chrome://extensions/.

Why Chrome?

This article focuses on the Google Chrome browser due to its huge market share (currently 65% and rising). There are also many Chrome-based browsers which support extensions. These include Brave, Vivaldi and, coming soon, Microsoft Edge. However, we should remember that Chrome isn't the only show in town and that many of the extensions mentioned here have a Firefox and/or Opera equivalent.

Finally, before we dive into the extensions, take a minute to remember that Chrome is proprietary software published by Google. As we all know, there are privacy concerns associated with using Google products, so maybe head over to GitHub and check out the ungoogled-chromium project instead. As the name suggests, this is Google Chromium, sans integration with Google.

1. Web Developer

We'll start off with the Swiss Army knife of extensions. With over 1 million users and a 4.5 star rating on the Chrome Web Store, Web Developer is something of a must have. It adds a toolbar button to Chrome which, when clicked, displays a plethora of tools that can be used on any web page. These are grouped by category (CSS, forms, images etc) and allow you to do such things as disable JavaScript, outline images with missing alt attributes, resize the browser window, validate a page's HTML, view a page's meta tag information and much more.

You can download it here.

2. Your Framework's Developer Tools

If you're developing an app with a JavaScript framework and you're not using that framework's developer tools, then you're probably doing it wrong. Let me explain using Vue as an example.

If you have a Vue app which you need to debug, or you just want to see what's going on under the hood, then what do you do? Inspecting the page's source will show you the HTML that Vue is rendering, but there is much more to a Vue app than that. What about a component's props, data or computed properties? Or your app's state or routing? How do you inspect any of those?

The good news is that the Vue.js dev tools have you covered. Simply install the extension and open it up on a page running a development build of Vue to see exactly what is happening in your app.

Here are links to download the dev tools for the big three frameworks.

3. Daily 2.0 - Source for Busy Developer

As we work in a fast paced industry, keeping up with news and goings on can sometimes be a challenge. Enter Daily 2.0, an extension that gathers the latest web development and tech posts from around the internet and presents them in an attractive masonry-style lay out on your new tab page.

The extension is easy to use. When you install it you are asked to pick from a bunch of categories that interest you and Daily 2.0 does the rest. Hovering over the sidebar on the new tab page allows you to filter your feed based on tags and sources.

You can get it here.

4. Toggl Button: Productivity & Time Tracker

If you're a busy freelancer, if you work remotely, or if you just need to track the time you're spending on a project, then Toggl is for you.

This extension requires you to create an account before you can use it. Once you're logged in it enables quick and easy real time productivity tracking with all the data stored in your Toggl account. It comes with a built-in Pomodoro timer, as well as integrations for a whole host of internet services (such as GitHub, Trello and Slack). One of my favorite features is that it will pop up a notification when you've been idle and the timer was running, allowing you to discard the time.

Toggl can be downloaded here.

5. Lighthouse

Lighthouse is an open-source, automated tool for improving the performance and quality of your web pages. You can either install it via the Chrome Web Store or, as of Chrome version 60, you can run it directly from the Audits tab of the browser's DevTools (press F12 and select Audits).

Once you have opened Lighthouse, click Generate report and optionally select which audit categories to include. Lighthouse will run the selected audits against the page, and generate a report on how well the page did. From there, you can use the failing audits as indicators of how to improve the page. Each audit also includes links to further reading and potential fixes.

Lighthouse is produced by Google, and presumably uses the same ranking factors as their search engine. This means it can offer you some of the best advice out there on how to optimize your site.

You can grab it here.

6. OneTab

So here's the situation. You're working on your web app when suddenly you run up against an unexpected bug. You spend a couple of hours tracking down a fix and by the time you're finished, you have a whole bunch of tabs open in your browser. Add those to the tabs from the project you were working on yesterday, as well as all those articles you haven't quite got round to reading yet, and pretty soon you find yourself in tab chaos.

This is where the OneTab extension can help you regain a measure of sanity. Whenever you find yourself with too many tabs, click the OneTab icon to convert all of your tabs into a list. When you need to access the tabs again, you can either restore them individually or all at once. Used properly, this extension can give you quite the productivity boost.

OneTab can be downloaded from here.

7. CSS Peeper

CSS Peeper bills itself as a CSS viewer tailored to designers, which allows you to extract CSS and build beautiful style guides. It does this by allowing you to inspect the CSS rules for any element on a page and presenting all of the style information in a simplistic, yet well-organized manner. It also lists all of a page's colors and images, which can be copied to your clipboard, or exported at the touch of a button.

This extension is considerably easier to use than the browser's built-in Inspect Element functionality, the only downside is that you cannot change an element's styles on the fly.

You can find CSS Peeper here.

8. User CSS

This extension goes hand in glove with CSS Peeper, offering a quick and easy way to add custom CSS a web page. Once installed, User CSS is easy to use — you click the extensions icon and enter your styles in the side panel that slides out.

One nice feature of this extension is that your custom CSS styles are persisted. This means you can also use it to permanently hide distracting features on websites you frequent, for example, the trending widget on Twitter.

You can download User CSS here.

9. Web Developer Checklist

Going live with a new project can be stressful at the best of times — there are a whole bunch of things to remember and coordinate. For example, did you remember to validate the site's HTML? Did you check the SEO? What about accessibility checks? Did you run it through Google Page Speed? The list goes on.

This is where the Web Developer Checklist extension can help. It analyses a web page for violations of best practices and allows you to discover problem areas in your website before you hand it off to your client. The extension is a companion to the excellent WebDevChecklist.com.

Web Developer Checklist can be downloaded here.

10. Tampermonkey

Userscripts are little computer programs that allow you to alter the behavior of a web page. These can be used for a variety of tasks, such as tweaking a site's layout to your preferences, adding extra functionality to a page, or automating repetitive tasks.

Tampermonkey is a userscript manager — an extension that allows you to manage and run userscripts, as well as create your own. And it's this last capability that has earned it a place on the list, as you can use Tampermonkey to great effect to streamline your web development workflow. For example, I was recently working on a large form which I needed to test. Instead of manually entering the values every time, I wrote a Tampermonkey script to do that for me, saving me countless keystrokes.

Tampermonkey can be found here.

Conclusion

In this post we have looked at ten of my favorite Chrome extensions to boost your web development workflow. I hope this has given you some inspiration, but please remember that this list is by no means exhaustive.

If I've missed your favorite extension, or you have a gem to share with other readers, I'd be glad to hear from you in the comments below.

Thanks for reading.

📚 7 development articles from SitePoint - August

SitePoint — Fri, 06 Sep 2019 02:53:04 +0000

We've been working hard to provide developers with useful knowledge and unique viewpoints on SitePoint, and would love to show you some of our top articles from August.

5 Super CSS Grid Generators for Your Layouts

CSS Grid has turned out to be the most exciting evolution of CSS for quite a while. It’s a specific CSS tool for building any web layout you can think of, from the simplest to the most complex. Today, CSS Grid is widely supported by all major browsers — it’s clear that the dark days of hacking layouts using floats are gone forever.

➤ Read 5 Super CSS Grid Generators for Your Layouts

How to Create Web Animations with Anime.js

There are many JavaScript animation libraries out there, but Anime.js is one of the best. It’s easy to use, has a small and simple API, and offers everything you could want from a modern animation engine. The library has a small file size and supports all modern browsers, including IE/Edge 11+.

➤ Read How to Create Web Animations with Anime.js

What Every Dev Company Needs to Know about NoOps Development

NoOps is a new development approach that involves relieving developers of needing to constantly work with operations members, speeding up deployment time, testing, and workflow.

➤ Read What Every Dev Company Needs to Know about NoOps Development

How the Top 1% of Candidates Ace Their Job Interviews

You’ve done it. You’ve made it through the initial screening process. You’ve just earned an interview with one of the most prestigious and successful companies in your industry. As you’re waiting in the office with three other candidates, a fourth candidate walks in.

➤ Read How the Top 1% of Candidates Ace Their Job Interviews

How to Use Windows Subsystem for Linux 2 and Windows Terminal

In this article, you’ll learn how you can use Windows Subsystem for Linux 2 to set up and run a local Linux shell interface in Windows without using a virtual machine. This not like using terminals such as Git Bash or cmder that have a subset of UNIX tools added to $PATH. This is actually like running a full Linux kernel on Windows that can execute native Linux applications. That’s pretty awesome, isn’t it?

➤ Read How to Use Windows Subsystem for Linux 2 and Windows Terminal

25+ JavaScript Shorthand Coding Techniques

This really is a must read for any JavaScript developer. I have written this guide to shorthand JavaScript coding techniques that I have picked up over the years. To help you understand what is going on, I have included the longhand versions to give some coding perspective.

➤ Read 25+ JavaScript Shorthand Coding Techniques

How to Redesign Unsplash Using Styled Components

Writing future-proof CSS is hard. Conflicting classnames, specificity issues, and so on, come up when you have to write and maintain thousands of lines of CSS. To get rid of the aforementioned issues, Styled Components was created.

➤ Read How to Redesign Unsplash Using Styled Components

Premium Previews

We've also released a number of extracts from SitePoint Premium on the blog. Check them out:

How to Set Up a Vue Development Environment by James Hibbard
Getting Started with React Native by Wern Ancheta
Master Modern JavaScript with This Curated Reading List by James Hibbard
How to Build a Cipher Machine with JavaScript by Darren Jones

That's it for this month. If you're looking for more, check out our July roundup. Let us know what you'd like to see more of in the comments!

How to Launch a Side Project from Zero

SitePoint — Fri, 23 Aug 2019 04:29:16 +0000

By Amie Chen. Originally published on SitePoint.

Want to launch a side project, but not sure where to begin? Since 2017, I have launched several projects, including Spider, Pretzel, Stitches and Dribbble color palette.

At first, it wasn't clear which steps of the launch process were more important than others. But after my third launch, I had hatched a plan and started tweaking it. In this article, I will share the lessons I learned and walk you through the process of making a product. Hopefully you can take this as a starting point or inspiration, and make something tailored for yourself.

Start by checking out this checklist that I've developed over a number of side projects. Feel free to run with it and adapt it for your own projects.

// Detect dark theme var iframe = document.getElementById('tweet-1116683418425683968-992'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1116683418425683968&theme=dark" }

1. Keep a Problem Notebook

Many of us keep an idea notebook, but I would advocate keeping a “book of grudges”: one with problems and wrongs you find intriguing to solve. Mine is a kanban board with different labels — design, social, security, etc. With these labels, I know what problem could be easily solved with a post-it note, and what could be solved by a clever app. I stare at this board often and maintain it diligently — it tells me what my current priority is, and what the next long term goal is.

2. Know Yourself First

If you’re like me, your book of grudges is extensive. To figure out what is worth spending time on, let’s start with why. Why do you want to create a product?

For me, there are two reasons:

I like helping people and listening to their daily struggles. It gives me different perspectives on life.
Nothing brings me as much joy as making things. The satisfaction of creating something of my own is far greater than any shiny new job or huge paycheque.

With the two causes combined, I noticed I’m drawn to smaller and refined issues. You can spot a trend among all the products I've made — they are utilitarian and focused.

So, ask yourself why to narrow the field of selections. If new technologies and the possibilities they bring fascinate you, maybe an open-ended, AR powered camera app would excite you. Whatever you choose, starting by understanding your cause will help you feel less overwhelmed.

3. Ideation and Design

Once you have a problem to tackle and you’re armed with enough knowledge regarding the problem, it’s time to ideate the solution. During ideation, the only goal is to generate as many solutions as possible without being judgmental. I write my ideas out in a Markdown file and keep the session around 30 minutes.

Sometimes, I sit on this Markdown file for several days while doing more research. Once I decide on an approach, then I can start writing user stories and sketching wireframes. Because these latter two steps both require a clear path, I try to iron out all the doubts and questions beforehand.

Writing user stories is like envisioning how the user would use the product in detail. Here is an example of what I did for Spider:

As you can see, every step explains “what user sees and what user does.” It creates a clear workflow that makes drawing wireframes a breeze.

4. Branding and High-fidelity Mockups

Often times I spend one or two days working on the visual design and branding. Many would argue that's unnecessary for an MVP — but I think there's a value in a good first impression and cohesive branding. Plus, the designer in me really enjoys this part.

To design efficiently, I recommend maintaining a small toolkit that consists of:

an extensive UI kit in Sketch or Figma
a few of your favorite fonts and pairings
a few of your favorite color palettes
a versatile SVG icon library

Also, focus on nailing these design assets first:

The button style in hover and normal state
The body font vs the title
The input style
The navigation

Remember, try not to spend too much time fussing over details.

5. Code It Up

When it comes to development, I (would rather) believe no one spits out beautiful code on the first go. Though time consuming, an iterative approach works better for me. Usually, I start by writing a functional app (with terrible code) to prove the concept. After that, I play with the end result and think about how I can do it better. Finally, I scratch the whole thing and rewrite everything — this time with quality and maintainability in mind. The second iteration should result in better quality code.

The Basecamp team rewrites their app from the ground up every four years. It’s an approach I find necessary if you want to keep a focused product and maintain a manageable code base.

6. Spread the Word

All the usual marketing strategies aside, what I found to be effective is simply telling someone about a thing by showing them how it’d be useful to them. With that in mind, it’s crucial to focus on these things:

A clear elevator pitch for the product
Demo video of how the product can help people
Marketing website with a feature list and FAQ
Documentation
Consistent, high-quality promotion assets for various platforms like Product Hunt/Twitter/email

When people are confused about your product, they move on. Be as honest and clear as you can be — it speaks to people better that way!

Conclusion

We all have something inside that we'd like to share with the world: it could be an idea, a project or a talent. Don't let the imposter syndrome cripple you. More likely than not, you are ready to create something of your own. Add something to the world that only you can add to it.

4 Signs It’s a Bad Idea to Quit Your Dev Job

SitePoint — Wed, 07 Aug 2019 05:42:16 +0000

(& What to Do When You Have to Stay)

By Andrew McDermott. Originally published on SitePoint.

Edwarden, a developer and StackExchange user, wanted advice.

His boss yelled at him for requesting a promotion in the future. Or more specifically, asking for advice on the best process for receiving a promotion. Edwarden exceeded his manager’s expectations. Other managers were also very happy with his performance as well.

His manager also knew what Edwarden wanted to discuss ahead of time.

It didn’t matter.

His manager exploded. He began yelling, shouting and stomping his feet. “You’ve only been here… how many months?! Seven?! And now you’re asking for a promotion!” His manager threw a tantrum and continued to interrupt him until he agreed that he had no “additional concerns.”

Here’s the Advice He Received from Other Users

You should quit your job.

You should look for a new job, I don’t think your boss is going to promote you
How many red flags do you need to see before you look for a new job?
Do yourself a favor and get out
This shows you why the turnover rate is high and why you should try to get out as soon as possible

Is it a bad idea for him to quit his job?

How do you know?

It’s not something we’re taught in school. We graduate, get a job and then we’re just supposed to figure this out on our own. While some of us do, many of us don’t.

That’s the question.

What are the signs that indicate it’s a bad idea to quit your job? First, let’s take a look at some of the more common/obvious answers.

You don’t have another job lined up
You don’t have any savings to carry you through the transition from old to new
You need the money or you aren’t sure you’ll get as much somewhere else

We’re all familiar with the usual reasons given when people suggest that you should stay at a job you obviously would prefer to leave. And you know what? This is solid advice. What about the uncommon and obscure reasons that are more important?

Let’s take a look.

1. You’ll Be Branded as a Job Hopper If You Leave Now

Mark Suster is a well-known entrepreneur and successful venture capitalist. He offers businesses some essential, yet wildly unpopular advice.

Never hire job hoppers.

In his post, Never Hire Job Hoppers. Never. They Make Terrible Employees, he defines a job hopper and explains why it’s so detrimental for companies to hire them. Here’s his subjective definition.

“It’s kind of like that famous saying about art, “you know it when you see it.” If you’re 30 and have had 6 jobs since college you’re 98% likely to be a job hopper. You’re probably disloyal. You don’t have staying power. You’re in it more for yourself than your company. OR… You make bad decisions about which companies you join.

Are you 25 and have worked for 3 companies, each for 18 months? You’re on the borderline. If they are Google, Facebook and then a startup — you’re fine. That’s less than 1%. If you’re 42 and the longest you’ve EVER worked at a company is 3 years — TOAST. That means you’ve likely had 7 short-term jobs since college.”

He basically describes job hoppers as disloyal mercenaries. This kinda, sorta implies that he views these employees as selfish and untrustworthy. This is bad news if you’re looking to quit your job.

Is it true though?

It doesn’t matter whether it’s true or not. Most employers agree with him. Research from Indeed shows 76 percent of employers don’t want to hire job hoppers. Most employers won’t admit that if you ask because, legalities. Research from the Department of Labor validates the frequency of job-hopping.

Here’s some pushback.

A quick Google search shows there are plenty of articles suggesting that attitudes on job-hopping have changed. That it’s the new normal. Many of the people reading these articles feel good. Are you one of those people who feel it’s not as much of an issue as it used to be?

Either way, it’s a complete disaster (for you).

If you’re right, employers have become mercenaries as well. This means employee disloyalty has increased employer disloyalty. It’s easier for them to mistreat their people. If you’re wrong, you’re not going to get the job. Either way, you lose.

Quit prematurely and you may hurt your career in the long term.

2. You May Be Blacklisted

It’s a hotly debated topic.

Do HR blacklists exist? Some HR professionals say they don’t and are insulted by the suggestion that they do. Other professionals (and developers) say they do. Which side is right?

First, the argument for blacklists.

“At a networking event last August in Bellevue, Wash., a recruiter pointed to a software developer across the room. He’s qualified, but “very bad in his presentation skills,” he told career coach Paul Anderson and a human resources official for a big technology concern. “What’s that guy’s name?” Mr. Anderson remembers the HR official asking, and then scribbling the name in her notebook. “I want to add him to our blacklist.”

It gets worse.

“The developer then walked over to the trio to inquire whether the recruiter had found relevant openings for him. The recruiter replied he was still looking. But once the job seeker left, the recruiter “told us he would never submit him to any clients,” Mr. Anderson recalls.”

Mr. Anderson claims he blacklisted prospects during his tenure at Microsoft. Other articles recount a similar story.

Next, the arguments against blacklists.

“Candidates do have a record when they apply to a large company, but each opportunity is on its own merit and we do not use data from other jobs or a “Black List” to disqualify anyone. All recruiters have bias like any other human, and hiring managers do tend to remember bad candidates, but nothing like a Black or Hit List that I have ever witnessed in my 15 years as a recruiter.”

Other HR professionals agree.

“Most companies find its (sic) own ways to make sure that they “remember” why an employee left to avoid rehiring of employees who left on negative terms but there is no shared resource where companies share information about employees. The strongest “weapon” is the reference call.”

What if both sides are right?

A formal blacklist or database that’s shared across several organizations would be an illegal and very risky move. An internal (and informal) “do not hire” list would be more appealing. As we saw earlier, it would be easier to discuss this with recruiters and other HR professionals in a casual setting.

Do you work for an organization that blacklists? Here are a few strategies you can use to detect blacklisting.

Talk to former employees before you quit. You’re looking for a specific scenario. A series of circumstances where new employers were on the verge of hiring these former employees, then suddenly lose interest.
Look for rehires. Does your organization have a large pool of employees who previously left the organization only to be rehired at a later date? This is a very good sign. It’s an indication that revenge isn’t a core value.
Ask former employees how long it took to find a new position. If a large portion of former employees struggle to land a new position, proceed with caution. Have a large number of these employees lost positions they were on the verge of winning? Secure a new position before leaving your current job.

If there’s any chance that you’ll need a reference from your current job in the future these strategies are important to-dos. They’re important even if you’re planning on a career change.

3. You Don’t Have a Replacement Plan

Isn’t this another way of saying you don’t have another job lined up?

Nope.

A replacement plan means you have a plan to find a new position at your ideal company. This plan achieves very specific goals and objectives and is focused on one thing. Hold and carry.

What does that mean?

You’re maintaining and/or improving on your current circumstances. This means you have a plan to…

Establish a mutually beneficial relationship with allies, mentors, influencers, and connectors
Identify and cultivate relationships with ideal companies
Curate a list of sources that feed you a consistent stream of information
Maintain and/or improve on your current salary and benefits package
Protect yourself from negative circumstances in the future (terrible boss, layoffs, firing, etc.)
Identify pathways to promotion, leadership and performance positions ahead of time
Minimize interruptions and downtime due to transition

Use these posts to create a detailed plan of attack before you leave your current job or avoid the unexpected firing. If you don’t have a plan with these details and you decide to quit, you’re rolling the dice.

4. Leaving Means You Hurt Your Co-Workers

This could be a co-worker, manager or friend you’re on good terms with. There are certain situations where leaving makes things worse for the co-workers you leave behind.

Here’s a scenario.

There are three dev teams at your company. All three teams are completely siloed from each other. For some bizarre reason, you’re the only dev who can provide all three teams with the data they need to finish a large project.

But your boss is the worst.

In fact, he’s the reason why you want to quit. He’s made work an unbearable disaster. You’re expected to put out a never-ending series of dumpster fires every day at work. Your boss is responsible for many of them.

Here’s why it may be a bad idea to leave.

If you want to get another job you’re probably going to need a reference, or at the very least, a way to explain the gap in your resume if you decide to omit your current position. Remember the mutually beneficial relationships I mentioned in step three? Your co-workers are part of that list.

Who cares?

An article from Monster outlines the five types of co-workers you need in your inner circle to get ahead in your career (e.g. a friend, HR confidant, mentor with clout, gatekeeper, and competitor). Leaving prematurely (or in a way that hurts your co-workers) destroys these relationships.

Have to leave anyway?

Do your very best to tie up loose ends before you go. Work to make things as easy as you can for your co-workers. Focus on leaving your current company on the very best of terms, even if you hate your current manager.

What should you do if you have to stay at your job?

Staying is an opportunity in disguise. If you’re desperate to leave it certainly won’t feel that way. It’ll probably feel terrible. Many people would recommend that you keep your head down, that you do your best to make it through until you find something better.

There’s a good chance you have other (better) cards to play.

Here’s what I mean.

Search for Dysfunctional Patterns and Problems

The greater the dysfunction and problems at your current company the bigger the opportunity to add significant value. Look for work-related issues you can fix. You’re looking for opportunities that go above and beyond your normal workload. Why on earth would you go to the trouble of working harder for your current company?

Your accomplishment portfolio.

If you’re able to score several big wins at your current organization you have the leverage you need to negotiate a large salary increase at your next position. The more value you add in your current position, the more value you’ll receive (with negotiation) in your next position.

Here’s how your accomplishments factor in.

Anytime you achieve anything of value, no matter how small, you open your notes and you jot it down.

Received a compliment from a manager in another department? Write it down.
Fixed three times as many bugs as the next developer in your company? Write it down.
Have you created libraries and tools for other developers at your company? Write it down.

Don’t Judge, Just Write

Make a list of anything and everything good you’ve done for your company. Make a list of the names, dates and times. You’re looking to create a sizeable list of accomplishments. If you’re looking to turbocharge the effectiveness of your accomplishments, ask your managers or co-workers for feedback.

Keep doing this.

You now have a list of amazing stories you can share on your cover letter, in your resume, and in job interviews. Even better, you have specific names, dates and times which makes your stories powerful and incredibly compelling.

What’s next?

Take Future Co-Workers to Lunch

Remember those mutually beneficial relationships I mentioned in step three? You’re going to go through their LinkedIn contacts list. Reach out to co-workers who have second-degree connections at companies you’re interested in. If you’ve taken the time to serve them, you’re in a good position to request a favor.

It doesn’t matter if these companies are hiring.

Ask your co-workers to make an introduction via LinkedIn or, if you’re concerned about privacy, send these second-degree connections an InMail to introduce yourself. Here’s a template you can customize — just substitute the bold elements.

Hi First Name,

I’m friends with mutual contact. I’d love your advice on …. Can I take you to lunch this week?

Let me know what works best for you.

First + Last Name

You’ll want to identify the five types of co-workers you would need in your inner circle if you received a position at their company. Then, when you’re ready, take them to lunch. Ask them about the things you need to do to earn a job at their company. While you’re chatting, look for ways you can add value.

Rinse and repeat.

If it’s a fit, work to build a genuine relationship with each of these contacts. Invite them out after work. Include them in parties and get-togethers. Why does this work? Research shows employers prefer to hire friends, people they want to hang out with. It’s a straightforward way to earn a position at the organization of your choice.

Sometimes It’s a Bad Idea to Quit Your Job

It’s not something we’re taught in school. When we graduate, we’re told to get a job. Then we’re just supposed to figure these details out on our own. When things go south with our jobs, many of us aren’t sure how to handle it. Sometimes the signs indicate it’s a bad idea to quit your job.

When you have to stay, there are benefits.

We’re all familiar with the usual reasons given when others tell us to stay at a job we want to leave. The usual advice is good advice. But we’re not told how to make the most of a bad situation.

Elite, A player developers know-how.

Now you do too. With the right strategy and tactics, you’ll have the strategies you need to convert a difficult situation into an incredible opportunity.

📚 6 development articles from SitePoint - July

SitePoint — Mon, 29 Jul 2019 05:11:45 +0000

We've been working hard to provide developers with useful knowledge and unique viewpoints on SitePoint, and would love to show you some of our top articles from June.

Learn to Design and Animate in 3D with Zdog

There’s a cool JavaScript library that names like Chris Gannon, Val Head, and CodePen are all raving about. You can also find it on Product Hunt, where it’s been doing rather well. The library is none other than Dave DeSandro‘s Zdog.

➤ Read Learn to Design and Animate in 3D with Zdog

How to Plot Charts in Python with Matplotlib

You generate a huge amount of data on a daily basis. A critical part of data analysis is visualization. A variety of graphing tools have developed over the past few years. Given the popularity of Python as a language for data analysis, this tutorial focuses on creating graphs using a popular Python library — Matplotlib.

➤ Read How to Plot Charts in Python with Matplotlib

4 Signs It’s a Bad Idea to Quit Your Job

Edwarden, a developer and StackExchange user, wanted advice. His boss yelled at him for requesting a promotion in the future. Or more specifically, asking for advice on the best process for receiving a promotion. Edwarden exceeded his manager’s expectations. Other managers were also very happy with his performance as well. His manager also knew what Edwarden wanted to discuss ahead of time. It didn’t matter.

➤ Read 4 Signs It’s a Bad Idea to Quit Your Job

10+ Top Vue.js Tools & Libraries

Vue continues to grow in popularity and is rapidly being adopted by many developers, and Vue.js tools are popping up everywhere. This is not without reason: Vue’s shallow learning curve, clear functionality-driven structure, and excellent documentation make it easy for novices to pick it up, and for more experienced developers to make a switch from other frameworks like React or Angular.

➤ Read 10+ Top Vue.js Tools & Libraries

An Introduction to Cloudflare Workers

Cloud computing in its various incarnations — SaaS, PaaS, IaaS — has had big successes. Some of us still recall the $212 million purchase of PaaS provider Heroku in 2010, which at that time was — architecturally speaking — little more than a high-level deployment layer. It had a very posh gem for smooth and easy deployment of apps and frameworks like RoR, Python or Node apps running on Amazon’s infrastructure. The concept of Serverless Computing was born.

➤ Read An Introduction to Cloudflare Workers

A Beginner’s Guide to Feathers.js

Feathers is built on top of Express, a minimalist web framework for Node.js. If you’ve completed the tutorials demonstrated in the links, you’ll realize that it’s quite tiring building RESTful APIs using just Express. With Feathers, most of the repetitive work is already done for you. You only need to focus on configuring and customizing code. Let’s dive into the code and learn how this web framework works.

➤ Read A Beginner’s Guide to Feathers.js

Premium Previews

We've also released a number of extracts from SitePoint Premium for free on the blog. Check them out:

Build a Real-time Chat App with Pusher and Vue.js by Michael Wanyoike
A Beginner’s Guide to Working With Components in Vue by Kingsley Silas
8 of the Best Design Handoff Tools by Daniel Schwarz
How to Build a Vue Front End for a Headless CMS by Michael Wanyoike

That's it for this month. If you're looking for more, check out our June roundup. Let us know what you'd like to see more of in the comments!

📚 5 development articles from SitePoint - June

SitePoint — Mon, 01 Jul 2019 05:25:31 +0000

We've been working hard to provide developers with useful knowledge and unique viewpoints on SitePoint, and would love to show you some of our top articles from June.

How to Replace Redux with React Hooks and the Context API

"The most popular way for handling shared application state in React is using a framework such as Redux. Quite recently, the React team introduced several new features which include React Hooks and the Context API. These two features effectively eliminated a lot of challenges that developers of large React projects have been facing. One of the biggest problems was ‘prop drilling’ which was common with nested components. The solution was to use a state management library like Redux. This unfortunately came with the expense of writing boilerplate code — but now, it’s possible to replace Redux with React Hooks and the Context API.

In this article, you are going to learn a new way of handling state in your React projects, without writing excessive code or installing a bunch of libraries — as is the case with Redux. React hooks allows you to use local state inside of function components, while the Context API allows you to share state with other components."

➤ Read How to Replace Redux with React Hooks and the Context API.

10 Top Chrome Extensions for Your Web Development Workflow

"As web developers we work in a very fast paced industry and staying on top of things can sometimes be a challenge. That’s why I believe we should take full advantage of whatever tools we have at our disposal to help keep our heads above water. Today I’m going to present ten Chrome extensions that are geared to optimizing your web development workflow, hopefully making you that little bit more productive."

➤ Read 10 Top Chrome Extensions for Your Web Development Workflow.

7 Worst UX Mistakes Limiting Your Growth

"Growth is often the top focus for businesses that are “onto something.” They’ve found what makes customers tick, their special recipe, and now they’re ready for the world to see.

However, scaling doesn’t only scale success.

If there’s friction in the UX, bugs, technical limitations, or any other types of UX flaws, these flaws are magnified as a product scales, which is why the most successful businesses are the ones that take their time and try not to grow too rapidly."

➤ Read 7 Worst UX Mistakes Limiting Your Growth.

How to Set Up a Mobile Development Environment

"The use of mobile devices has increased considerably in the past decade. It has been over two years since mobile browsing took over desktop. The usability of mobile devices has exploded, too. Mobile devices now come with huge processing power.

We often dismiss mobile platforms as serious workhorses for developers, but today, it’s possible to take advantage of mobile portability with a level of flexibility that gets closer to the desktop every year.

This post explains the process of running a Linux development environment from your mobile device using Samsung Dex."

➤ Read How to Set Up a Mobile Development Environment.

How to Get Started with Vuetify

"In this article, you will learn how you can quickly build an attractive and interactive frontend very quickly using Vuetify. Building a friendly application interface with a great user experience is a skill that requires practice and knowledge. While Vuetify won’t make you a skilled UX practitioner overnight, it will help provide a solid start to those who are new in this area."

➤ Read How to Get Started with Vuetify.

Premium Previews

We've also released a number of extracts from SitePoint Premium for free on the blog. Check them out:

Content as UX: Building a More Human Web by Georgina Laidlaw
A Deep Dive into User Research Methods by Mark Seabridge
How Analytics Helped Solve a UX Issue by Daniel Schwarz
Getting Started with Vuex: a Beginner’s Guide by Michael Wanyoike
A Beginner’s Guide to Vue CLI by Ahmed Bouchefra
The 9 Best Mind Mapping Tools for Designers by Daniel Schwarz

That's it for this month. If you're looking for more, check out our May roundup. Let us know what you'd like to see more of in the comments!

📚 7 development articles from SitePoint - May

SitePoint — Thu, 30 May 2019 00:20:53 +0000

We've been working hard to provide developers with useful knowledge and unique viewpoints on SitePoint, and would love to show you some of our top articles from May.

Introduction to Nest.js for Angular Developers

We introduce Nest.js for Angular developers. Nest is a progressive Node framework, written in TypeScript and sharing many concepts with Angular.

Read Introduction to Nest.js for Angular Developers.

6 Collaborative Coding Tools for Remote Pair Programming

Whether you work on a distributed team or just have the occasional problem-solving session with a friend, you'll find a remote pair programming tool here.

Read 6 Collaborative Coding Tools for Remote Pair Programming.

Explore GraphQL with Apollo & React: Build a Superhero Database

We shed some light on what GraphQL is and give you an opportunity for some hands-on experience with Apollo and React.

Read Explore GraphQL with Apollo & React: Build a Superhero Database.

18+ JavaScript Libraries for Creating Beautiful Charts

Learn about 18+ JavaScript libraries for creating charts and graphs — from heavy-duty libraries like D3.js to simple options for representing data quickly and beautifully.

Read 18+ JavaScript Libraries for Creating Beautiful Charts.

How to Launch a Side Project from Zero

Amie Chen shares the lessons she has learned from building her own products, and shows you how to launch a side project.

Read How to Launch a Side Project from Zero.

Why the Highest Paid Developers “Fight” Their Coworkers

At some point, if it hasn't happened already, your coworkers or your boss will ask you to do something foolish.

Read Why the Highest Paid Developers “Fight” Their Coworkers.

Build a Desktop Application with Electron and Angular

In this tutorial we’ll build a cross-platform desktop application with Electron and web technologies such as TypeScript and Angular.

Read Build a Desktop Application with Electron and Angular.

Premium Previews

We've also released a number of extracts from SitePoint Premium for free on the blog. Check them out:

A Beginner’s Guide to Pug by James Hibbard
A Beginner's Guide to Webpack by Ivaylo Gerchev
How to Build a Chrome Extension with Vue by James Hibbard

That's it for this month. If you're looking for more, check out our April roundup. Let us know what you'd like to see more of in the comments!

Why the Highest Paid Developers “Fight” Their Coworkers

SitePoint — Wed, 22 May 2019 04:19:36 +0000

You're going to be asked to do it.

At some point, if it hasn't happened already, your coworkers or your boss will ask you to do something foolish. Something you know will make things worse for you, your coworkers, maybe even the business itself.

If you're like most developers, you do it anyway.

That's what most will do, right? It's better to keep your head down, avoid making waves and simply do what you're told. Job security isn't a thing anymore, but that's one of the best things you can do to keep your job, for a while at least.

This Common Mistake Creates a Career Handicap

This is the problem.

Most employees want to keep their jobs and their clients. They don't have the leverage or control they want over their own careers. They need their job. In fact, most people are terrified of losing their jobs.

This has a cascading effect.

Research shows the fear of losing your job creates job dissatisfaction and a lack of commitment at work. This, in turn, affects job performance, negatively increasing the likelihood that you will lose your job. It's a vicious cycle that seems to repeat itself over and over.

But there's something worse than the fear of a job loss.

It's the misplaced confidence or expectation of job security, the kind of confidence that crushes you when you're actually let go. Both of these issues are a problem, and both of these issues are continually ignored.

Why is it a problem?

Because 78 percent of employees live paycheque-to-paycheque. This includes workers making $100,000+ per year. This is the real reason why most employees have no leverage, no ability to say no. This is the reason most developers won't fight with their coworkers.

Why Developers Need to Fight Their Coworkers

What do I mean by "fight?"

I'm talking about the ability to explicitly confront anyone, regardless of status, about their poor behavior. At some point, you'll be asked to do something you know is wrong. It isn't always a moral issue, sometimes it's a logistics or planning issue. Other times it a performance issue. Here are a few examples:

You're asked to do something questionable
You're instructed to subtly alter or manipulate your end-users
Your boss or a coworker requests work that will break something somewhere else
Your boss or coworker requests work that comes with negative consequences in the future
You're told to ignore, reject or avoid a problem that needs immediate attention
You're asked to cover up a problem or minimize a mistake as a personal favor to someone else
You're implicitly expected to side with a boss' or coworker's bad idea
You'll be expected to push out shoddy or low quality work to meet a pressing deadline
You'll be asked to promise something everyone knows you can't (or shouldn't) deliver
You'll be pushed into situations where you're expected to choose between two very bad outcomes

Okay then, how do I expect developers to "fight?"

Most of the time your conscience tells you. You know when you're supposed to speak up in some capacity, whether it's for yourself or for others. You also know how you feel when you don't.

Fighting could be as simple as:

Continue reading this article by Andrew McDermott on SitePoint.

How to Build Runnable JavaScript Specifications

SitePoint — Tue, 21 May 2019 00:17:09 +0000

By James Kolce. Originally published on SitePoint.

Programming is not only about giving the computer instructions about how to accomplish a task, it’s also about communicating ideas in a precise way with other people, or even to your future self. Such communication can have multiple goals, maybe to share information or just to allow easier modifications—it’s hard to change something if you don’t understand it or if you don’t remember what you did long time ago. Documentation is key, either as simple comments in your code or as whole documents describing the overall functionality of a program.

When we write software we also need to make sure that the code has the intended functionality. While there are formal methods to define semantics, the easiest and quickest (but less rigorous) way is to put that functionality into use and see if it produces the expected results.

Most developers are familiar with these practices: code documentation as comments to make explicit the goal of a block of code, and a series of tests to make sure functions give the desired output.

But usually documentation and testing are done in different steps. By unifying these practices, we can offer a better experience for anyone involved in the development of a project. This article explores a simple implementation of a program to run JavaScript specifications that work for both documentation and testing.

We are going to build a command-line interface that finds all the specification files in a directory, extracts all the assertions found inside each specification and evaluates their result, finally showing the results of which assertions failed and which ones passed.

The Specification Format

Each specification file will export a single string from a template literal. The first line can be taken as the title of the specification. The template literal will allow us to embed JS expressions between the string and each expression will represent an assertion. To identify each assertion we can start the line with a distinctive character, in this case, we can use the combination of the bar character (|) and a dash (-), which resembles a turnstile symbol that can sometimes be found as a symbolic representation for logical assertions.

The following is an example with some explanations of its use:

const dependency = require('./dependency')

module.exports = `
  Example of a Specification File

  This project allows to test JavaScript programs using specification files.
  Every *.spec.js file exports a single template literal that includes a general
  explanation of the file being specified. Each file represents a logical
  component of a bigger system. Each logical component is composed of several
  units of functionality that can be tested for certain properties.
  Each one of this units of functionality may have one or more
  assertions. Each assertion is denoted by a line as the following:

  |- ${dependency} The dependency has been loaded and the first assert has
  been evaluated.

  Multiple assertions can be made for each file:

  |- ${false} This assertion will fail.

  |- ${2 + 2 === 4} This assertion will succeed.

  The combination of | and - will form a Turnstile ligature (|-) using the appropriate
  font. Fira Code is recommended. A Turnstile symbol was used by Gottlob Frege
  at the start of sentenses being asserted as true.

  The intended usage is for specification-first software. Where the programmer
  defines the high level structure of a program in terms of a specification,
  then progressively builds the parts conforming that specification until all
  the tests are passed. A desired side-effect is having a simple way to generate
  up-to-date documentation outside the code for API consumers.
`

Now let's proceed with the high level structure of our program.

The Structure of Our Program

The whole structure of our program can be defined in a few lines of code, and without any dependencies other than two Node.js libraries to work with the filesystem (fs) and directory paths (path). In this section we define just the structure of our program, function definitions will come in the next sections.

#!/usr/bin/env node

const fs = require('fs')
const path = require('path')

const specRegExp = /\.spec\.js$/
const target = path.join(process.cwd(), process.argv[2])

// Get all the specification file paths
// If a specification file is provided then just test that file
// Otherwise find all the specification files in the target directory
const paths = specRegExp.test(target)
  ? [ target ]
  : findSpecifications(target, specRegExp).filter(x => x)

// Get the content of each specification file
// Get the assertions of each specification file
const assertionGroups = getAssertions(getSpecifications(paths))

// Log all the assertions
logAssertions(assertionGroups)

// Check for any failed assertions and return an appropriate exit code
process.exitCode = checkAssertions(assertionGroups)

Because this is also the entry point of our CLI (command-line interface), we need to add the first line, the shebang, that indicates that this file should be executed by the node program. There is no need to add a specific library to handle the command options, since we are only interested in a single parameter. However, you may consider other options if you plan to extend this program in a considerable manner.

To get the target testing file or directory, we have to join the path where the command was executed (using process.cwd()) with the argument provided by the user as the first argument when executing the command (using process.argv[2]). You can find a reference to these values in the Node.js documentation for the process object. In this way we obtain the absolute path of the target directory/file.

Now, the first thing that we have to do is to find all the JavaScript specification files. As seen in line 12, we can use the conditional operator to provide more flexibility: if the user provides a specification file as the target then we just use that file path directly, otherwise, if the user provides a directory path then we have to find all the files that match our pattern as defined by the specRegExp constant, we do this using a findSpecifications function that we will define later. This function will return an array of paths for each specification file in the target directory.

In line 18 we are defining the assertionGroups constant as the result of combining two functions getSpecifications() and getAssertions(). First we get the content of each specification file and then we extract the assertions from them. We will define those two functions later, for now just note that we use the output of the first function as the parameter of the second one, thus simplifying the procedure and making a direct connection between those two functions. While we could have just one function, by splitting them, we can get a better overview of what is the actual process, remember that a program should be clear to understand; just making it work is not enough.

The structure of the assertionsGroup constant would be as follows:

assertionGroup[specification][assertion]

Next, we log all those assertions to the user as a way to report the results using a logAssertions() function. Each assertion will contain the result (true or false) and a small description, we can use that information to give a special color for each type of result.

Finally, we define the exit code depending on the results of the assertions. This gives the process information about how the program ended: was the process successful or something failed?. An exit code of 0 means that the process exited successfully, or 1 if something failed, or in our case, when at least one assertion failed.

Finding All the Specification Files

To find all the JavaScript specification files we can use a recursive function that traverses the directory indicated by the user as a parameter to the CLI. While we search, each file should be checked with the regular expression that we defined at the beginning of the program (/\.spec\.js$/), which is going to match all file paths ending with .spec.js.

function findSpecifications (dir, matchPattern) {
  return fs.readdirSync(dir)
    .map(filePath => path.join(dir, filePath))
    .filter(filePath => matchPattern.test(filePath) && fs.statSync(filePath).isFile())
}

Our findSpecifications function takes a target directory (dir) and a regular expression that identifies the specification file (matchPattern).

Getting the Contents of Each Specification

Since we are exporting template literals, getting the content and the evaluated assertions is simple, we have to import each file and when it gets imported all the assertions get evaluated automatically.

function getSpecifications (paths) {
  return paths.map(path => require(path))
}

Using the map() function we replace the path of the array with the content of the file using the node’s require function.

Extracting the Assertions from the Text

At this point we have an array with the contents of each specification file and their assertions already evaluated. We use the turnstile indicator (|-) to find all those assertions and extract them.

function getAssertions (specifications) {
  return specifications.map(specification => ({
    title: specification.split('\n\n', 1)[0].trim(),
    assertions: specification.match(/^( |\t)*(\|-)(.|\n)*?\./gm).map(assertion => {
      const assertionFragments = /(?:\|-) (\w*) ((?:.|\n)*)/.exec(assertion)

      return {
        value: assertionFragments[1],
        description: assertionFragments[2].replace(/\n /, '')
      }
    })
  }))
}

This function will return a similar array, but replacing the content of each specification with an object following this structure:

{
  title: <String: Name of this particular specification>,
  assertions: [
    {
      value: <Boolean: The result of the assertion>,
      description: <String: The short description for the assertion>
    }
  ]
}

The title is set with the first line of the specification string. Then each assertion is stored as an array in the assertions key. The value represents the result of the assertion as a Boolean. We will use this value to know if the assertion was successful or not. Also, the description will be shown to the user as a way to identify which assertions succeeded and which ones failed. We use regular expressions in each case.

Logging Results

The array that we have built along the program now has a series of JavaScript specification files containing a list of found assertions with their result and description, so there is not much to do other than reporting the results to the user.

function logAssertions(assertionGroups) {
  // Methods to log text with colors
  const ansiColor = {
    blue: text => console.log(`\x1b[1m\x1b[34m${text}\x1b[39m\x1b[22m`),
    green: text => console.log(`\x1b[32m  ✔  ${text}\x1b[39m`),
    red: text => console.log(`\x1b[31m  ✖  ${text}\x1b[39m`)
  }

  // Log the results
  assertionGroups.forEach(group => {
    ansiColor.blue(group.title)

    group.assertions.forEach(assertion => {
      assertion.value === 'true'
        ? ansiColor.green(assertion.description)
        : ansiColor.red(assertion.description)
    })
  })

  console.log('\n')
}

We can format our input with colors depending on the results. To show colors on the terminal we need to add ANSI escape codes. To simplify their usage in the next block we have saved each color as methods of an ansiColor object.

First we want to show the title of the specification, remember that we are using the first dimension of the array for each specification, which we have named it as a group (of assertions.) Then we log all the assertions depending on their value using their respective color: green for assertions that evaluated as true and red for assertions that had another value. Note the comparison, we are checking for true, as a string, since we are receiving strings from each file.

Checking Results

Finally, the last step is to check if all the tests were successful or not.

function checkAssertions (assertionGroups) {
  return assertionGroups.some(
    group => group.assertions.some(assertion => assertion.value === 'false')
  ) ? 1 : 0
}

We check every assertion group (specification) to see if at least one value is 'false' using the some() method of Array. We have nested two of them because we have a two dimensional array.

Running Our Program

At this point our CLI should be ready to run some JavaScript specifications and see if assertions are picked up and evaluated. In a test directory you can copy the specification example from the beginning of this article, and paste the following command inside your package.json file:

"scripts": {
  "test": "node index.js test"
}

… where test is the name of the directory where you have included the sample specification file.

When running the npm test command, you should see the results with their respective colors.

Last Words

We have implemented a very simple but useful command-line program that can help us to make better software. There are some lessons that we can gain from this:

Software can be simple and useful at the same time.
We can build our own tools if we want something different, there is no reason to conform.
Software is more than “making it work" but also about communicating ideas.
Some times we can improve something just by changing the point of view. In this case, the format of the specification files: just a simple string!

An example workflow for this program, would be to place one .spec.js file per module in your projects, describing in detail the intended functionality and properties that the program should have in form of assertions. You can sketch the idea of a new project in this way, and continuously improve until all the assertions have passed.

You can find the source code used in this article here.