Michael Kühnel // Front-End Developer // Kassel

Stencil and Storybook – How to generate argTypes from JSDoc comments

Wed, 05 Nov 2025 11:00:00 +0000

When using Stencil with Storybook, you’ll quickly notice that Controls don’t work out of the box. This guide shows you how to automatically generate proper argTypes from your JSDoc comments using the Custom Elements Manifest.

The final result: a proper table with controls matching the props types.

The Problem

Storybook for Web Components relies on the Custom Elements Manifest to generate the props/attributes table below your default story from your JSDoc blocks. Even when using correct TypeScript types and JSDoc comments, these don’t automatically translate into proper Storybook Controls without some additional setup.

You’ll end up with “Set object” buttons instead of proper select, radio, or boolean controls to play with your components attributes in Storybook.

Let’s tackle this problem step by step.

1. Generating a Custom Elements Manifest

The Custom Elements Manifest is a JSON file containing metadata about your web components – their properties, attributes, events, and methods. Storybook uses this metadata to automatically generate documentation and controls.

First, install the Custom Elements Manifest Analyzer:

npm install --save-dev @custom-elements-manifest/analyzer

Create a custom-elements-manifest.config.js in your project root:

export default {
  globs: ['src/components/**/*.tsx'],
  outdir: '.',
  exclude: ['**/*.spec.tsx', '**/*.e2e.tsx', '**/*.stories.tsx'],
  dev: false,
  litelement: false,
  catalyst: false,
  stencil: true,
};

Add a script to your package.json:

{
  "scripts": {
    "analyze": "custom-elements-manifest analyze",
    "prebuild": "npm run analyze",
    "build": "stencil build",
    "prestorybook": "npm run build",
    "storybook": "storybook dev -p 6006",
    "prebuild-storybook": "npm run build",
    "build-storybook": "storybook build"
  }
}

The prebuild script ensures the manifest is regenerated before each Stencil build. The prestorybook and prebuild-storybook scripts run the full build (which includes generating the manifest via prebuild) to ensure both the components and the manifest are up-to-date before starting or building Storybook.

Important: Add custom-elements.json to your .gitignore since it’s a generated file.

2. Enriching the Manifest with Type Information

Stencil sometimes omits type information for boolean props in the generated manifest. We need a plugin to fix this:

Create stencil-manifest-plugin.js:

/**
 * Custom Elements Manifest Plugin for Stencil components
 * 
 * This plugin enriches the custom-elements.json generated by Stencil with
 * missing type information and removes internal implementation details.
 * 
 * Functions:
 * 1. Type Enrichment: Transfers type information from @Prop() members to their
 *    corresponding HTML attributes. This is necessary because Stencil sometimes
 *    omits type information in attributes for boolean props.
 * 
 * 2. Member Filtering: Removes internal @State() and other non-public members
 *    from the manifest, keeping only @Prop() declarations with corresponding
 *    HTML attributes.
 * 
 * Used by: Storybook for automatic Control generation
 */
export const stencilEnrichAttributeTypes = {
  name: 'stencil-enrich-attribute-types',
  moduleLinkPhase({ moduleDoc }) {
    moduleDoc?.declarations?.forEach(declaration => {
      if (declaration.members && declaration.attributes) {
        // Create a map from fieldName to member for type lookup
        const memberMap = new Map();
        declaration.members.forEach(member => {
          if (member.name) {
            memberMap.set(member.name, member);
          }
        });

        // Add missing type information to attributes
        declaration.attributes.forEach(attr => {
          if (attr.fieldName && !attr.type) {
            const member = memberMap.get(attr.fieldName);
            if (member?.type) {
              attr.type = member.type;
            }
          }
        });
      }

      // Filter out @State() and other internal members
      if (declaration.members) {
        declaration.members = declaration.members.filter(member => {
          // Keep only @Prop() members (those have an attribute)
          return member.kind === 'field' && member.attribute;
        });
      }
    });
  },
};

Update your custom-elements-manifest.config.js:

import { stencilEnrichAttributeTypes } from './stencil-manifest-plugin.js';

export default {
  globs: ['src/components/**/*.tsx'],
  outdir: '.',
  exclude: ['**/*.spec.tsx', '**/*.e2e.tsx', '**/*.stories.tsx'],
  dev: false,
  litelement: false,
  catalyst: false,
  stencil: true,
  plugins: [stencilEnrichAttributeTypes],
};

3. Configuring Storybook

Storybook’s .storybook/preview.js file is the central configuration for customizing how stories are rendered and controlled. There are several ways to adapt preview rendering – using decorators, loaders, or enhancers. For our use case, we’ll use argTypesEnhancers, which allows us to programmatically generate argTypes based on the Custom Elements Manifest.

Create .storybook/enhance-arg-types.js to handle the argTypes generation:

import customElements from '../custom-elements.json';

/**
 * Enhances argTypes for Storybook based on Custom Elements Manifest
 * Automatically generates proper controls for union types, booleans, numbers, etc.
 */
export function enhanceArgTypes(context) {
  const { component } = context;
  if (!component) return {};

  const componentDef = customElements?.modules
    ?.flatMap((m) => m.declarations || [])
    ?.find((d) => d.tagName === component);

  if (!componentDef) return {};

  const argTypes = {};

  // Attributes/Props
  componentDef.attributes?.forEach((attr) => {
    const name = attr.name;
    
    argTypes[name] = {
      description: attr.description,
      table: {
        defaultValue: { summary: attr.default?.replace(/'/g, '') },
        category: 'attributes',
      },
    };

    if (attr.type?.text) {
      const text = attr.type.text;
      
      // Handle union types like 'info' | 'success' | 'error'
      if (text.includes('|')) {
        const options = text
          .split('|')
          .map(v => v.trim().replace(/['"]/g, ''));
        
        argTypes[name].control = {
          type: options.length <= 3 ? 'inline-radio' : 'select',
        };
        argTypes[name].options = options;
      } else if (text === 'boolean') {
        argTypes[name].control = { type: 'boolean' };
        argTypes[name].type = 'boolean';
      } else if (text === 'number') {
        argTypes[name].control = { type: 'number' };
      } else {
        argTypes[name].control = { type: 'text' };
      }
    }
  });

  // Events
  componentDef.events?.forEach((event) => {
    argTypes[event.name] = {
      description: event.description,
      table: {
        category: 'events',
        type: { summary: event.type?.text || 'CustomEvent' },
      },
      control: false,
    };
  });

  return argTypes;
}

Now update your .storybook/preview.js:

import { setCustomElementsManifest } from '@storybook/web-components';
import customElements from '../custom-elements.json';
import { defineCustomElements } from '../dist/loader';
import { enhanceArgTypes } from './enhance-arg-types.js';

setCustomElementsManifest(customElements);
defineCustomElements();

const preview = {
  parameters: {
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
      hideNoControlsWarning: true,
    },
  },
  argTypesEnhancers: [enhanceArgTypes],
  tags: ['autodocs']
};

export default preview;

Writing Your Stories

With the global enhancer in place, your stories become much simpler by ommiting the argTypes and only providing the default args values:

import type { Meta, StoryObj } from '@storybook/web-components-vite';
import { html } from 'lit';

const meta: Meta = {
  title: 'Components/Alert',
  component: 'my-alert',
  tags: ['autodocs'],
};

export default meta;

export const Alert: StoryObj = {
  args: {
    variant: 'info',
    text: 'Here is the info text',
    'has-close-button': true,
  },
  render: (args) => html`
    <my-alert
      variant=${args.variant}
      ?has-close-button=${args['has-close-button']}
    >${args.text}</my-alert>
  `,
};

Important notes:

Use kebab-case for attribute names in args ('has-close-button' not hasCloseButton)
Use Lit’s boolean attribute syntax ?attribute-name for boolean props
Slots can be added as regular args and rendered as children

Example Component

Here’s how to properly document your Stencil components:

import { Component, Host, h, Prop } from '@stencil/core';

/**
 * Component for an alert box.
 */
@Component({
  tag: 'my-alert',
  styleUrl: 'my-alert.scss',
  shadow: true,
})
export class MyAlert {
  /**
   * Variant of the alert.
   * @type {'info' | 'success' | 'error' | 'warning'}
   * @default 'info'
   */
  @Prop() variant: 'info' | 'success' | 'error' | 'warning' = 'info';

  /**
   * Whether the close button should be displayed.
   * @type boolean
   * @default true
   */
  @Prop() hasCloseButton = true;

  render() {
    return (
      <Host>
        <div class={`alert alert-${this.variant}`}>
          <slot />
          {this.hasCloseButton && (
            <button type="button">
              <i class="fa fa-close" />
            </button>
          )}
        </div>
      </Host>
    );
  }
}

The JSDoc comments are essential for proper documentation:

@type defines the type (will be parsed for union types)
@default shows the default value in Storybook
Description appears in the Controls panel

Result

With this setup, Storybook will automatically:

Generate radio buttons or select dropdowns for union types
Create boolean toggles for boolean props
Display text inputs for strings
Show number inputs for numbers
List events in the events category

No manual argTypes configuration needed in your stories!

Additional Resources

How to flash ESP8266 (and ESP32) to use Espruino firmware on macOS

Tue, 16 Jul 2019 23:34:16 +0000

Espruino is a firmware with an integrated JavaScript interpreter for microcontrollers coming with it’s own IDE. So it’s possible to run JavaScript natively on the most affordable microcontrollers like the ESP8266. This Guide helps you to set things up to explore the possibilities of the Internet of Things using the language of the web.

About Espruinos JavaScript abilities

Espruino sports a subset of ES6 features as shown in the language feature list. You’ll find the comprehensive API documentation including built-in modules on the website as well.

The module system is similiar to CommonJS but you won’t be able to use the npm eco system. Learn more about Espruinos modules.

Espruino compatible microcontrollers

Espruino sells different own development boards with various hardware features that are specifically designed to work with this firmware. Fortunately, Espruino can also be used with other, much cheaper boards.

I recommend using a development board (D1 Mini or NodeMCU) based on the ESP8266 or ESP32 depending on your needs. The main difference (beside the size and the price) is that the ESP32 comes with Bluetooth 4.2 and Bluetooth low energy in addition to the WI-FI capabilities of the ESP32. See this comparison to make your choice.

Install macOS drivers

Download and install one of the following drivers to be able to successfully connect your development board via USB to your Mac:

Load and enable the extensions

Since macOS High Sierra you have to load and enable the drivers after the installation.

Loading the ESP8266 driver in the Terminal:

sudo kextload /Library/Extensions/usbserial.kext

Loading the ESP32 driver in the Terminal:

sudo kextload /Library/Extensions/SiLabsUSBDriver.kext

Important:
After loading the driver you have to approve the usage by clicking the »Allow« button in the »Security & Privacy« system preferences panel.

Install esptool

You need a command line tool called »esptool« to be able to flash your ESP based development board. You can get it via HomeBrew:

brew install esptool

Flashing

Connect your ESP via USB to your Mac.

Check connectivity

Enter the following to figure out if you verything is set up properly:

esptool.py flash_id

If the driver is correctly installed and activated your Terminal should respond with something like:

esptool.py v2.6
Found 5 serial ports
Serial port /dev/cu.wchusbserial1440
Connecting....
Detecting chip type... ESP8266
Chip is ESP8266EX
Features: WiFi
MAC: 84:f3:eb:ed:6d:54
Uploading stub...
Running stub...
Stub running...
Manufacturer: 68
Device: 4016
Detected flash size: 4MB
Hard resetting via RTS pin...

Port

Serial port /dev/cu.wchusbserial1440 tells us which port to use for flashing the ESP and transfering code to it later..

Note: Your port may differ.

Download firmware

Visit http://www.espruino.com/Download to get the latest Espruino release:

Choose your board (ESP32 respectively ESP8266)
Click the following link
- for ESP8266:
  
  Release: espruino_[latest-version]_esp8266_4mb/ (Directory)
- for ESP32:
  
  Release: espruino_[latest-version]_esp32/ (Directory)
Create a directory and download all files

Erase your board

Enter the following to erase the flash of your board:

esptool.py --port /dev/<port> erase_flash

Note: Replace <port> with your port.

Write firmware

Note:

Replace <path/to/firmware> with the directory directory containing the downloaded firmware files.
Replace <port> with your port.

ESP8266

$ cd <path/to/firmware>
$ esptool.py                                    \
    --port /dev/<port>             \
    --baud 115200                               \
    write_flash                                 \
    --flash_freq 80m                            \
    --flash_mode qio                            \
    --flash_size 32m                            \
    0x0000 boot_v1.6.bin                        \
    0x1000 espruino_esp8266_user1.bin           \
    0x3FC000 esp_init_data_default.bin          \
    0x3FE000 blank.bin

ESP32

$ cd <path/to/firmware>
$ esptool.py                                    \
    --chip esp32                                \
    --port /dev/<port>               \
    --baud 921600                               \
    --after hard_reset write_flash              \
    -z                                          \
    --flash_mode dio                            \
    --flash_freq 40m                            \
    --flash_size detect                         \
    0x1000 bootloader.bin                       \
    0x8000 partitions_espruino.bin              \
    0x10000 espruino_esp32.bin

Testing aka Hello World

Horray, We should now be able to run JavaScript on the board 🎉

Let’s check if everythings works like expected:

Install the Espruino Web IDE
Set the correct connection speed
1. ESP8266: Settings → Communications → Baud Rate → 115200
2. ESP32: Settings → Communications → Baud Rate → 921600
Hit the »connect« button in the upper left corner

Enter the following code to interact with the built in LED:

 // ESP8266
 const pin = 2;
  
 // ESP32
 //const pin = 8;
  
 let on = 0;
 digitalWrite(pin, on);
 setInterval(() => {
   on = on === 0 ? 1 : 0;
   digitalWrite(pin, on);
 }, 100);

Hit the »Send to Espruino« button to transfer the code to your board

Tip: See Espruinos Quick Start for writing code Espruino IDE to learn more.

Espruino CLI as alternative to using Espruino IDE

The Espruino CLI can be used to send the code your are writing with any code editor to your board.

This way you can use the features of the IDE/editor you are used to when writing JavaScript.

Install

npm install espruino -g

Enter espruino -h to see all available options.

List all available devices and exit

espruino --list

Useful snippets

Note: Replace /dev/<port> with your port and the baud rate from 115200 to 921600 when using an ESP32.

Reset the code on your board

espruino -p /dev/<port> -b 115200 -e 'reset(); digitalWrite(2, 1); save();

Push code to board

espruino -p /dev/<port> -b 115200 filename.js

Push code to board and save

espruino -p /dev/tty.wchusbserial14110 -b 115200 -e 'save()' filename.js

Additional links

Helpers and tips for npm run scripts

Thu, 22 Mar 2018 23:30:00 +0000

The purpose of this blog post is not to introduce using npm as a build tool. There are lots of good articles about the »where« and »why«. I would like to present some hidden gems to potentially improve your setup instead.

I’d like to point to Why npm Scripts? if you want to read an introduction to the benefits of using CLI tools via npm scripts in favor of a task runner like Gulp and their plugin eco system.

Introduction

You can easily run scripts using npm by adding them to the "scripts" field in package.json and run them with npm run <script-name>. Run npm run to see available scripts. Binaries of locally install packages are made available in the PATH, so you can run them by name instead of pointing to node_modules/.bin/name.

{
	"name": "my-package",
	"scripts": {
		"lint": "eslint ."
	},
	"devDependencies": {
		"eslint": "^4.19.0"
	}
}

$ npm run lint

Lifecycle scripts

npm comes with predefined lifecyle scripts which are excuted under specific conditions when they are defined in your package.json.

{
  "name": "my-package",
  "scripts": {
    "prepublishOnly": "nsp check"
  },
  "devDependencies": {
    "nsp": "^3.2.1"
  }
}

This will be executed automatically before your npm package is published to the registry via npm publish to check for known vulnerabilties in your dependencies.

Note: prepublishOnly is available since npm v4.0.0. See npm docs.

»npm start« and »npm test«

These are also lifecycle scripts (but aren’t executed automatically).

{
  "name": "my-package",
  "scripts": {
    "start": "node server.js",
    "test": "jest"
  },
  "devDependencies": {
    "jest-cli": "^22.4.2"
  }
}

Therefore they can be executed simply with:

$ npm test
$ npm start

»pre« and »post« scripts

»pre« and »post« scripts are special lifecycle scripts which can be used to run scripts automatically in sequence.

{
  "name": "my-package",
  "scripts": {
    "pretest": "eslint .",
    "test": "jest"
  },
  "devDependencies": {
    "eslint": "^4.19.0",
    "jest-cli": "^22.4.2"
  }
}

$ npm test

This will lint your files before running your tests. The tests will not run if linting fails, or more generally: the following script won’t be executed if one of the scripts running in sequence exits with an exit code other than 0.

Note: »pre« and »post« scripts can also be used for your custom npm scripts. So npm run foo will also run prefoo and postfoo if defined.

Options for npm scripts

Passing options to used commands

You can pass options to the command you are using in your npm script by adding -- --flag like in the example below.

{
  "name": "my-package",
  "scripts": {
    "lint": "xo",
    "lint:fix": "npm run lint -- --fix",
  }
}

Adding the -- --fix option is like executing xo --fix.

Silent option

npm run has a --silent option which is especially useful when combining npm scripts in npm scripts.

Imagine you have a setup for linting your JavaScript files like the following:

{
  "name": "my-package",
  "scripts": {
    "lint": "xo",
    "lint:fix": "npm run lint --silent -- --fix",
  }
}

Using the –silent option reduces the output in the Terminal. See this comparison.

Helper packages

Watch tasks

There are several packages which enable running scripts when files changed. Personally, onchange offers the best combination of ease of use and flexibility.

{
	"name": "my-package",
	"scripts": {
		"lint": "eslint src",
    "lint:watch": "onchange \"src/**/*.js\" -- npm run lint --silent"
	}
}

So npm run lint:watch will watch for changes in the file system and will automatically run eslint when a file changes.

Get notified in error cases

cli-error-notifier sends native desktop notifications when npm scripts fail.

{
  "scripts": {
    "lint": "onerror \"eslint src\"",
  }
}

This is especially useful for watching files while developing in conjunction with onchange.

{
  "scripts": {
    "lint": "eslint src",
    "lint:fix": "npm run lint --silent -- --fix",
    "lint:watch": "onchange \"src/**/*.js\" -- onerror \"npm run lint --silent\""
  }
}

Run multiple scripts in parallel or serial

Using npm-run-all offers the following advantages:

can increase readability of the scripts section in your package.json via glob-like patterns
Before:

npm run clean && npm run build:css && npm run build:js && npm run build:html

After:

npm-run-all clean build:*

compared to using npm run foo & npm run bar
- running scripts in parallel works on Windows
- multiple scripts which are listening to file changes can run parallel

{
  "scripts": {
    "start": "npm-run-all clean --parallel webpack:server lint:watch",
    "build": "npm-run-all security test clean webpack",
  }
}

Remembering npm run scripts

Depending on the amount of tasks it might be hard to remember each and every task name. A faster alternative to use npm run to list all available tasks is to use an awesome little helper tool called ntl to show an interactive list of task to choose from 💥

Beyond npm scripts

Wrap your npm scripts setup to improve maintainibility and user experience

There are two things which might have a downside when your setup becomes more and more complex:

Not being able to describe your tasks to your users.
- You might want to upvote this issue on the npm issues tracker to fix this.
The lack of using comments in package.json.

As workaround for both you can use a tool like nps which claims to have »all the benefits of npm scripts without the cost of a bloated package.json and limits of json«.

The solution of nps

It allows you to move your scripts to a package-scripts.js file. Because this file is a JavaScript file, you can do a lot more with your project scripts.

const npsUtils = require('nps-utils') // not required, but handy!

module.exports = {
  scripts: {
    default: 'node index.js',
    lint: 'eslint .',
    test: {
      default: 'jest',
      watch: {
        script: 'jest --watch',
        description: 'run in the amazingly intelligent Jest watch mode'
      }
    },
    build: {
      default: 'webpack',
      prod: 'webpack -p',
    },
    // learn more about npsUtils here: https://npm.im/nps-utils
    validate: npsUtils.concurrent.nps('lint', 'test', 'build'),
  },
}

Using npx with locally installed dependencies instead of npm run scripts

npm comes bundled with npx (since v5.2.0) — a tool to execute package binaries which is great to use packages globally without the need to install them globally.

But it’s also pretty useful for locally installed dependencies in your project.

Each command called with npx is executed either from the local node_modules/.bin directory, or from a central cache, installing any packages needed in order to run a command.

{
	"name": "my-package",
	"scripts": {
		"lint": "xo"
	},
	"devDependencies": {
		"xo": "^0.20.0"
	}
}

npx xo --fix

This executes the locally installed version of XO from node_modules/.bin.

That’s it for now. Please share other features, tips and tools I might have missed.

JSConf Budapest 2017 – A personal recap

Tue, 14 Nov 2017 22:00:00 +0000

Picture by Kevin Lorenz

It was my first time attending JSConf Budapest. In this recap I’ll summarize and highlight a few talks and try to convey the overall experience. TL;DR: It was a blast. Thanks to everyone involved :sparkling_heart:

General remarks

JSConf Budapest is – besides JSConf EU (The first JSConf in europe) and JSConf Belgium – another JSConf happening at the european continent which actually took place for the third time and therefore already has a tradition to one’s name.

For those who don’t know the concept of the whole JSConf thing I’d like to proceed with a short explanation.

The JSConfs happening around the globe are all community driven by heart. From the local community for the world-wide community. So there isn’t something like a huge common organizer behind all that conferences. But they do have something in common: All local organizers are focusing on the community aspect instead of being only tech driven. This is achieved by offering many possibilities for social interactions from lounges through open discussion panels to interactive games during evening events. All of that considering a code of conduct which is not only written somewhere on the conferences website, but also will be lived and enforced.

Another important fact is that the organizers set a high value on diversity concerning the speakers as well as the attendees. They offer diversity support tickets for example. The additional charge is used to give members of underrepresented groups the possibility to attend the conference.

The 2017 edition was the first JSConf Budapest for me after visiting JSConf EU in Berlin a while ago. I was very thrilled about Budapest accordingly.

The location

Picture by Stefan Judis

The event location was a historic cinema in the heart of the jewish quarter in the center of the city. A monumental location. The only thing I kinda missed were more places to chill.

The schedule

It was a two day, single track conference. So there was no need to be afraid of choosing the wrong track and miss a talk :smirk:

The mixture of talks really was to my taste. The technical ones were predominating and there were very interesting talks which aren’t focused to technical details but enlightened human parts of our work life.

Personal highlights of the non-technical talks

I’d like summarize and highlight the following three talks.

Bodil Stokke – You Have Nothing to Lose but Your Chains

The topic of this talk was Open Source Software. From their beginnings, through licenses to todays relevance. Whether you interpret Open Source and the Free Software movement as socialism, pragmatism or art: The idea itself and spreading is as important as it ever was. Then it has the ability to empower us. Making source code available to the general public doesn’t only mean that we can take influence, can fix and can improve software. It builds communities of developers and user which weren’t imaginable. First and foremost it enables us to learn.

Picture by myself

Vaidehi Joshi – Goldilocks and the three Code Reviews

This talk illustrated problems we have with code reviews wrapped in an entertaining story. Including:

tons of comments, little conversation
focusing on style / syntax
ego over empathy

Plus it showed concrete opportunities for action to fix these problems:

review everyone: push for a culture that values vulnerability
develop empathy: call out the good stuff, too!
iterate: only iteration can improve the process
start the conversation

Picture by myself

Madeleine Neumann – Impostor syndrome - am I suffering enough to talk about it?

in this important psychological talk Madeleine told her personal story of career development in which the Impostor Syndrome acts a part. My main take away from the talk was that everyone has moments of suffering from self-doubts from time to time. Lastly Madeleine gave very useful tips about how to get out of the impostor zone. See slides.

Personal highlights of the technical talks

The following talks impressed me the most from the technical standpoint.

Stefan Judis – Watch your back, Browser! You’re being observed

A roundtrip across modern JavaScript web APIs which turns the way to gather information upside down. The concept of communications of older APIs mostly was based on a pull principle. Broadly speaking, you had to ask for information your are interested in. It seems that this has changed to an push principle with modern APIs.

Shortly explained using the example of the pretty new Intersection Observer API: This API offers the possibility to listen if a DOM node gets in the visible viewport and to asynchronously get notified in case this happens.

The most prominent use cases are probably lazy loading images and implement infinite scrolling as an alternative to a classical pagination. We were of course able to implement these things before, but less performant and elegantly.

Jonathan Martin – Async patterns to scale your multicore JavaScript … elegantly.

An excellent talk about patterns to grasp the challenges when it comes to handle concurrency with sequential dependencies via JavaScript. Since the JavaScript interpreter in the browser and in Node is a single thread classical multithreading approaches don’t fit in here. But JavaScript and the underlying architecture based on the event loop, the call stack and the callback queue is a perfect match for concurrent programming.

Jonathan came with recipes based on »Async IIFEs«, »Web Worker clusters« und »SharedArrayBuffers« to solve the concurrency challenges elegantly.

Picture by myself

Eirik Vullum – JavaScript Metaprogramming - ES6 Proxy Use and Abuse

An interesting talk providing real world use cases for one of the few non-polyfillable / non-transpilable ES6 features which you can use in in the latest browsers and Node.js versions.

A short explanation of proxies: JavaScript Proxies enables you to modify and extend fundamental language features (e.g. property lookup, assignment, enumeration, function invocation, etc).

Beside quite useful mini examples like auto-logging of object keys when accessing object properties I really was impressed by an Oprn Source project from Eirik: JSON-populate, which simplifies accessing JSON properties with circular dependencies by reference.

Parties :tada:

A very special highlight was the party after the first day of the conference. Mainly because {Live : JS} had a truly amazing live gig. They performed music running on two Gameboy Advance and did bedazzling live visuals exclusively based on web technologies. Mad props to Ruth, Tim, Sam und Martin. These folks truly rocked the party.

Bottom line

Beside the talks (and the party) I especially was delighted by the social aspects of this conference attendance. It was a pleasure to see friends who I only have the chance to meet them once a year (beside hanging out with them online), as well as meeting new people who I knew before from Twitter only.

Thanks to all the people for the nice conversations and your openness :sparkling_heart: Thanks to the folks for organizing JSConf Budapest :sparkling_heart: And thanks to my employer Micromata for making it possible to attend JSConf Budapest :sparkling_heart:

Quick Tip: Using Lodash per method packages with Angular (2 and above)

Mon, 12 Jun 2017 11:00:00 +0000

Problems with using Lodash per method packages

I didn’t get how to import per method packages and how to include the types in my project.

Therefore I encountered one or another of the following error Messages:

ERROR in /path/to/project/src/app/my.component.ts (3,10): Module '"/path/to/project/node_modules/@types/lodash/index"' has no exported member 'lodash'.

ERROR in /path/to/project/src/app/my.component.ts (3,22): Module '"/path/to/project/node_modules/@types/lodash.drop/index"' resolves to a non-module entity and cannot be imported using this construct.

ERROR in /path/to/project/src/app/my.component.ts (71,24): Cannot find name 'dropRight'.

ERROR in Cannot read property 'getLineAndCharacterOfPosition' of undefined

It’ actually pretty much straight forward to fix these errors like described below.

Installing Lodash per method packages

In addition to the Lodash packages you have to install the type definitions:

npm install --save lodash.drop
npm install --save @types/lodash.drop

npm install --save lodash.dropright
npm install --save @types/lodash.dropright

Add type definitions to your project

Add just the one and only item to the types array in src/tsconfig.app.json:

{
  "compilerOptions": {
    "types": [
      "lodash"
    ]
  }
}

Note: No need to add each and every installed lodash method in here.

Import methods where you need them

Just act like you have installed the whole Lodash package:

import { drop, dropRight } from 'lodash';

// […]
visiblePages = dropRight(totalPages, PagesAboveVisible);

Looks easy, but I invested some time to get this straight. Hope this little tip can save you half an hour. :blush:

Cheat Sheet: Docker CLI

Sat, 19 Nov 2016 16:45:00 +0000

I’m new to Docker. So this cheatsheet is primarily for me to help to remember commands for handling containers as well as images.

See Docker command line reference for the whole reference.

Containers

Listing containers


# List running containers 
docker ps

# List all containers
docker ps -a

Starting/Stopping containers

# Start 
docker start containerName

# Stop
docker stop containerName

Removing containers

# Remove container 
docker rm containerName

# Stop and remove container
docker rm -f containerName

# Remove all exited containers
docker rm -v $(docker ps -a -q -f status=exited)

Running commands in new containers

docker run imageName command arguments

# Example
docker run docker/whalesay cowsay Hello

# Assign a name to the container
docker run --name myName docker/whalesay cowsay Hello

# Run with a specific tag of an image
docker run node:6.9.1 node --version

# Run container in background
docker run -d -p 80:80 --name webserver nginx

See Docker run reference for more …

Images

Listing local images

docker images

Removing images

docker rmi imageName

# Remove unwanted dangling images
docker rmi $(docker images -f "dangling=true" -q)

Searching for images

# Search the Docker Hub for images
docker search searchWord

Pulling images

docker pull imageName

# Pull a specific tag
docker pull imageName:tag

# Example: Get a specific node version
docker pull node:6.9.1

Building image from Dockerfile

docker build .

# Name the image
docker build -t imageName .

# Tag the image
docker build -t imageName:1.0.0 .

See Dockerfile reference in addition.

Data mocking – Ways to fake a backend (API)

Fri, 04 Nov 2016 00:10:00 +0000

Eine deutsche Version des Artikels findet ihr im Micromata Blog.

Today we mostly have a loose coupling between the frontend and the backend of our web applications. It might be even useful to handle the separate parts as separate projects. Think about the backend as the provider of an RESTful API which has a totally different (hopefully semantic) versioning than the frontend. This offers much more flexibility by being able to deploy only the frontend to production or by using the same backend for a different frontend with a totally different tech stack (eg. native apps).

So in development we have different people working on the frontend and on the backend. The backend team needs to make sure the content the API is providing is sane, whereas the frontend doesn’t care about the content: it just needs dummy data in the correct structure. So these teams only have to talk about and agree on JSON structures before they can work independently on their part.

The main advantage working with dummy data over here is the independence in which the frontend team can work. It doesn’t matter if the development of the backend gets stuck for whatever reason.

Which leads us to the question: How could we simply mock the backend?

Different ways to fake a backend

There are a few possibilities to »serve« dummy data depending on your needs, your tech stack and the requirements of your project:

Static JSON files via Ajax
Online mocking services
»JSON Server«
An own server

We are going to explore the details as well as the pros and cons of each and every possibility.

Loading JSON files via Ajax

The simplest approach without any tooling involved. Just create your dummy data and store it within the file system of your frontend project.

Pros

Straightforward
The dummy data is in your version control system (eg. Git)

Having those files in your file system has the big advantage, that the dummy data have a single source of truth. This is important for working in the team, especially for the coordination between the frontend and the backend team.

Cons

Very limited functionality
Might not be supported by your JavaScript Framework™
No usage of HTTP method besides GET possible
Can’t test handling errors (besides 404)
Differences between the fake and the real backend

This might work out for a web app or website which just loads a little data via Ajax. But other than that the downsides will outweigh the simplicity in most cases. The biggest disadvantages are the differences between your fake backend and the real backend in production. This goes from different URLs (including a whole different structure) to different HTTP headers.

Online mocking services

There are dedicated services like mockapi.io, mocky.io and jsonstub.com which offer good solutions to help you effortlessly mock your HTTP responses.

Pros

Easy to use
Good and in some cases powerful configuration possibilities

This is almost as easy as storing JSON files in your project. Plus it offers more possibilities to configure things like HTTP status codes and verbs.

Cons

CORS limitations (if applicable)
Your own data stored on public servers you don’t own
Dependent on vendor
Data isn’t in your version control system

The dependency factor is important because it may lead to unforeseeable problems. There is a whole spectrum of uncertainties, mostly related to availability. You should ask yourself at least the following questions: Can I continue working when the service has downtimes? What happens if the service discontinues working? Will it offer any kind of export?

Not having the dummy data under version control is also a major drawback if you are not working alone. Of course you could store the data redundantly in your file system; but that would lead to a maintainability overhead and might cause confusion because no one is sure whether the files in version control are really and exactly mirroring the data served by the mocking service.

»JSON Server«

JSON Server is a nifty command line tool and super easy to use even for people who don’t spend most of the day at their terminals.

Get a full fake REST API with zero coding in less than 30 seconds (seriously)

It boils down to letting you serve JSON from your file system via a local server.

Pros

The dummy data is in your version control system
The simplest setup you can imagine
It supports the most used http verbs
It saves changes to your JSON source for POST, PUT, PATCH or DELETE requests.

This sounds like heaven. You can store your fake data in JSON in your project and have an external tool to provide the data.

But there are also a few cons, one or the other of which might be a dealbreaker depending on your project requirements.

Cons

The payload requires a strict format (JSON)
No routes with self-defined dynamic parts
- ~~api/articles/{offset}/{count}~~
Maintainability of one single JSON file for your responses

It’s easy to use, however this means some of its conventions could get in your way.

The payload restriction will be no problem if you have full control over the real backend as well. But you will have a problem when your real backend only accepts an integer as payload, to delete a data set for example.

JSON server provides URL parameters for things like pagination. But this is bound to a fixed URL concept you have to adapt. Otherwise you end up having a huge list of URL mappings in a file called routes.json. Having this option is advantageous but it may still lack flexibility depending on your needs.

The last possible downside is that putting all your dummy data in one JSON file may not scale well.

Own server

Writing an own server just to provide your mocked data sounds like a perfect example of overengineering. The question is: Would you – as a frontend developer – maintain something like a »second« backend? Because the main reason to mock your data is to be independent of the backend.

The answer is yes, if you can have a reasonable compromise between flexibility and complexity.

http-fake-backend offers such compromise. It comes as a Node.js server which serves your dummy data via HTTP. And it’s almost as easy to set up as »JSON server«. It basically lets you build a fake backend by providing the content of JSON files or JavaScript objects through configurable routes.

Each endpoint needs a configuration file to define routes, HTTP method and the response.

Simple example

Let’s say you need an endpoint like http://localhost:8081/api/simpleExample which should return:

{
  "status": "ok"
}

All you have to do is create a configuration in a JavaScript file like:

module.exports = SetupEndpoint({
    name: 'simpleExample',
    urls: [{
        requests: [{
          response: {status: 'ok'}
        }]
    }]
});

Advanced example

But it’s way more flexible than responding JSON defined through a JavaScript object via HTTP GET.

Let’s look at a more complex example configuration like the following:

module.exports = SetupEndpoint({
    name: 'anotherExample',
    urls: [{
        params: '/read',
        requests: [{
            method: 'GET',
            response: '/json-templates/anotherExample.json'
        }]
    }, {
        params: '/update/{id}',
        requests: [{
            method: ['PUT', 'PATCH'],
            response: {
                success: true
            }
        }, {
            method: 'DELETE',
            response: {
                deleted: true
            }
        }]
    }]
});

So you can have multiple urls with different HTTP verbs for any endpoint and you can define your Response via JSON files.

You can also fake HTTP errors and status codes for an entire endpoint or on request level like in the following example:

module.exports = SetupEndpoint({
    name: 'statusCodes',
    urls: [
        {
            params: '/boomError',
            requests: [{
                // Returns a 402 status code + error message provided by boom:
                // {
                //   "error" : "Payment Required",
                //   "statusCode" : 402
                // }
                statusCode: 402
            }]
        },
        {
            params: '/customError',
            requests: [{
                // Returns a HTTP status code 406 and a self defined response:
                response: { error: true },
                statusCode: 406
            }]
        },
        {
            params: '/regularResponse',
            requests: [{
                // Returns a 401 error provided by boom
                // as defined on endpoint level
                response: '/json-templates/anotherExample.json'
            }]
        }
    ],
    statusCode: 401
});

The configuration object described in detail:

name
- Is used to set the endpoint.
urls
- You need to add at least one url object.
urls.params
- Optional
- In this example a valid URL might be: http://localhost:8081/api/articles/foo/bar/baz whereas: http://localhost:8081/api/articles will return a 404 error.
- See hapi docs. For example regarding optional path parameters.
urls.requests
- You need to add at least one request object.
urls.requests.method
- optional. Uses GET when not defined.
- string, or array of strings.
- is used to define the http method(s) to which the endpoint will listen.
urls.requests.response
- Could be a string pointing to a JSON template:
  - response: '/json-templates/articles.json'
- Or just a JavaScript object:
  - response: { success: true }
urls.requests.statusCode
- Optional
- A status code (number)
- Will return:
  - a status code with a self defined response if you provide a response property
  - a status code with a predefined error object provided by boom if you dont provide a response property for that request.
statusCode
- Optional
- Every route of this endpoint will return a HTTP error with the given status code provided by boom.

People who think that this looks daunting can create a config like this easily and interactively with the help of this Yeoman generator which comes with a subgenerator which guides through the configuration:

It offers even more flexibility

Just when you need it: You can build own endpoints with custom configs since the server underneath is just a simple http server built with hapi.

Pros

The dummy data is in your version control system
The highest flexibility
Easy setup of
- Endpoints
- URLs including dynamic parts
- allowed HTTP methods
- errors (supporting all HTTP status codes)
Yeoman generator
- with a subgenerator to assist with building the API

It also optionally restarts the server when JSON or config files are changed. Just like JSON server.

Cons

Slightly more complex setup compared to JSON server
Less intelligent than JSON server
- No persisting of payload data for POST, PUT and PATCH requests
- No automatic and real relation between data of different endpoints
  - Example:
    - You have to define own and independent data for a route which returns a list /api/products and a route which returns a single item /api/products/{id}

Workflow integration

Starting the server is as easy as firing npm run start:dev during development or npm start in a Continuous Integration environment. No matter if you are using npm run scripts or a workflow based on a taskrunner to build your frontend.

Getting started

Just visit the projects Github page and you will have your fake backend running in a couple of minutes. You are even faster when using the Yeoman Generator.

Helpers for generating your dummy data

Developers aren’t lazy per se. But we all like to dispense with stupid and repetitive work. So we could need some help generating the content for our fake backend. This is where the following tools might come in handy.

JSON generators

The following tools could help you to generate JSON files for fake backend:

Dummy data generators

Feel free to use one of these excellent node modules if you prefer to build the responses of your fake backend programmatically:

Switch Node.js versions with the Node Version Manager (nvm)

Tue, 08 Sep 2015 23:00:00 +0000

Update from June 2, 2016

Update versions numbers in examples
Add info about getting version infos
Add note about potential problems with linking global packages
Complete info about handling of globally installed packages

Sure you can just use homebrew to update your Node.js installation when there are new releases. It’s in fact very handy to do so. But beside the quirk when it comes to updating npm there is a method which makes switching Node.js version even easier. This became more important since the stable release of Node 4.0 which I like to use. But I have to be able to use a different Node version just in case thinks break with Node 4.0.

Uninstall node via homebrew

First we could check which version of node we are using:

$ node -v
v5.5.0

Let’s get rid of this and older versions in the cellar of homebrew:

$ brew uninstall --force node
Uninstalling node...

Potential problems with linking global packages

Double check if there still is a node_modules directory in /usr/local/lib holding your globally installed packages. Do yourself a favor and remove that to prevent possible issues with linking globale packages via npm link.

Installing the Node Version Manager (nvm)

I prefer installing it via homebrew:

$ brew update
$ brew install nvm

Please have a look at https://github.com/creationix/nvm in case you would like to do a manual install.

Either way you have to add a few lines to your ~/.bash_profile, ~/.zshrc or ~/.profile. In case of the homebrew installation it is:

export NVM_DIR=~/.nvm
source $(brew --prefix nvm)/nvm.sh

Using nvm

To download, compile, and install the (currently) latest v6.x.x release of node, do this:

nvm install 6

Let’s install the latest v5.x.x release in addition:

nvm install 5

You will use the latest installed version automatically after installation. Switching version is easy as:

nvm use 6

In place of a version pointer like “6”, you can use the special default aliases like “stable” and “unstable”:

nvm install stable
nvm install unstable
nvm use stable

Globally installed packages

Please note that you have to install global packages with every node version your are using with nvm.

Another day, another Node.js release”

This is something you want to automate since releases of Node.js are pretty frequent (for a good reason). Thankfully nvm offers to ways to accomplish that.

Reinstall during install

The easiest one is to take care of that after during installation of a new node version with:

nvm install node --reinstall-packages-from=node

This will install the latest release and reinstall the globally installed packages from the predecessor.

You also can use more explicit versions like this:

nvm install 6.2 --reinstall-packages-from=6.0

Reinstall later

You can »transfer« your global packages from one version to another at any given time. Just use:

nvm reinstall-packages <version>

This will reinstall global packages contained in <version> to the current version in use.

Setting a default version

You need to set a default version if you dont want to be surprised by switched versions with every opened Terminal window/tab. There are the two following ways to accomplish this.

Via config file

You can place a .nvmrc file in your home directory to define your prefered version globally. For example:

This can be overidden by placing other .nvmrc files in your project root directories.

Via nvm alias

Alternatively you can add an alias with nvm alias <name> <version> :

$ nvm alias default 5
default -> 5 (-> v5.11.1)

Enter nvm --help to see how to handle aliases.

So many versions :flushed:

After a few releases it might come in handy to check which versions are installed and which you are currently using.

Just enter the following to see which versions are installed:

$ nvm ls

This will also highlight the version currently in use.

You could also fire nvm current to see what version your are using.

Showing the current version in your prompt

There are zsh themes like Bullet Train which offer to make the version visible with every prompt.

Pretty nifty, huh?

I guess that’s all you need to know to start using nvm. Make sure to checked out the project on Github in case you like to dig deeper.

Quick Tip: Updating your node modules is easy as »1, 2, 3«

Tue, 20 Jan 2015 14:00:00 +0000

It might be a »no-brainer« in case you are working within the Node.js environment for a while. But I used to ask myself how to figure out if there are updates to my dependencies / devDependencies which are beyond the patch-level updates which are »automatically« installed via the definition within my `package.json`. Because I don’t like to check possible updates separately for every module I’m using in my project.

Fortunately there is a node module which can handle that for all dependencies within your project and even all your globale modules. It’s called npm-check-updates and will also update your package.json file if you like to. So updating becomes »fun« again :smile:

Using this is pretty straight forward. First you need to install the package globally with:

npm install -g npm-check-updates

Then use the modules cli without any option to check available updates within your projects root directory:

npm-check-updates

This will show you all possible updates without changing anything:

"superb" can be updated from ^1.0.5 to ^1.1.1 (Installed: 1.0.5, Latest: 1.1.1)
"mocha" can be updated from ^2.0.1 to ^2.1.0 (Installed: 2.0.1, Latest: 2.1.0)
"should" can be updated from ^4.4.2 to ^4.6.1 (Installed: 4.4.2, Latest: 4.6.1)

Run 'npm-check-updates -u' to upgrade your package.json automatically

If you like to upgrade your projects package.json file just make use of the -u option as mentioned in the output above and fire:

npm install

afterwards. And :boom: … all updates will land on your machine and you’re done.

See the README for more options.

Quick Tip: Update your Git client on Mac OS X

Fri, 19 Dec 2014 12:00:00 +0000

I like to assist you just in case you wonder how to react on yesterdays announcement of that critical Git security vulnerability. As said within this post on Githubs Blog it’s strongly recommended to update your Git clients as soon as possible. Here we go with a short instruction how to update in case you are using OS X.

1. If you’re already using Homebrew

`brew update && brew upgrade git` or `brew update && brew install git`

Entering git --version should echo → git version 2.14.1 afterwards.

In case it’s saying something like Git 1.9.x (Apple) instead you have to add export PATH=/usr/local/bin:$PATH to your environment variables via .bashrc or however you handle that. See my dotfiles.

After restarting your terminal git --version should print → git version 2.14.1.

And you’re safe using Git via the command line.

2. If you don’t use Homebrew

Get Homebrew and start reading at »1. If your already using Homebrew«.

Update your Git Gui

In case you’re a using a Git client like Tower oder SourceTree you have to tell those apps which Git version they should use. You can set this via the Applications Preferences hitting ⌘ + , on your Keyboard.

That’s it. Happy coding and merry christmas :christmas_tree: