Dev Blogging: An Attempt to Maintain Focus

I want to put my effort and focus into my job. I’m finding it difficult lately. For various reasons I’m not feeling very productive, seeing a decreased amount of focus during the day. Yesterday I was able to focus for a few meetings, but the rest of the day I was distracted constantly. Then about 4:30 I felt the energy drain out and my mind felt fuzzy and I was suddenly able to focus. 45 minutes of productivity per day is not enough.

The honesty is difficult. This blog has not been about things like this in a long time. I don’t like the idea of publishing these thoughts forever, they are pretty cringe. At the same time I’ve been watching youtube channels where people do fun projects and also just show the real side of themselves. I don’t think I can do video right now, but I can write and publish a blog. And it might help me when I feel like I need to just get some of the thoughts out of my head. ADHD is difficult to manage and having a place to pour some thoughts out might help.

So that’s this post: a log of my thoughts and accomplishments from one day. An account of what I’m doing to deal with various challenges and tasks.

Today I plan to do the following:

  1. Have several short meetings about current projects.
  2. Edit and Post this file at the end of the day.
  3. Call and set up a Doctor’s appointment.
  4. Create a react-native test application with an embedded webview that can load with injected authentication tokens.

This file will be updated as I proceed.

9:16 AM

Just wrote the above. Listening to Pandora station “Tiësto Radio”.

Installed https://github.com/react-native-webview/react-native-webview in my test project. It’s an expo app. Something weird happened to my project. The start script changed form expo start to react-native start. When I run react-native run-ios it starts up a very slow xcode build process.

I have about 1 hour until my first meeting of the day.

9:29 AM

I did somehow get the simulator to open my project.

expo start --dev-client then click the link in the web UI “Run on iOS Simulator” whick opens a custom URL scheme link on the device.

It shows the app with custom native code inside it. Now can I get it to run on my actual device?

simulator

I want to skip the EAS build service for now. Can I just use the built in Apple tools? Plug in my iphone with USB. Launch XCode. Apple Docs. Add my work apple id to the accounts preferences in XCode. Change the project settings the associate with my work team for apple developer program membership.

Receive error in XCode:

1
2
Failed to register bundle identifier
The app identifier "com.timbly.donewithit" cannot be registered to your development team because it is not available. Change your bundle identifier to a unique string to try again.

Wat? Go make some more coffee. Just opened a new bag of “Late Night” from Methodical Coffee. Dark roast provided by bottomless.

9:54 AM

Worrying about tornadoes.

9:58 AM

If the proof of concept app doesn’t run on an actual device it doesn’t count as working in my mind. It’s important to carry test projects through the lenght of the development cycle. We call them tracer bullets sometimes. There’s not a lot of meat on the bones, but the project needs to traverse the full length of the process to find any gotchas.

Changing the bundle identifier to something else fixed the error in xcode, because I created the project and gave it a bundle identifier before I added my new apple ID that’s associated with a developer account.

10:05 AM

Build errors relating to expo. errors

Attempting to close xcode and open the .xcworkspace file instead

It’s building for longer - so this feels promising.

No, it failed in the node scripts.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
+ node /Users/tim/Sites/expo/DoneWithIt/node_modules/react-native/cli.js bundle --entry-file index.js --platform ios --dev true --reset-cache --bundle-output /Users/tim/Library/Developer/Xcode/DerivedData/DoneWithIt-hicxjkqmmrjkcrhavcnkptgegaxi/Build/Products/Debug-iphoneos/donewithit.app/main.jsbundle --assets-dest /Users/tim/Library/Developer/Xcode/DerivedData/DoneWithIt-hicxjkqmmrjkcrhavcnkptgegaxi/Build/Products/Debug-iphoneos/donewithit.app
warning: the transform cache was reset.
Welcome to React Native!
Learn once, write anywhere


events.js:167
throw er; // Unhandled 'error' event
^

Error: EMFILE: too many open files, watch
at FSEvent.FSWatcher._handle.onchange (internal/fs/watchers.js:123:28)
Emitted 'error' event at:
at NodeWatcher.checkedEmitError (/Users/tim/Sites/expo/DoneWithIt/node_modules/sane/src/node_watcher.js:143:12)
at FSWatcher.emit (events.js:182:13)
at FSEvent.FSWatcher._handle.onchange (internal/fs/watchers.js:129:12)
+ [[ true != true ]]
Welcome to React Native!
Learn once, write anywhere


node:events:371
throw er; // Unhandled 'error' event
^

Error: EMFILE: too many open files, watch
at FSEvent.FSWatcher._handle.onchange (node:internal/fs/watchers:204:21)
Emitted 'error' event on NodeWatcher instance at:
at NodeWatcher.checkedEmitError (/Users/tim/Sites/expo/DoneWithIt/node_modules/sane/src/node_watcher.js:143:12)
at FSWatcher.emit (node:events:394:28)
at FSEvent.FSWatcher._handle.onchange (node:internal/fs/watchers:210:12) {
errno: -24,
syscall: 'watch',
code: 'EMFILE',
filename: null
}
Command PhaseScriptExecution failed with a nonzero exit code

Googling

Attempting: brew reinstall watchman

Requires XCode command line tools. Attempting xcode-select --install

too long

11:26 AM

Two meetings. Need a break. Time to make some lunch and then watch some youtube.

12:00 PM

I had a confusing meeting that was full of information that I don’t know what to do with it. I have enough to keep me busy this is a confusing thing to try to figure out.

12:21 PM

I feel so lazy. I can’t do anything.

YouTube is stupid. There’s nothing on there. I don’t want to play games.

Time to call that doctor.

Reinstalling watchman again while on hold.

It’s weird that macOS is version 11 now. It’s been OS X v 10.x for almost 20 years.

3:38 PM

Got sick while on hold. Really sick to my stomach. Had to lay down. Took a long nap. I feel like a failure. Back up and trying again. OK, let’s see if the stupid project will build again.

3:43 PM

OK the development app started on my iPhone but I can’t get it to connect to my launcher.

3:50 PM

OK, got it figured out. It seems to be just my laptop’s IP address and port 8081. And it reloads when I change my JS. Now I can start testing it for real on a real device. Success!

4:05 PM

Love this channel: https://www.youtube.com/watch?v=fNxcOON1VNM


Outcomes

Meetings: partial success, had to skip 2 while sick

Posting this file to my blog… waiting until the next day.

Call and set up a Doctor’s appointment: fail.

Create a react-native test application: Partial Success. Still need to test the webview and the auth tokens.

icon

Speed up react and typescript testing with baretest and es-build

I have to admit that frontend testing is not my favorite thing to spend time on. Frontend tests tend to be fragile and tightly-coupled to non-functional aspects of the code like text labels and classnames. I prefer to write tests for pure functions that calculate or transform data in somewhat complex ways, and most of this happens on the backend. I fully expect developers to write tests for their backend API code, even to the level of testing that ORM models and SQL scripts work as expected.

But still I can’t leave the testing story where I did in the previous post about developing with estrella and es-build. Basically I just left mocha and ts-node as the solution in my sample project. But that’s not a great answer. I have seen that it is a fairly slow and heavy combination of tools. The popular alternative of Jest, Babel and Enzyme may not be fast enough for everyone either.

So I took my philosophy to creating a custom dev and production build script and applied it to the test script. The first step was to identify the minimal testing solution for my needs. Research revealed a new JS testing tool released last year called Baretest.

Minimalism (or when and why to reach for something weird)

Sometimes complex tools are complex for good reasons. Even if I don’t agree with all of the design decisions, I think the React team has built a VDOM library that is going to be the standard for building web applications for a long time to come. React is not minimal like preact – or a dozen other minimal alternatives – but, it creates an abstraction layer that is widely learned and used by many developers. Conceptually very similar to JQuery back in the day, it’s just so widely known that it’s useful as a target for teams to standardize on.

Other times a tool is just the standard because of popularity and there’s room to build something tiny to replace it that meets just the requirements you have. For example React is good, but Create React App installs half of NPM when you start it up. Every dependency and line of code in the dependency is something that theoretically affects the code you have to ship and maintain, including your build-tools. When someone new joins the team, they will have to learn the tools you’ve chosen, so the tools should be small and easy to understand, with a minimum of “magic”.

Baretest is about 50 lines of code with one dependency. It will execute faster and with less overhead than Jest. Instead of babel and tsc we can use es-build, it is faster that babel to compile typescript and JSX into compatible standard JS. Source transpilation and test runner overhead are the two long poles I wanted to address in test startup time for my sample project. Once I’ve seen how small and simple a testing script can be, I will be better informed about reaching for a big library in the future.

Step 1: Write a test with baretest

Here’s my setup helper setup.ts file for creating a dom environment in Node.

1
2
3
4
5
6
7
8
9
import "jsdom-global/register";
import raf from "raf";
export function setup(): HTMLElement | null {
raf.polyfill();
const appDiv = window.document.createElement("div");
appDiv.id = "app";
window.document.body.appendChild(appDiv);
return window.document.getElementById("app");
}

Here are the basic requirements to import

1
2
3
4
5
import assert from "assert";
import { Baretest } from "../src/typings/baretest";
import { render } from "react-dom";
import utils from "react-dom/test-utils";
import { setup } from "./helpers/setup";

Here’s the actual test function:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
export default async (test: Baretest): Promise<void> => {
test("should return hello world", () => {
const rootContainer = setup();

render(
AppComponent({ fancyName: "hello world", isVisible: true }),
rootContainer
);

assert.ok(rootContainer);
const header = rootContainer.querySelector("header");
assert.ok(header);
assert.strictEqual(header.textContent, "hello world");
});
};

And finally a test.ts file that imports and runs all the tests we are going to create.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import baretest from "baretest";
import { Baretest } from "../src/typings/baretest";

const test: Baretest = baretest("Render App");

// A big ol' list of tests to set up and run
// import new tests and call them here
import configureAppTest from "./app.spec";
configureAppTest(test);

!(async function () {
await test.run();
process.exit();
})();

Step 2: Compile tests and source code

To run the tests I create another file in the scripts/ directory that will get built once by es-build and then executed whenever I need to run my tests. This script is about 41 lines of code and 2 external dependencies (+2 transitive deps) to replace Jest (76 deps) and Babel (>15 deps [how to even count everything?]).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
#!/usr/bin/env node
import { BuildConfig } from "estrella";
import { build, glob, cliopts, scandir, file, watch, basename } from "estrella";
import { spawnSync, spawn, exec, execSync } from "child_process";
import Rimraf from "rimraf";
const testOutputDir = "build/_tests/";

/*
* Builds all src and test files then executes the tests whenever it finishes.
* Watch mode is supported with -watch.
*/
!(async function () {
await Rimraf.sync(testOutputDir + "*");
const files = glob("src/**/*.ts*").concat(glob("tests/**/*.ts"));

// the es-build options we will apply to your typescript
const buildOpts: BuildConfig = {
entry: files,
outdir: testOutputDir,
outbase: "./",
format: "cjs",
bundle: false,
debug: true,
sourcemap: true,
minify: false,
silent: true,
tslint: "off",
onEnd: startTests,
};
await build(buildOpts);
})();

/**
* Spawns a node process to run the tests
*/
async function startTests() {
console.log("🎸 Built Source Code");
const time = new Date().getTime();
const nodeTest = spawn(`${process.execPath}`, [`build/_tests/tests/test.js`]);

nodeTest.stdout.on("data", (data) => {
console.log(`[TEST]: ${data}`);
});

nodeTest.stderr.on("data", (data) => {
console.error(`[TEST ERROR]: ${data}`);
});

nodeTest.on("close", (code) => {
console.log(`🎸 Test run finished in ${new Date().getTime() - time}ms`);
if (!cliopts.watch) {
process.exit();
}
});
}

Step 2: Run the tests

1
2
3
4
5
6
7
...
"test": "npm run build:scripts && node build/_scripts/test.js",
"test:quick": "node build/_scripts/test.js",
"test:watch": "npm run build:scripts && node build/_scripts/test.js -watch",
"build:scripts": "esbuild scripts/*.ts --platform=node --format=cjs --outdir=build/_scripts/"
},
...

I added a couple different scripts to my package.json to make it easy, but I discovered that npm, pnpm, and yarn all add about .4 seconds of overhead to any script execution. So if you really want it to be fast then add executable permissions to your built file (chmod +x) and then run it directly in the terminal ./build/_scripts/test.js.

Here’s a typical run completing in less than 1 second, for example.

Step 3: Add live-watching.

1
./build/_script/test.js -watch

Sorry that was a trick, estrella gives us file watching and incremental builds as part of it’s built-in options – so any code changes are picked up and cause a rerun of tests within about 1 second. This is very powerful! Getting instant feedback on your changes is super helpful for speeding up development time and catching errors. It’s just as powerful as linting for improving code cleanliness. Your IDE probably takes almost a second to update the red squigglies on large JS file, so in theory we get feedback about the behavior and functionality of some of our code as quickly as possible! Now of course if your tests are integration tests they are going to be slower while they deal with more layers of the stack, but for simple unit tests this approach should be effective.

View the Source Code for this sample project.

icon

Imperative JS builds: es-build and estrella

I recently dug into a new tool that I wanted to explore called es-build. It’s a super-fast typescript compiler and JS bundler that competes with babel, rollup and webpack in certain ways.

You point it at an entry-point file and tell it to bundle it up for the browser (or node) and it does the rest. It converts typescript out of the box, without relying on tsc. The developer’s benchmarks show es-build is many times faster compiling most projects.

I put es-build into a react webpack project with esbuild-loader and it was almost too easy. But it doesn’t support hot module replacement and it doesn’t appear to be on the roadmap.

I like webpack, I think it has a lot of powerful features and is the most robust tool to reach for when you’re building a large project. But, I enjoy playing around with other tools when I can. And I’ve been enjoying the process of building my own framework and toolchain to really understand what’s possible with frontend tools. I like the approach of imperative over declarative syntaxes. And webpack is very declarative most of the time. The mixing of declarative and imperative code in webpack configs is the reason it’s so powerful but it also confuses beginners.

So I set out to write a live dev server and production build script using typescript and no webpack. I still pulled some tools off the shelf and might switch some of them out as I continue to learn.

Just show me the code.

The first tool I found while researching was Estrella built by Rasmus Andersson – who’s kinda brilliant. It encourages a simple approach, it’s API is clear, and it reminds me of Gulp. If you want to understand what really happens when you run npm run dev then this approach will help with that. It takes away some of the magic. Of course abstractions are still useful, we don’t have to examine every part of the stack. But code is better for configuration on something that is so critical to getting work done and so often fails and stumbles in real-world scenarios. In my experience local dev environment setup is one of the biggest sources of confusion and frustration when new developers join the team. Too much magic gets in the way of learning and fixing your own code.

So when a user run’s npm run dev first we use es-build to build the dev.ts file, then we run it with a command line option of -watch.

1
2
3
4
5
"scripts": {
"build:scripts": "esbuild scripts/dev.ts scripts/helpers.ts --platform=node --format=cjs --outdir=build/_scripts/",
"dev": "npm run build:scripts && node build/_scripts/dev.js -watch",
"build": "npm run build:scripts && node build/_scripts/dev.js -production",
}

I’m not bundling this build script because live-server is not happy with bundling, so we just set the format to CommonJS and let it run like a plain old node app. I’ll probably find an alternative to live-server eventually.

What’s first in the dev server? The same thing you would have in any script, a bunch of constants for configuration!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// for configuring this script's command line arguments, see also
// https://github.com/rsms/estrella#your-build-script-becomes-a-cli-program
const [opts] = cliopts.parse(
["p, production", "Creates a production build."],
["o, outdir", "Output directory, defaults to `build/`"],
["s, sourcedir", "Output directory, defaults to `src/`"],
["t, staticdir", "Static file directory, defaults to `static/`"]
);

// set up all the directories we want to work in
const src = subdir(opts.sourcedir || "src/");
const output = subdir(opts.outdir || "build/");
const staticDir = subdir(opts.staticdir || "static/");
const cssFilter = /\.css$/i;

// the es-build options we will apply to your typescript
const buildOpts: BuildConfig = {
entry: src + "index.ts",
outfile: output + "index.js",
bundle: true,
...(opts.production
? { debug: false, sourcemap: false, minify: true }
: { debug: true, sourcemap: true, minify: false }),
};

I know this is a little silly, because I was just complaining about configuration, but some of this stuff is already properly abstracted, and the variable name’s meaning should be clear to developers.

I create a few helper functions then I start the actual build process.

1
2
3
4
5
6
7
8
9
10
11
/**
* ==========================================
* Start running custom build steps here.
* ==========================================
*/

// this can run in parallel with the rest of the build
scandir(staticDir).then((files) => {
console.log("🎸 Copy Static files");
files.map(copyToOutputFrom(staticDir));
});

Copying static files to the build directory is called out first. I make heavy use of promises because most javascript developers need to know how that works anyway, and it’s useful for this type of project.

After the static files I start dealing with CSS files. In my project I need to process my CSS files before I run my Typescript Build because otherwise type checking will fail. Normally es-build doesn’t even do type-checking but estrella starts up a tsc process to do that for us in parallel with the build process so we get feedback about type errors on the command line while the dev server is running.

The postcss pipeline is abstracted away and configured in it’s own file postcss.config[.prod].js and postcss uses the tailwind plugin which consumes tailwind.config.js. It’s a little frustrating to still have so many config files, but those tools normally configured in this way and all the documentation around tailwind will point developers towards those files anyway so I didn’t want to break existing mental models for those tools.

When I call the postcss command inside my helpers I pass a different set of plugins and options if it’s in production mode to purge the CSS files and minify them with cssnano.

After the CSS is ready we will run esbuild, start our live development server, and start watching for any file changes we care about.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
/**
* Build and Transpile Sources
* Order of operations:
* 1. Process CSS,
* 2. In dev mode: start the server
* 3. In dev mode: start watching for CSS file changes to rebuild them
* 4. Build JS,
*/
scandir(src, cssFilter)
.then((files) => {
console.log(
"🎸 Process CSS with Postcss and Frets Styles Generator",
files
);
return Promise.all(files.map((file) => processStylesheet(src + file)));
})
.finally(() => {
// Run es-build on our typescript source, watch mode is built in
if (cliopts.watch) {
console.log("🎸 Starting dev server.");
liveServer.start({
port: process.env.PORT || 8181,
root: output,
});
console.log("🎸 Watching for file changes.");
watch(src, { filter: cssFilter }, (changes) => {
console.log("🎸 CSS File modified");
changes.map((c) => {
if (c.type === "add" || c.type === "change") {
processStylesheet(c.name);
}
});
});
}
console.log("🎸 Build the JS");
return build(buildOpts);
});

What does this get us? A nice utility script inside the repo, that handles both dev and production build workflows in a way that is easy to modify and update for any developer that can ready JS already. It has far less magic than a webpack config, at the expense of being more verbose.

Where to go from here

I have considered putting all of the build and developer tool configuration in one big file with lots of comments… it would be an interesting experiment. We could bring everything to imperative run our whole developer tool-chain:

  • postcss and plugins like tailwind
  • es-lint
  • prettier
  • mocha or jest
icon

Reduce Software Delivery Cycle Time and Switch To Github Actions

At Invisible we have a small but focused team of engineers that want to ship quickly. We are marching towards a goal of building a company and technology platform that can employ people everywhere in the world to do knowledge work at a fair wage. We manage complex project and operations teams with our custom tools, so we have a lot of software components that need to be developed and maintained.

We have adopted a monorepo structure for our platform so that everyone on the team remains in tight sync on what is happening around the different parts of the company. This also allows us to maintain some level of coupling between front-end and back-end services without creating multiple PRs on different repos. The unanticipated cost of the mono-repo for us was the time our CI pipeline took to run.

We were on CircleCI and had configured our CI test jobs to run all of the tests for every service in parallel every time we push code to a Pull Request. This configuration is perfect if you need to make sure that one service wont fail when another service or package changes. We treat our entire platform as one product, even though certain members of the team focus on just one part of the platform most of the time. But, our PR test runs were very slow, often over 20 minutes. This was happening because of several configuration choices we made early on, including running yarn install with lerna across every service and package up front then caching, which resulted in a 900 MB workspace cache file that needed to be downloaded for every successive step in the CI work-flow.

A slow test run time is annoying, but it became unbearable when we started insisting on a linear git history for our master branch. This setting means that every PR has to be re-based any time another PR is merged by someone else. Since we often have a dozen or more active PRs being worked on in one repository, this timer would have to re-start many times each day. Developers would make a change to code, see the test results come back, but the master branch had already been merged into by someone else. The owner of the PR would need to go back, re-base, force push, and start waiting for tests to finish all over again. Getting a feature to staging would often take an hour of sitting and waiting, and coordinating with other devs. Deploys to production often required manual intervention by a developer using a command line tool.

The core problem here is “tight coupling”. One team’s ability to ship is impacted by another person or team’s actions (merging first). Developers were prevented from finishing their work by circumstances outside of their control. With a structure like this, each developer we add would slow down every other person and team, that’s inverse efficiency scaling! Adding more people slows us all down! On the road to speed all instances of tight coupling between teams and services need to be eliminated.

This resulted in a very slow “cycle-time” — the time it takes to get from PR open to deployed in production. Every time a developer has to switch contexts and wait for an async process results in massive inefficiency.

We began outlining what we wanted to change about our CI configuration and created a goal of every CI test run being finished in less than 5 minutes. And every deployment script finishing in less than 5 minutes. Here’s how we configured our work-flows to do that.

  • We use path filtering in actions so that only the services that have changed actually run their unique tests.
  • We parallelized our runs so that multiple kinds of tests run at once.
  • We utilize small caches, unique to each service, instead of one big cache, so it can be downloaded and decompressed in seconds.
  • The only “global” tests are very short linting tests that don’t require as much installation and setup time.
  • We added a check to our back-end service that spots any breaking changes to our graphql schema and stops developers from shipping breaking changes, which helps eliminate another point of tight coupling between services.

After these changes our PR test suite runs between 1 and 4 minutes. All of this has significantly improved our cycle time. Everyone on the team can feel how much faster they are able to move with these shorter waits. We are also able to deploy more confidently because we know changes and fixes will be relatively quick and cheap to ship as well.

The switch from Circle to Github Actions will impact our bottom line as we will be using fewer minutes of compute time and we can use lower cost compute resources since each work-flow is doing less work. We can also take advantage of the 3000 minutes that are included with the Github pro team plan we were already paying for.

We are going to add a few more lint checks in the near future, and improve our automatic syncing of issue status in JIRA using these actions. I’m very excited about unblocking our engineering team to move faster. Instead of slowing down as we add more engineers, we can ensure each developer on the team is able to ship more often and more confidently.

icon

The Bridges Between Design and Code

The problems with design-code hand-off are still manifold. I’ve been doing this for like 20 years and the process of turning visual direction into interactive applications is still fraught. Here are a few hints and principles to help you understand where this problem space has evolved lately.

  1. Use Figma, but it’s not magic. Figma is an excellent design tool that is more accessible to devs since it’s web-based and collaborative. Devs get better access to measurement tools, colors, and specific CSS values that can be forklifted into a component, but honestly that saves us 2—5 lines of code in the component implementation, so don’t get hung up on that.
  2. Don’t try to keep your static designs perfectly up to date with the work that makes it into production. Design tools are best used for creating a point-in-time snapshot. That snapshot will be attached to a story, ticket or issue in the project management tool, directing what developers should be creating. If the first implementation was sloppy and rushed because of deadlines, then put another story in the next sprint and keep circling in on that perfection until the product manager tells you to stop.
  3. Developers should not be allowed to push code to production without someone reviewing it for proper reuse of components and consistent usage of design token values instead of hard-coded colors, fonts and sizes.
  4. The designer needs to start with a systems and tokens mindset. They have to create reusable symbols that stick to a strict set of font styles, and colors. These values need to be synced with the code component theme values constantly. Also, the designer should have symbolic representations in their design tool that closely match up with the components that the developers have created.
  5. A documentation site or app for you system is nice, but quickly turns into so much useless static artifacts if it’s not tightly integrated with the code that runs in production. For this reason we use Docz to write markdown with lots of integrated live examples of everything the component API is capable of.
  6. Having a designer that knows how to write CSS and HTML is incredibly valuable. Working in the correct medium of the web is a turbo-booster in making that transition from idea to implementation.

I still operate on both sides of this line, I produce designs for one team to implement in Figma, and have to answer their questions to give specific answers about all the details that a static image can’t cover. In my experience humility and agility are key in the design role.

I also create React components based on the work of designers in another team and manage a dev team that produces components in a design system. We have to deal with all the technical aspects of packaging up a library of reusable widgets, and maintaining them. I believe Organization and communication skills are key in the engineering management role.

icon

Put Your Design System in a Coda.io Doc

I’ve been a fan of user-friendly user-configurable information management web apps for a long time. I love AirTable, I loved (the now defunct) FieldBook even more. I’ve enjoyed the power of Notion.so, Quip, Slab, and Confluence as team wikis and collaborative spaces. I wrote an article a while about about putting your design system in a wiki which was all about creating organization structures and page templates to make your team’s product design system great inside of a wiki - a tool that is simple for non-developers to use.

I am a developer, I do love putting design systems in code repositories like Fractal, Storybook, and UI Engine. But, I think there’s a place in modern product teams for an easy to edit document, bringing together multiple facets of designer’s and developer’s deliverables. I’ve observed teams using big, long Google Sheets to update the status of their design systems, each component getting a row and being updated to show progress in a central place. Well, I of course started thinking about other ways to organize that go beyond a spreadsheet. Project management tools like Trello and Pipefy are good for managing units of work as they move through various states in a process, so that seemed like a good option…

But, then I found Coda. It launched early this year and it’s pretty incredible. It starts with a basic collaborative text document but encourages you to start creating data tables (like Notion and AirTable have). But, the super-power of Coda is the presence of one very important integration, Figma. If you’re designing in Figma, then Coda is the perfect fit.

The Figma integration allows you to copy and paste a URL from the node of a figma document (using the browser not the desktop app) and paste that url into a special formula cell, which formats and displays a nice link with the name of the selected frame, along with a PNG snapshot of the frame as it looks currently. This means you can create a table that describes various components and screens in your application, track their status and see a nice little updated thumbnail right in the same row.

project management tables

The Figma integration (Coda calls it’s integrations “packs”) also pulls in the last modified date of the frame as well as the number of comments on it in Figma. The other data checkboxes and dropdowns are all completely customizable for your purposes inside of the Coda table. 

It’s possible to embed static designs from Sketch of course, but it’s not as full featured. Perhaps Sketch will be releasing web-facing APIs later this year.

There is another useful integration you might notice: that button in the screenshot that says “Ping Slack.” It will send a pre-formatted message to a specified channel with the relevant details about this design task. The button is disabled until a user marks the row as “Designed”.

Coda also has good integrations with Github, so if your development team is creating issues or Pull Requests that correlate with the design tasks, then those can be added as special links here as well, with columns that show summary data about the status of the issue or PR pulled from the the Github API.

bar charts

Each table in Coda is not isolated, it can be referenced from other tables, viewed in multiple different charts, and displayed in many formatted or grouped views of the same data. Each cell or row can have conditional formatting and you will find many of the same types of formulas you would in Excel.

pie charts

The addition of the integrations with Slack, Figma and Github mean that you can finally bring things all together in one place. Figma bills itself as “the app other people use to build their own apps”. This seems true to me, it’s perfect for creating your own custom project management tool, research data tool, documentation tool, feedback gathering tool, and process collaboration tool. Each of these is possible if you just dig in and start building or look at their examples. If you’ve found yourself wishing that excel or google sheets could do more, this is for you.

The next part of a design system creation process is tracking the implementation by frontend developers in various platforms. Creating a table that summarizes all of the components you created in Figma is easy.

component table

Then you can create a detailed page documenting the design and implementation details of each component, and link to it from the main table.

Button types table

On this detailed screen you can embed long Gists of HTML, links to Github commits for the SCSS, Figma frames, or embed the Wireframes from Miro, or maybe add an example animation in a video. You could even link to the UX research tasks and survey results that you’ve gathered in other tables of the document. And, of course, it’s easy for anyone on the team to update this document. They don’t have to open a markdown file and learn git to commit it to a repo. 

I see people asking about the limitations and advantages of various hosted design systems tools all the time, ZeroHeight, Invision, Zeplin, Abstract, etc. I think those tools are really interesting, but ultimately can’t stretch to fit every usage scenario. It’s possible what you really want is something more free-from, less prescriptive - something more collaborative for the whole company to own and use. I think it’s worth trying to put your design system in Coda… for my clients at Systematic UI, I’m already trying it out.

Weeknotes 5

Monday

This Vue + ElementUI + Typescript template is quite well put together. Very handy for getting a Proof of Concept up and running. https://github.com/Armour/vue-typescript-admin-template

Tuesday

I had to write some python for someone… it was weird. https://www.mongodb.com/blog/post/working-with-mongodb-stitch-through-existing-drivers--python

This tool is a nice way to deal with SVG file, possibly better than Fontawesome. https://github.com/MMF-FE/vue-svgicon

https://iconsvg.xyz/ Here’s an easy place to get a few free SVG icons quickly.

Wednesday

https://github.com/mcibique/vue-date-fns - now that’s useful! Create a reusable date-formatting Vue filter that is light-weight and easy to understand.

1
Vue.filter('datetime', createDateFilter('MM/DD/YYYY h:mm a'));

Thursday

I’ve had to create an average of numbers using .reduce before, but I apparently forgot and had to figure it out all over again.

1
2
3
4
5
6
7
8
9
10
11
private avgReducer = (prev: number, curr: number): number => (prev + curr) / 2;

private avgAnObject = (value: any[], key: string): number => {
return parseFloat(
Number(
value.map(
(x): number => x[key]
).reduce(this.avgReducer)
).toFixed(2)
);
}

Friday

More about reduce and a few really helpful utility functions using reduce, so that you don’t need to reach for lodash every time.

Speaking of which, maybe this library of LINQ inspired functions could be useful. FromFrom is a nice chainable API for dealing with lists of stuff. Here is a great explanation of why their approach is interesting:

fromfrom uses the iteration protocols to iterate through the input data. All transformations create a new iterable that when iterated reads from the previous iterable, applies the transformation and then provides the output data. fromfrom works with any input data that implements the iterable protocol. From the built-in types for example Array, Set and Map implement the iteration protocols, but for example Objects do not. fromfrom provides its own iterable implementation for objects, so they can also be used as input data.

I can dig that. I miss LINQ from C# and .Net.

Weeknotes #4

Monday

Hmm… guess I missed last week. Stress sunk it’s claws into me.

Sore back. I’m feeling so old. Did some babysitting. Grateful for a big blessing on our family.

Cleaned up inboxes and task lists.

Tuesday

Business development and networking.

Created a “hire-me” page which required further integration of the CMS on systematicui.com as well as creating a twitter card.

Wednesday

Can’t stop reading about inv.tech. What a fascinating company, so completely transparent.

Completely trapped by over a foot of snow. Winter is still here.

Thursday

So, I built an interesting script for generating a Nuxt website from a static HTML file. It’s not that hard but it is interesting. Nuxt will lose any static payload data once it’s done with hydration, assuming that you will make an API call after hydration. That’s a bit of a pain, so you have to write your dynamic generation-time data into a JSON file and then embed it in your output JS with webpack require() assignment.

Friday

🌞🌤❄️🌬☔️cool emoji weather library parses text and picks an emoji.

Started watching https://www.invisionapp.com/design-system-manager/expert-advice/heartache-design-scale

I ordered contacts with an app. Pretty neat experience, but it’s still amazing how often multi-step forms lose state or experience similar bugs.

https://blog.prototypr.io/what-do-you-need-to-know-before-starting-a-design-system-448158acc084

https://medium.com/invisible-reports/why-report-in-public-d4b94306a52f

Weeknotes #3

Over the Weekend I spent quite a bit of time on a side project that could turn into a really interesting service. It’s a tool that’s useful for deploying and testing CSS design systems. Puppeteer + Docker + Node + Typescript + Mongo Stitch. Super exciting.

Monday

Played with my boys in the morning, enjoyed the sun and watched a small avalanche on the mountain nearby.

I’ve been writing docs, and came up with 12 Factors for Enterprise-Level Front-End Code Quality

  1. Linting
  2. TypeScript
  3. Unit Testing
  4. E2E or Integration Testing
  5. Git, PRs and Code reviews
  6. Continuous Integration
  7. Multiple Environments
  8. Dependency Mgmt. & Security Auditing
  9. Visual Regression Testing
  10. Error Monitoring
  11. Performance Monitoring
  12. Documentation

Tuesday

Hey someone started on a new version of Fractal! It even has a Vue demo. 😍

I built a new project boilerplate for design system projects using Parcel for compilation, XO for Linting, even somehow managed to get TypeScript Support working.

Wednesday

Created a project generator script for design systems with different boilerplate options for folder structure and CSS preprocessors. https://github.com/sirtimbly/systematic-ui-scripts

Rebuilt a Nuxt 1.4 site in Nuxt 2.4. Figured out how to get ESLint working with that setup, and typescript again. What a pain. I never realized how easy TSLint was.

Thursday

Posted a new project on my portfolio. Designing a Perfect-fit Soluton for a Niche Industry

Friday

Re-discovered Astrum for design systems. Light weight design systems running on JS in the browser. No build step or dev server. Interesting.

Order some Darn Tough Socks they last a long time and when they do wear out you can get free replacements from the company.

Weeknotes #2

Monday

Fixed design bugs on timbly.com, more responsive, using tachyons.

Had to figure out how to tell if a slot is empty on a Vue component (TS class).

1
2
3
public get hasDefaultSlot() {
return !!this.$slots.default;
}

It’s 2019 and CSS is awesome. But, we still can’t prevent orphan words when wrapping lines of text.

Have you tried Sublime Merge? I opened it again today – I like it, but I think I still prefer fork.

Tuesday

I’m using the AWS Amplify SDK, and it’s pretty decent. Fully featured authentication implementation. Their docs are nice, and they ship Vue and Reat UI components.

Wednesday

A super usefuly way to get basic SVG icons quickly

Thursday

Doing a lot of Git rebase from multiple developers.

Trying to get fontawesome-vue to actually do treeshaking… with limited success.

Friday

An article about running puppeteer automatically

A good startting place for automated chrome screenshots

Lot’s of time automating visual regressing tests.

icon

Weeknotes #1

Saw this “Weeknotes” idea on some other blogs and decided it’s a good idea. For a while I was trying to write an article every week on dev.to – but I missed week 6 and now it’s hard to get back on the habit. Maybe if I’m adding some value to my personal blog again I can be a little more motivated to write.

Monday

Watched too much twitch. Apex Legends looks so awesome.

Set up perforance monitoring of an app through Calibre - It’s really excellent.

Looked at the latest version of UI Engine to see if it’s a good basis for my next design system. It can display plain HTML or handlebars templates like Fractal, but it also supports displaying Vue and React components, so that’s a pretty good option. Latest version has some great improvements in configuration also.

Tuesday

Found uptime robot. Good free plan. Found an interesting blog from Remy Sharp about rebuilding the very first web browser at CERN on the 30th anniversary of the web.

Wednesday

Lot’s of code reviews today. Hunting down the domain registrar for a client to see why their old website hosting dissappeared. Mystery. If it weren’t for the wayback machine we would lose a lot more websites due to neglect.

Thursday

Spent a lot of time building a initial prototype serverless+FRETS app on Zeit Now. Amazing stack. Will have to write more. It is totally possible to deploy serverless functions written in TypeScript without pre-compiling.

Friday

Discussed CSS and HTML with my mentee. Lots of basic rules like when to use position. The concepts of selector specificity, and background images. Saw a really weird thing happen when viewing a flex element on Chrome mobile viewport emulator. The whole flex item shrunk down to fit in the available flexbox space… interesting. Setting a pixel value on the flex item seemed to solve it.

Saw this article about UX and login forms from Brad Frost. Don’t Get Clever with Login Forms.

Routing and Easy Form Fields on FRETS 0.3

Made a few changes to my little web frontend library, FRETS. First of all I updated the online API documentation to clean up old pieces of code and document more funcitons in the main module.

First, one big bug was fixed. We were getting double rendering of the same state change because I wasn’t checking the cache properly. The new cache checking code should prevent double renders and still allow rendering to happen when an async function (like a fetch) calls FRETS.render(newProps).

Here’s an example of the right way to call async functions from an event listener (action).

1
2
3
4
5
6
7
8
9
10
11
F.actions.loadUser = F.registerAction((e: Event, props: AppProps) => {
fetch("https://jsonplaceholder.typicode.com/users")
.then(response => response.json())
.then(json => {
const user = json[(Math.random() * 10).toFixed()];
console.log("recieved fetch");
props.username = user.username,
F.render(props);
});
return props;
})

Fields Registry

On previous apps, for every single field that a user could change I would have to do several steps.

  • Add a property to the main modelProps class
  • Add an empty action function signature to the main actions class.
  • Add a concrete implementation of the action event handler. Usually some variation of this code
1
props.someProperty = (e.currentTarget as HTMLInputElement).value

Writing the same boilerplate is repetitive. I thought about how we as developers want to add functionality to our apps in flexible and composable way. That’s what components in Vue and React are all about. With those libraries you are building an object to fit some sort of component structure so that you can register properties inside of child components that all get rolled up into the master component. But, I want to keep FRETS free of configuration objects and string key conventions that need to be memorized.

So, I added registration methods on FRETS so that you can call a registerField() method from inside of your UI rendering methods. The entire frets App object is expected to be injected into your render methods now. That way you can still extract model props and actions from the app instance for rendering the UI, and now you can add fields to the main registry — and FRETS takes care of the repetetive event handler creation.

1
2
3
4
5
const countField = app.registerField<string>("count", "1");
return $.input.m1.h({
onblur: countField.handler,
value: countField.value,
}),

When you call registerField you get back an object with the handler and the current value, and any validation errors that have been attached to it during the validation step.

This makes it much quicker to add form inputs that are tied into your app state without having to know and declare every single model property up front. Now you can inject functionality to your app from within the render methods themselves increasing decoupling of the main app code and enabling functionality and features to be declared from within js chunks that are loaded asynchronously only when they are needed.

Routing

When I build single page apps I often end up needing to do some sort of routing to different screens based on the URL. I took it on as a challenge to enable this feature in a functional way, not using complicated configuration objects like Vue-router does. So, when you want to register a route in FRETS - what you are really doing is registering a string for matching the current URL value, and a function that will update your app state in some way when the current url matches your decalared pattern. It can be as simple as switching a value from “screen: 0” to “screen: 1”.

1
2
3
4
F.registerRoute(RouteKeys.About, "/about", (name, params, props) => {
props.activeScreen = SampleScreens.About;
return props;
});

Then when it comes time to navigate to a screen programmatically you will call a method on the app instance from within your event handler action.

1
2
3
4
5
6
7
F.actions.navAbout = F.registerAction((e: Event, props: AppProps): AppProps => {

F.navToRoute(RouteKeys.About);
props.activeScreen = SampleScreens.About;
return props;
});

Performance

The overall library size is a bit larger (15.3kb minified and Gzipped instead of 10.6kb) because I added a second dependency: the path matching library “path-parser”. In addition, the necessary features from Maquette are still included in compiled library.

I still recommend writing your UI rendering methods using atomic CSS library like BassCSS or Tachyons compiled to JS functions using frets-styles-generator. This will make writing UI code much more pleasant but adds a few more KB of javascript to your final bundle.

The updated example app frets-starter builds a final javascript bundle of 36KB minified and gzip. Which I think is very respectable. View that demo app.

Other Changes

I increased unit test coverage to around 75% now.

To support the field registry your actions and props classes should now inherit PropsWithFields and ActionsWithFields

1
2
3
4
class MyProps extends PropsWithFields {} 

class MyActions extends ActionsWithFields {}

As mentioned before, the new UiRendering method that’s passed into FRETS.registerView() should accept the entire frets object, it’s signature should be:

1
renderFn: (app: FRETS<MyProps, MyActions>) => VNode