DEV Community: Lea Rosema (she/her)

Eleventy in eleven minutes

Lea Rosema (she/her) — Fri, 05 Feb 2021 09:34:27 +0000

I would like to share my opinionated path how I got started using.

What is Eleventy?
Why Eleventy?
Create a new project
Adding content
Running and building
HTML templates
Providing data for your site
Collections
Filters
Plugins
Adding toolchains for CSS and JS

What is Eleventy?

Eleventy is a popular static site generator. It creates a static site from your input files. The input files eleventy looks for are content files, html template files and data files which will be covered in this article.

It supports several data file formats, content file formats and html template engines which you can use together. In this article, I'm using Markdown files together with Nunjucks templates.

Why Eleventy?

There are many static site generators out there and you may wonder what benefits it offers compared to others. The key points which make me really love Eleventy are:

it is built on node.js
it does one job and does that well: create markup from content plus templates
it is completely unopinionated about client-side JS+CSS toolchains: bring your own
no angular/react/vue knowledge necessary.
html first approach which makes it great for progressive enhancement.
easily extendible and combinable with npm packages
similar to jekyll, but with node.js as a base
easy to mock data via the data folder.

Create a new project

mkdir my-awesome-site
cd my-awesome-site
git config --global init.defaultBranch main
npm init -y
npm i @11ty/eleventy -D

Initialize your repository

Additionally, run git init and provide a .gitignore if you are working with git:

node_modules
.DS_Store
Thumbs.db

# Eleventy output folder
public

Configuration

Configuration is done via a single javascript file named .eleventy.js. Providing a configuration is optional.

My personal preference is to provide src as input folder and public as output folder. Additionally, I use to specify folders that are copied over to the output folder on build. These are also automatically watched by eleventy when starting the development server.

module.exports = (config) => {
  // specify folders to be copied to the output folder
  config.addPassthroughCopy('./src/js/');
  config.addPassthroughCopy('./src/css/');

  return {
    markdownTemplateEngine: 'njk',
    htmlTemplateEngine: 'njk',
    dir: {
      input: 'src',    // default: '.'
      output: 'public' // default: '_site'
    }
  }
};

Adding content

Create a markdown file and name it like this: src/index.md

---
title: "Hello world"
---
# Hello World

Welcome to my awesome {{title}} site!

Markdown and front matter

Markdown files can optionally provide a metadata block, which is marked via three hyphens --- in the beginning and the end of the block. In this block, you can specify meta data in YAML notation.

From content to paths

For each markdown content file, eleventy creates a folder with an index.html for nice urls:

index.md            --> /
about.md            --> /about/
faq.md              --> /faq/
blog/hello-world.md --> /blog/hello-world/

Running and building

Finally, we can start adding the start and build tasks to our package.json file:

{
  "scripts": {
    "start": "eleventy --serve",
    "build": "eleventy"
  }
}

npm start -> start Development server
npm run build -> build your website
npx serve public -> test your build

The development server is using browsersync which automatically keeps track of changes and updates your DOM. Additionally, if you open the page in multiple browsers, events are kept in sync, which is useful for cross-browser-testing.

HTML templates

To define your HTML structure and layouts, you can use HTML templates. There are several template engines available in Eleventy. In this example, I'm using the Nunjucks template engine.

Other template formats supported are .html, .liquid, .hbs, .ejs, .haml, .pug.

A general approach is to build a base html file and then build
several other structures as you need based upon it.

Add a src/_includes/base.njk file

<!DOCTYPE html>
<html lang="en">
  <head><title>{{ title }}</title></head>
  <body>
    <main>
      {% block main %}
        {{ content | safe }}
      {% endblock %}
    </main>
  </body>
</html>

Via the {% block %}{% endblock %} syntax, you can add several slots into your template which you can use when extending your template.

The content variable is a reserved variable which contains the content body of the current content file.

The | safe directive is a builtin filter which tells the template engine that the content you want to insert is safe. This way, HTML tags are not converted to plain text containing HTML entities. This allows using html inside your content.

Using your templates in your content files

In the front matter of your markdown file, specify the layout you want to use:

layout: base

Extending your templates

Next to your base.njk file, create an article.njk file:

{% extends "base.njk" %}

{% block main %}
  <article class="article">
    {{ content | safe }}
  </article>
{% endblock %}

Nunjucks also has a section about inheritance in the documentation: https://mozilla.github.io/nunjucks/templating.html#template-inheritance

Includes

You can include partial layouts anywhere in your njk or markdown files:

{% include "header.njk" %}

Providing data for your site

There are several ways to provide data that can be used from inside your templates or content files:

file specific: in the markdown's front matter
folder specific: add a json file to a content folder
globally _data directory: globally available
_data supports .js, .yaml, .json files

`_data` example

Imagine you would like to build a navigation and provide all the url entries from a JSON file:

src/_data/nav.json

[
  {"title": "Home", "url": "/"},
  {"title": "Blog", "url": "/blog/"}
]

Then, you can create a partial html snippet to include in your main template, eg. src/_includes/nav.njk

<nav>
  <ul>
    {% for link in nav %}
      <li>
        <a href="{{ link.url }}">{{ link.title }}</a>
      </li>
    {% endfor %}
  </ul>
</nav>

`_data` javascript example

_data/site.js

module.exports = {
  name: 'My awesome site',
  url: 'https://awesome.site/'
};

Can be used like this in the content:
{{ site.name }}

Having a .js file instead of a plain json or yaml file brings the flexibility to use node.js environment variables (like, checking if you're in the development or production environment). Also, you can do API fetches from there to pull in a headless CMS, for example.

Collections

You can tag your content with a keyword and then iterate through these via collections.

This is useful for auto-generating table of contents or listing articles that are related to each other

Collections example

In your src folder, add a blog folder with a bunch of markdown files. Tag them as posts in your front matter:

tags: posts

Then, in your markdown or include files, you can iterate through these collection via a for loop:

index.md:

# Blog

<ul>{% for post in collections.posts %}<li>
  <a href="{{ post.url }}">
    {{ post.date | date('YYYY-MM-DD') }}: {{ post.data.title }}
  </a>
</li>{% endfor %}</ul>

Filters

Filters provide a way to further process your content. You can use these filters from inside your content and template files by using the pipe.

Adding a custom filter

In your .eleventy.js file, you can add several filters you can use inside your file. You can also use third party libraries here. This is an example for a scream filter and a date formatting filter:

const moment = require('moment');

module.exports = (config) => {
  config.addFilter('date', (date, format) => moment(date).format(format || 'YYYY-MM-DD'));
  config.addFilter('scream', (str) => str.toUpperCase());
  // ...additional config 
  return { ... }
};

Then, you can use this filter in your content and template files like this:

{{ content | scream | safe }}`
{{ page.date | date('YYYY-MM-DD') }}

Processing include files with a filter

If you would like to process an include with a filter, you can use the nunjucks set directive to store includes into a variable. In my personal site, I've used this technique to minify WebGL shader code on the fly:

{% set vertexShader %}
{% include 'shaders/vertex-shader.vs' %}
{% endset %}

{{ vertexShader | glslminify | safe }}

Built-in filters

you can use all built-in nunjucks filters
safe – the content is safe to insert, so html specific characters are not converted to html entities (use this to inject html and scripts).
url – specify a prefix path (useful for deployment into a subdirectory, eg. on github pages).
slug – convert a string to an url-friendly slug (eg My site to my-site)
get*CollectionItem – get next or previous item in collection

Plugins and tools

Eleventy provides a rich plugin ecosystem where you can add further magic✨ to your workflow 🙌.

Check out the Eleventy plugins documentation

Adding toolchains for CSS and JS

In the article, we used a pass-through-copy command and used CSS and JS without any bundling or further processing. My favorite approach is to use a CSS preprocessor plus ES module JavaScript files. These are not supported in legacy browsers such as IE11. When using progressive enhancement, JavaScript is not required to read
your content.

In the following, I will demonstrate the approach I used (only using a CSS transpiles) and a complete JS+CSS toolchain using parcel as an alternative approach.

CSS transpiler only

In my personal project, I used the sass together with concurrently, to start two processes concurrently running in my npm start script.

npm i sass concurrently -D

To build the CSS, I'm running sass src/scss:src/css which compiles every .scss to CSS:

{
  "scripts": {
    "start": "concurrently 'npm:watch-css' 'npm:serve-11ty'",  
    "build-11ty": "eleventy",
    "serve-11ty": "eleventy --serve",
    "build-css": "sass src/scss/:src/css/",
    "watch-css": "sass src/scss/:src/css/ --watch",
    "build": "npm run build-css -s && npm run build-11ty -s"
  }
}

Or complete Javascript+CSS toolchain.

If you would like to have a complete frontend toolchain taking care of compiling JavaScript and CSS, one way to do is is to use Parcel.

npm i parcel-bundler concurrently -D
echo src/dist >> .gitignore
echo .cache >> .gitignore

For the development mode, I'm also using concurrently to start eleventy and parcel in parallel:

{
  "scripts": {
    "start": "concurrently 'npm:watch-bundle' 'npm:serve-11ty'",
    "build": "npm run build-bundle -s && npm run build-11ty -s",
    "watch-bundle": "parcel watch src/app/index.js -d src/dist",
    "build-bundle": "parcel build src/app/index.js -d src/dist",
    "serve-11ty": "eleventy --serve",
    "build-11ty": "eleventy"
  }
}

In src/app, put an index.js file. Additionally, put any CSS import of your choice into it:

import './scss/styles.scss';

console.log('Hello world');

Finally, in your eleventy config, change the pass through copy to copy the parcel output into your eleventy output folder:

config.addPassthroughCopy('./src/dist/');

Then, parcel creates an index.js and index.css in the dist folder, which you can use in your html templates like this:

<!-- in your head tag --> 
<link rel="stylesheet" href="/dist/index.css">

<!-- right before your closing </body> tag -->
<script src="/dist/index.js"></script>

Example project

https://github.com/terabaud/lea-codes/

Resources

https://terabaud.github.io/eleventy-talk/ - My slides for a talk about 11ty (useful as a summary of this article)
https://11ty.dev/ - Official site
https://11ty.rocks/ - Eleventy rocks
https://piccalil.li/course/learn-eleventy-from-scratch - in-depth course

Thank you 👩‍💻

Proxy your Backend API to the Parcel Development Server

Lea Rosema (she/her) — Fri, 09 Oct 2020 09:00:38 +0000

When working with Parcel, I missed the option to proxy the backend API to the frontend development server.

Parcel runs on localhost:1234 and my API backend server runs on localhost:1337. I would like to have both the API server as well as the frontend server on the same site, this way you don't have to deal with CORS and you can use secure settings for cookies, like SameSite=Strict.

In a production environment, you would setup some kind of reverse proxy for that. This could be achieved with NGINX, for example.

In your development environment, you will still like to have the features of Parcel, like Hot Module Reloading.

I've built a node.js express script using the parcel-bundler as an express middleware, together with http-proxy-middleware:

const proxy = require('http-proxy-middleware').createProxyMiddleware;
const Bundler = require('parcel-bundler');
const express = require('express');

const bundler = new Bundler('src/index.html');
const app = express();

app.use(
  '/api',
  proxy({
    target: process.env.API_SERVER || 'http://localhost:1337/'
  })
);

app.use(bundler.middleware());

app.listen(Number(process.env.PORT || 1234));

In package.json, I replaced the start script that used the parcel script with node server.

As a demo project, I have created a clone of https://yesno.wtf
It provides a node.js express backend and a react application.

https://github.com/terabaud/yesno-clone

Do you have questions or feedback? Feel free to leave a comment.

Realtime video processing with WebGL

Lea Rosema (she/her) — Sat, 20 Jun 2020 13:54:11 +0000

This is a making-of of a WebGL demo I made recently on CodePen. It grabs the data of a webcam (or a fallback image from placekitten when no access to the webcam is available), and turns it into ASCII art in real time.

For some extra RETROness, I'm using a 8x8 pixel rasterfont that was common in DOS PCs from the 90s (you may still see this kind of font in some BIOSes).

To map the image content to a specific character, I chose the best match by using a luminance map. I counted pixels in each 4x4 square. Scroll down inside the pen to see the luminance map:

I've also created an editor for these kinds of fonts: https://terabaud.github.io/pixelfedit/

Some WebGL Basics

I'm going to introduce some basics of WebGL, but I'm only scratching the surface here. For a more in-depth guide, I recommend you to head to https://webglfundamentals.org

A common misunderstanding about WebGL is that it is a 3D engine in the browser. Although WebGL is the technology that enables us to provide GPU accelerated 3D content in the browser, WebGL itself is not a 3D engine. On top of WebGL, there are graphics libraries for GPU-accelerated 2D or 3D content (like Pixi for 2D, ThreeJS for 3D).

WebGL itself is quite low level and a library to draw points, lines and triangles in a GPU accelerated way onto a html <canvas> element.

The WebGL rendering context can be retrieved via getContext (similar to the 2D canvas API):

const canvas = document.querySelector('canvas');
const gl = canvas.getContext('webgl') || canvas.getContext('experimental-webgl');

A webgl program is consists of shaders. Shaders are pieces of code that are run on the GPU. These are not written in JavaScript but have its own language, called GLSL (GL shader language).

Quick GLSL facts

C-like, shader programs have a void main(),
variable declaration also like in C
Primitive data types: int, float, double
Vectors: vec2, vec3, vec4, ...
Matrices: mat2, mat3, mat4, ...
Type for accessing texture data: sampler2D
built-in vector/matrix arithmetics
many built-in functions, eg. to get a length of a vector (length(v))

Types of shaders

There are two types of shaders in a WebGL program.

The vertex shader computes positions.
The fragment Shader handles rasterization.

If your webgl program wants to draw a triangle on screen, it passes 3 coordinates of a triangle to a vertex shader. Then, the task of the fragment shader is to fill that triangle with pixels. This per-pixel processing is super fast, because it is run in parallel for each pixel on the GPU.

Im my demo, I'm using 4 vector coordinates to span up a rectangle that fits the whole screen. All the work is done in the fragment shader.

Vertex shader

So, the vertex shader is there for the vertexes. It get's a bunch of data from a buffer provided in the JavaScript code and computes this data to a position in the canvas.

The following piece of code pulls data from a buffer into an attribute variable and passes it to the gl_Position variable:

attribute vec3 position;

void main() {
  gl_Position = vec4(position, 1.0);
}

Fragment shader

precision highp float;

void main() {
  vec2 p = gl_FragCoord.xy;
  gl_FragColor = vec4(
1.0, .5 + .5 * sin(p.y), .5 + .5 * sin(p.x), 1.0);
}

The fragment shader is run for each fragment (pixel) in parallel. In the example above, the fragment shader reads the current pixel coordinate from the gl_FragCoord variable and sets and output color via gl_FragColor with some sin() magic.

gl_FragColor is a vec4 vector containing (red, green, blue, alpha) with values from 0 .. 1 each.

Types of GLSL variables

attribute: the vertex shader pulls a value from a buffer and stores it in an attribute variable
uniform: uniform variables are set from the JS side. For example, you can use uniforms to pass something like your current mouse/tap position to your shader. You can also use uniform variables to access texture data uploaded from JavaScript.
varying: pass values from the vertex to the fragment shader and interpolate values.

Uploading image data to your WebGLRenderingContext

You can access image data to your WebGLRenderingContext inside your shader and upload them into textures. (See Also: WebGL Fundamentals: Image Processing)

You can use the texImage2D method inside the WebGLRenderingContext to upload image data into a texture.

// gl is the WebGLRenderingContext 
const texture = gl.createTexture()
gl.activeTexture(gl.TEXTURE0 + textureIndex);
gl.bindTexture(gl.TEXTURE_2D, texture);
gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, img);

// more info about these parameters in the webglfundamentals
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);

The image data you pass to texImage2D can be an img element, a video element, ImageData, and more.

Because the image data of the video constantly changes, you will have to update the texture inside the requestAnimationFrame animation loop. This is done via texSubImage2D.

gl.texSubImage2D(gl.TEXTURE_2D, 0, 0, 0, gl.RGBA, gl.UNSIGNED_BYTE, video);

Reading texture data inside your shader code

You can access pixel data of the texture via the texture2D glsl function.

Texture coordinates go from (0, 0) to (1, 1). The image is upside down. Also I'm mirroring the image horizontally (like a selfie cam does).

uniform sampler2D texture0;

void main() {
  vec2 coord = 1.0 - gl_FragCoord.xy / vec2(width, height);
  gl_FragColor = texture2D(texture1, coord);
}

Accessing the Webcam

To get image data from the webcam, we can use a video tag and
use the getUserMedia API:

function accessWebcam(video) {
  return new Promise((resolve, reject) => {
    const mediaConstraints = { audio: false, video: { 
        width: 1280, 
        height: 720,
        brightness: {ideal: 2} 
      }
    };

    navigator.mediaDevices.getUserMedia(
      mediaConstraints).then(mediaStream => {
        video.srcObject = mediaStream;
        video.setAttribute('playsinline', true);
        video.onloadedmetadata = (e) => {
          video.play();
          resolve(video);
        }
      }).catch(err => {
        reject(err);
      });
    }
  );
}

// USAGE:
// const video = await accessWebcam(document.querySelector('video'));
// or via promises:
// accessWebcam(document.querySelector('video')).then(video => { ... });

To access the webcam, you can use the getUserMedia API to access the webcam like above.

Provide a Fallback Image

If the access to the webcam is blocked by the user, or no webcam is available, you can provide a fallback image to be used instead.

I also wrapped new Image() and its onload event into a promise.

function loadImage(url) {
  return new Promise((resolve, reject) => {
    const img = new Image();
    img.crossOrigin = 'Anonymous';
    img.src = url;
    img.onload = () => {
      resolve(img);
    };
    img.onerror = () => {
      reject(img);
    };
  });
}

Putting it all together

To make things a little easier, I've put commonly used WebGL functions into a tiny helper library I made: GLea.

It initializes the WebGL context, compiles the WebGL shader code and creates attributes and buffers for the vertex shader:

By default, a position attribute is provided for the vertex shader with a buffer containing 4 2D coordinates, spanning up a strip of 2 triangles filling the whole screen.

import GLea from 'glea.js';

const frag = ` ... `; // fragment shader code
const vert = ` ... `; // vertex shader code
const glea = new GLea({
  shaders: [
    GLea.fragmentShader(frag),
    GLea.vertexShader(vert)
  ]
}).create();

function loop(time = 0) {
  const { gl, width, height } = glea;
  glea.clear();
  glea.uniV('resolution', [width, height]);
  glea.uni('time', time * 1e-3);
  gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
  requestAnimationFrame(loop);
}

window.addEventListener('resize', () => {
  glea.resize();
});
loop(0);

Conclusion

That's basically it. I hope you enjoyed reading the article and get curious about exploring WebGL yourself. I'll put some resources in here.

If I haven't covered something, please feel free to comment =).

Resources

I created my first TypeScript library and published it on NPM

Lea Rosema (she/her) — Mon, 15 Jun 2020 15:02:40 +0000

Recently, I've published my very first library as an NPM module and I'd like to share my learnings and struggles with you.

The module I'm talking about is ella-math, which is a library for vector and matrix calculations.

These are useful for transformations in graphics programming, like scaling, moving and rotating shapes, or projecting things into 3d space.

Why?

To be honest, there really is no need to build my own vector/matrix calculation library. There are many of these already out there. But I wanted to do it anyway, just in order to learn how all this works.

Getting started

The language I've chosen to work with is TypeScript. I initialized the project from scratch:

mkdir ella-math
cd ella-math
git init
npm init
npm i typescript -D
./node_modules/.bin/tsc --init

In order to continue, I had to learn about the basics of the module systems used in JavaScript and by node.js and NPM.

Module systems

In the first place, NPM (and node.js) uses a module format that is called CommonJS. CommonJS syntax looks like this:

// a vector class
class Vec { /* ... */ }

// a matrix class
class Mat { /* ... */ }

module.exports = {
  Vec,
  Mat
};

In node.js, you can use the module by using require():

const { Vec } = require('ella-math');

const a = new Vec(1, 2, 3);
const b = new Vec(4, 5, 6);
const c = a.add(b); // (5, 7, 9)

Unfortunately, if you want to try to use it directly in the browser by embedding the library via <script> tag, that does not work, because the browser doesn't know about module or require.

One early approach to get a module system into the browser without having additional build steps was RequireJS. RequireJS also provides a require() function, but as the scripts are loaded asynchronously, the CommonJS syntax could not be used. So, requireJS came up with a module definition format that looks different and wasn't comaptible with CommonJS. It is called Asynchronous Module Definition (AMD). RequireJS isn't pretty common anymore and you will only find it in legacy projects. One selling point for RequireJS was that it even runs on IE6.

So, there were 2 different module formats out there. And sometimes, you don't want to use a module system at all and just use the library via a <script> tag.

A fix for this is called Universial Module Definition (UMD). The UMD format provides the best user experience because it supports
CommonJS, AMD and also an export via global variable when no module system is available.

The catch is, an UMD module looks quite messy:

(function (global, factory) {
    typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) :
    typeof define === 'function' && define.amd ? define(['exports'], factory) :
    (global = global || self, factory(global.Ella = {}));
}(this, (function (exports) {

    exports.Mat = Mat;
    exports.Vec = Vec;

    Object.defineProperty(exports, '__esModule', { value: true });

})));

Because this is a mess, the ECMAScript specification came up with another module system: ES modules (ESM).

It introduced the import and export keywords into the JavaScript language, which looks a lot cleaner:

export class Vec { /* ... */}
export class Mat { /* ... */}

On the consumer side:

import { Vec, Mat } from './ella-math.esm.js';

<script type="module" src="index.esm.js"></script>

Because this specification introduced a keywords, older browsers cannot understand this flavor of JavaScript.

To address this, there is a type="module" attribute that tells the browser the JavaScript is using the modern module system. Old browsers don't execute it at all (like IE11).

So, in an ideal world, you want to just use the modern module specification. But NPM uses CommonJS in the first place. Additionally, you may want to provide a way to directly use your library in the browser.

So, I ended up still using the UMD module format but also providing the modern ES module format.

Compiling to UMD and ESM

To compile my library to an UMD module, I am using Rollup alongside with the official TypeScript plugin. Rollup both supports the UMD format and the ES module specification out of the box, so I can provide both flavors.

The rollup configuration (rollup.config.js) looks like this:

import typescript from '@rollup/plugin-typescript';

export default {
  input: 'src/ella.ts',
  output: [
    {
      file: 'dist/ella.esm.js',
      format: 'es',
    },
    {
      file: 'dist/ella.umd.js',
      format: 'umd',
      name: 'Ella',
    },
  ],
  plugins: [typescript()],
};

My scripts section in the package.json looks like this:

{
  "scripts": {
    "test": "jest",
    "docs": "typedoc && touch docs/.nojekyll",
    "build:types": "tsc -t esnext --moduleResolution node -d --emitDeclarationOnly --outFile dist/ella.d.ts src/ella.ts",
    "build:js": "rollup -c rollup.config.js",
    "build:minjs": "terser dist/ella.umd.js --compress --mangle > dist/ella.umd.min.js",
    "build": "npm run build:js -s && npm run build:minjs -s && npm run build:types -s"
  }
}

Because the official rollup typescript plugin does not work with emitting type definitions, I'm using an additional build step to generate a .d.ts file containing all type definitions for TypeScript.

Currently, the declaration and sourceMap options in tsconfig throw an error when using @rollup/plugin-typescript.

There is a rewrite of the typescript plugin rollup-plugin-typescript2 that fixes the issue with type definitions and source maps, but I haven't tried it.

To also provide a minified bundle, I'm using terser which works quite well together with Rollup.

Additionally, I'm using typedoc to generate API documentation from code comments using JSDoc notation.

Specify files for publishing

To specify which files are going to be published, you specify all the things inside your package.json.

The entry file goes in the main field, the type definition goes into the types field. Finally, you define a files field with an array containing the files and folders to be included:

{ 
  /* ... */ 
  "main": "dist/ella.umd.js",
  "types": "dist/ella.d.ts",
  "files": ["src", "dist"]
  /* ... */
}

Publishing on NPM

After you have created an account on NPM, you can log in to your account inside your command line shell:

npm login

Then, choose a package name and an initial version in your package.json:

{
  "name": "ella-math",
  "version": "1.0.0",
  /* ... */
}

You will have to chose a package name that is unique. To finally
release your package on NPM, do

npm publish

Counting versions up

After you have made your changes, make sure everything is committed and you are on the main branch. npm provides a built in versioning count tool:

npm version major  # v1.0.0 -> v2.0.0
npm version minor  # v1.0.0 -> v1.1.0
npm version patch  # v1.0.0 -> v1.0.1

# publish the new version
npm publish

Use major for breaking changes (every time your API changes).
The version command also creates a git tag for the specific version inside your repo. To push it to your remote repo, use:

git push
git push --tags

The released project

So, I must say, publishing a library on NPM that was created in TypeScript is not super straight forward.

You can check out the whole project at github:

https://github.com/terabaud/ella-math/

A demo using this library is on CodePen:

https://codepen.io/terabaud/pen/MWazXyd

Testing with Jest and TypeScript, the tricky parts

Lea Rosema (she/her) — Mon, 17 Feb 2020 17:09:31 +0000

Recently, I started with a side project that uses TypeScript in the frontend and in the backend. I wanted to do things test-driven and chose the Jest framework as it is a very popular choice.

When using Jest with TypeScript, I encountered some struggles and pitfalls I ran into.

I would like to share the learnings I had 👩‍💻🙇‍♀️🤷‍♀️🤦‍♀️👩‍🎤😊.

Using Jest with TypeScript

In the first place, jest recommends to use TypeScript via Babel in their documentation.

I couldn't get Babel configured correctly, so it did not work for me. I used the alternative approach via ts-jest:

npm install --save-dev jest typescript ts-jest @types/jest
npx ts-jest config:init

It generates a jest.config.js file with:

module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node',
};

If you are testing browser stuff, you can change testEnvironment to 'jsdom' to get access to DOM APIs in your tests.

Mocking stuff in TypeScript

When I first tried to use mocks in TypeScript, I got a lot of type errors when trying to access properties from the mock (eg. mockClear()).

I figured out ts-jest provides a mocked() wrapper function that adds all mock properties to the function or object you would like to mock.

Example:

Let's look at an example app that fetches a person from the Star Wars API

// api.ts

import fetch from 'node-fetch';

const BASE_URL = 'http://swapi.co/api/'

export async function getPerson(id: number) {
  const response = await fetch(BASE_URL + `people/${id}/`);
  const data = await response.json();
  return data;
}

// index.ts

import { getPerson } from "./api";

async function main() {
  const luke = await getPerson(1);
  console.log(luke);
}

main();

The testing code mocks fetch and provides a mock implementation for it:

// api.test.ts

import fetch from 'node-fetch';
import { mocked } from 'ts-jest/utils';
import { getPeople } from './api';

jest.mock('node-fetch', () => {
  return jest.fn();
});

beforeEach(() => {
  mocked(fetch).mockClear();
});

describe('getPeople test', () => {
  test('getPeople should fetch a person', async () => {

    // provide a mock implementation for the mocked fetch:
    mocked(fetch).mockImplementation((): Promise<any> => {
      return Promise.resolve({
        json() {
          return Promise.resolve({name: 'Luke Vader'});
        }
      });
    });

    // getPeople uses the mock implementation for fetch:
    const person = await getPeople(1);
    expect(mocked(fetch).mock.calls.length).toBe(1);
    expect(person).toBeDefined();
    expect(person.name).toBe('Luke Vader');
  });
});

Ignore css/scss/less imports

By default, jest tries to parse css imports as JavaScript. In order to ignore all things css, some extra configuration is needed.

Add a stub-transformer to your project which returns css imports as empty objects:

module.exports = {
  process() {
    return 'module.exports = {};';
  },
  getCacheKey() {
    return 'stub-transformer';
  },
};

Add this to your jest.config.js configuration file:

module.exports = {

  // ...
  transform: {
    "\\.(css|less|scss)$": "./jest/stub-transformer.js"
  }
};

node Express: mocking an express Response object

I was struggling with testing express routes on the backend side. I figured out that I don't need a complete implementation of the express response object. It's sufficient to implement just the properties you actually use. So, I came up with a minimal fake Partial<Response> object, wrapped into a Fakexpress class:

import { Response } from 'express';

export class Fakexpress {

  constructor(req: any) {
    this.req = req;
  }

  res : Partial<Response> = {
    statusCode: 200,
    status: jest.fn().mockImplementation((code) => {
      this.res.statusCode = code;
      return this.res;
    }),
    json: jest.fn().mockImplementation((param) => {
      this.responseData = param;
      return this.res;
    }),
    cookie: jest.fn(),
    clearCookie: jest.fn()
  }

  req: any;
  responseData: any;
}

The test code looks like this:

  test('Testing an express route', async () => {
    const xp = new Fakexpress({
      params: {
        name: 'max'
      }
    });

    const searchResult = {
      name: 'max',
      fullName: 'Max Muster',
      description: 'Full Stack TypeScript developer',
      pronouns: 'they/them',
    };
    await expressRoute(xp.req as Request, xp.res as Response);
    expect(xp.responseData).toStrictEqual(searchResult);
    expect(xp.res.statusCode).toBe(200);
  });

Aborting a fetch request

Lea Rosema (she/her) — Sun, 16 Feb 2020 11:51:36 +0000

When working with the vanilla JavaScript fetch() API, aborting a request is not too intuitive.

Why do we even need to abort a request?

One specific use case I needed an abortable request for was inside a React component. The component fetches some data at mount time and sets the fetched data inside the component's internal state.

Because the fetch is an asynchronous operation, the component could be unmounted before the fetch request is resolved. So, if you are working with a useEffect hook inside a React component, you have to provide a cleanup function that aborts the request.

How to abort a fetch request

Create an AbortController alongside with your fetch request and pass its signal property in the fetch options:

const { signal } = new AbortController();
const response = await fetch('https://yesno.wtf/api', {signal});
const data = await response.json();
// do something with data

In your cleanup function, you can then call the abort function via signal.abort();.

Wrapping it up

For my project, I wrapped it all up in a fetch wrapper class. In my project, I am using TypeScript and also took some decisions for my specific use case:

As only json data was needed, I hardcoded response.json() into it 💁‍♀️. Also I throw an exception if the response is anything else than 2xx okayish:

/**
 * Exceptions from the API
 */
export interface ApiException {
  status: number;
  details: any; 
}

/**
 * Request State
 */
export enum RequestState {
  IDLE = 'idle',
  ABORTED = 'aborted',
  PENDING = 'pending',
  READY = 'ready',
  ERROR = 'error'
}

/**
 * Ajax class
 * 
 * Wrapper class around the fetch API. 
 * It creates an AbortController alongside with the request.
 * Also, it keeps track of the request state and throws an ApiException on HTTP status code !== 2xx
 * 
 */
export class Ajax<T = any> {

  promise: Promise<Response> | null;
  abortController: AbortController | null;

  info: RequestInfo;
  init: RequestInit;

  state: RequestState;

  /**
   * Ajax constructor. Takes the same arguments as fetch()
   * @param info 
   * @param init 
   */
  constructor(info: RequestInfo, init?: RequestInit) {
    this.abortController = new AbortController();
    this.init = { ...(init || {}), signal: this.abortController.signal };
    this.info = info;
    this.state = RequestState.IDLE;
    this.promise = null;
  }

  /**
   * Send API request. 
   * 
   * @returns {any} json data (await (await fetch()).json())
   * @throws {ApiException} exception if http response status code is not 2xx
   * 
   */
  async send(): Promise<T> {
    this.state = RequestState.PENDING;
    try {
      this.promise = fetch(this.info, this.init);
      const response = await this.promise;
      const json = await response.json();
      if (! response.ok) {
        throw {status: response.status, details: json} as ApiException;
      }
      this.state  = RequestState.READY;
      return json;
    } catch (ex) {
      this.state = RequestState.ERROR;
      throw ex;
    } finally {
      this.abortController = null;
    }
  }

  /**
   * Cancel the request.
   */
  abort(): void {
    if (this.abortController) {
      this.state = RequestState.ABORTED;
      this.abortController.abort();
      this.abortController = null;
    }
  }
}

Usage:

const request = new Ajax('https://yesno.wtf/api');
const data = await request.send();

// abort it via:
request.abort();

Not sure if it really makes life easier, but it worked for me 💁‍♀️
I'd love to hear feedback about my solution and how to maybe simplify this. Also, I should have a look into all these http request libraries out there. If you have any recommendations, let me know in the comments.

Quick-Fixing the Windows command line for JavaScript development

Lea Rosema (she/her) — Mon, 10 Sep 2018 14:50:48 +0000

A major issue with using Windows for web development is the lack of a nice unix-like shell environment. Although most of the JavaScript NPM tooling also works with PowerShell or CMD, I have experienced some weird Command not found issues when working with some packages on a drive other than C:\.

An easy fix for that is to just use the bash shell that comes with git. It's more lightweight than installing a complete Linux/msys2/cygwin distribution and it suffices for most JavaScript development purposes.

I like to use the git bash in combination with hyper.is for a nice terminal experience. Just configure the shell setting to
'C:\\Program Files\\Git\\bin\\bash.exe'. I'm using a darker version of rebeccapurple as the background color (#221133) 💁.

If you are using vscode, you can adjust your integrated shell via settings.json accordingly:

{
    "terminal.integrated.shell.windows": "C:\\Program Files\\Git\\bin\\bash.exe",
    ...
}

Bootstrapping a React TypeScript project with Parcel

Lea Rosema (she/her) — Fri, 07 Sep 2018 08:11:39 +0000

With the Parcel bundler, you can bootstrap a React TypeScript project with (almost) zero configuration.

First, create a folder, cd into it, initialize NPM, install parcel and your React dependencies:

mkdir react-number-game
cd react-number-game
npm init -y
npm i parcel-bundler --save-dev
npm i react react-dom @types/react @types/react-dom --save
mkdir src

Then, open your favorite code editor. Create a index.html file in your src directory. Modern editors like VSCode provide Emmet completion features. You can just enter a !, press the tab key and you get a basic html structure. Inside the body, add a root div element and a script tag with the reference to your entry index.tsx file:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta http-equiv="X-UA-Compatible" content="ie=edge">
  <title>React TypeScript App</title>
</head>
<body>
  <div id="root"></div>
  <script src="./index.tsx"></script>
</body>
</html>

Your minimal index.tsx file could look like this. There is no special TypeScript feature in there yet:

import * as React from 'react'
import { Component } from 'react'
import { render } from 'react-dom'
// import './index.css'

class App extends Component {
  render() {
    return (<h1>Hello World!</h1>)
  }
}

render(<App />, document.getElementById('root'))

Finally, add a start command to your package.json:

{
  "name": "react-number-game",
  "version": "1.0.0",
  "description": "A number game in React",    
  "scripts": {
    "start": "parcel src/index.html",
  },
  "author": "Lea Rosema",
  "license": "MIT",
  "devDependencies": {
    // ...
  },
  "dependencies": {
    // ...
  }
}

Then, you can start your application via npm start.

Additional project configuration

Production Build

Add a build command to your package.json and run npm run build:

{
  "scripts": {
    "build": "parcel build src/index.html",
  }
}

Deployment

If you are using GitHub, you can easily deploy to gh-pages using the gh-pages npm package. I also use rimraf package to clean up the dist folder before building:

npm i rimraf gh-pages -D

Add the following scripts to your package.json:

{
  "scripts": {
    "build": "parcel build --public-url . src/index.html",
    "clean": "rimraf dist/index.html dist/src.*.css dist/src.*.js dist/src.*.map",
    "predeploy": "npm run clean -s && npm run build -s",
    "deploy": "gh-pages -d dist"
  }
}

The --public-url . parameter in the build step is important, because your project is deployed at https://username.github.io/projectname/ and the script is included with a slash by default (eg /src.0123abcdef.js). That would result in a 404 error.

TypeScript

You might need additional TypeScript configuration. Though, the minimal example works without any configuration. You can generate a tsconfig.json via node_modules/.bin/tsc --init. A nice minimal tsconfig.json could look like this:

{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "strict": true,
    "jsx": "react"
  }
}

Autoprefixer

Install autoprefixer via npm i autoprefixer -D and add a .postcssrc:

{
  "plugins": {
    "autoprefixer": {
      "grid": true
    }
  }
}

SCSS

Just add a index.scss file to your project and import it into your entry index.tsx. Parcel automatically installs the node-sass precompiler for you.

.gitignore

Parcel builds the dist files in the related output folders dist and also has a cache folder .cache. I would recommend to add them to your .gitignore file:

dist/index.html
dist/src.*.js
dist/src.*.css
dist/src.*.map
.cache

Result

See the resulting code at my react-number-game repository on GitHub.

Snippets for Vanilla JS Coding

Lea Rosema (she/her) — Sat, 21 Jul 2018 10:49:58 +0000

When coding in VanillaJS, I usually create shortcuts for document.querySelector and document.querySelectorAll. I also like to declare D as a shortcut to document:

const D = document
const $ = D.querySelector.bind(D)
const $$ = (selector, startNode = D) => [...startNode.querySelectorAll(selector)]

It's also good to know that the $ and $$ functions are already built-in aka Command Line API when you open the JS console in Devtools.

With that dollar functions, you can already use a syntax that is similar to jQuery:

<button id="button">click me!</button>

$('#button').onclick = () => {
  alert('You clicked me!')
}

If you want to play with multiple elements, the $$ shortcut to document.querySelectorAll comes into play.

<button> button 1 </button>
<button> button 2 </button>
<button> button 3 </button>

$$('button').map(btn => {
  btn.style.backgroundColor = 'red'
})

When it comes to event handling, having an on method can be useful:

Array.prototype.on = function(type, listener, options) {
  this.map(el => {
    if (el instanceof Element) {
      el.addEventListener(type, listener, options)
    }
  })
  return this // for chaining
}

This way, you can register multiple event handlers on multiple elements at once:

$$('button').on('click', e => {
  const btn = e.target
  alert('You clicked ' + btn.textContent)
}).on('mouseover', e => {
  const btn = e.target
  btn.style.backgroundColor = 'red'
}).on('mouseout', e => {
  const btn = e.target
  btn.style.backgroundColor = 'blue'
})

Hello World!

Lea Rosema (she/her) — Wed, 11 Jul 2018 16:24:24 +0000

Hello World ! ☺

My name is Lea Rosema. I am a passionate Full Stack Software Developer, currently based in Papenburg, Germany.

You can find me on GitHub as terabaud.

At the age of 8, I started to learn coding with the Schneider CPC 464 in Locomotive BASIC. At the age of 13, I switched to a 386 PC and further advanced my coding skills. I learned Turbo Pascal and x86 Assembly Language and created my first games and graphics demos using mode 0x13.

In the late 90's, I started playing with the web platform. Since then, I fell in love the web platform. I never used <blink> but a fair amount of <marquee> and started gaining backend skills with Perl CGI Scripting. Then, I switched from Perl to PHP/MySQL and ASP.NET/Microsoft SQL Server. Today, I focus on JavaScript in node.js and in the browser.

As a life-long learner, I always keep up-to date with modern web technologies and love to work on projects following agile and test-first development workflows.

I also enjoy creative coding and audio/graphics programming, playing with HTML5 Canvas, SVG, WebGL and exploring new JavaScript APIs for fun and profit. Check out my works on CodePen.

DEV Community: Lea Rosema (she/her)

Eleventy in eleven minutes

Table of Contents

What is Eleventy?

Why Eleventy?

Create a new project

Initialize your repository

Configuration

Adding content

Markdown and front matter

From content to paths

Running and building

HTML templates

Using your templates in your content files

Extending your templates

Includes

Providing data for your site

_data example

_data javascript example

Collections

Collections example

Filters

Adding a custom filter

Processing include files with a filter

Built-in filters

Plugins and tools

Adding toolchains for CSS and JS

CSS transpiler only

Or complete Javascript+CSS toolchain.

Example project

Resources

Thank you 👩‍💻

Proxy your Backend API to the Parcel Development Server

Realtime video processing with WebGL

Some WebGL Basics

Quick GLSL facts

Types of shaders

Vertex shader

Fragment shader

Types of GLSL variables

Uploading image data to your WebGLRenderingContext

Reading texture data inside your shader code

Accessing the Webcam

Provide a Fallback Image

Putting it all together

Conclusion

Resources

I created my first TypeScript library and published it on NPM

Why?

Getting started

Module systems

Compiling to UMD and ESM

Specify files for publishing

Publishing on NPM

Counting versions up

The released project

Testing with Jest and TypeScript, the tricky parts

Using Jest with TypeScript

Mocking stuff in TypeScript

Example:

Ignore css/scss/less imports

node Express: mocking an express Response object

Aborting a fetch request

Why do we even need to abort a request?

How to abort a fetch request

Wrapping it up

Quick-Fixing the Windows command line for JavaScript development

Bootstrapping a React TypeScript project with Parcel

Additional project configuration

Production Build

Deployment

TypeScript

Autoprefixer

SCSS

.gitignore

Result

Snippets for Vanilla JS Coding

Hello World!

`_data` example

`_data` javascript example