Forem: Gal Schlezinger

Why fnm was rewritten in Rust

Gal Schlezinger — Fri, 05 Mar 2021 00:00:00 +0000

This blog post was in the “drawer” for a long time, so I thought it would be nice to just publish it.

It wasn’t very long ago, when I mentioned I’m rewriting fnm in Rust. At first, I was just experimenting in order to learn the language: fnm is kinda wide in its scope — works with the file system, network and user input, and I know exactly what to test. After a couple of days experimenting with Rust I had some insights, comparing it to Reason.

Reason and Rust feel very close, as if they were family. I guess that most of it comes from having ML-style type system with C-style syntax. Rust is usually treated as a lower-level language (it is), and as a very verbose one, because if you compare it to higher-level languages like Reason, you find yourself much more explicit about what you want, like passing references and static strings, etc. But seems that while you still think about memory more, Rust provides great ways to abstract knowledge and build higher-level components to your system.

The Trait System

I think one of Rust’s biggest strengths is its trait system. AFAIK, it is very similar to Haskell’s typeclass, Swift’s protocol extensions, and they’re very similar to Java’s interfaces, with a unique superpower: You can implement your trait on 3rd party struct — including the standard library.

That means you can implement a custom trait on std::fs::File, or implement a standard library trait to your type, like std::default::Default or std::fmt::Debug (both can be simply derived, more on that in a bit).

Reason and OCaml do not have anything like traits. You can use functors and almost get with it, but it’s not 100% there.

Seems that using traits can get you very far and provide great higher-level APIs that preserve type safety. Check out structopt, a derive macro that allows you to use the FromStr trait on any type and parse command line information from it. That means that you can declare ANY TYPE you want and use it as a CLI argument, parsing it from the user input. Do you want to use a URL? Luckily, reqwest::Url is implementing FromStr.

In fnm, we also get UserVersion which is some kind of a version requirement: it can be the system version (literal system), it can be an alias or a semantic version MAJOR.MINOR.PATCH optionally prefixed with v, where MINOR and PATCH are optional too. In fnm, we implement FromStr to UserVersion and let structopt to handle the parsing errors and print a nice message to the user.

This is one of the ways the trait system allows to build better software simpler, comparing to Cmdliner which is a great utility but was VERY hard for me to use and reason about.

Deriving

Another great Rust feature is the #[derive()] annotation. Similar to some Reason/OCaml PPX extensions, when put on top of a data structure, it can generate code for you in compile time, that will be type-checked. Rust comes with some deriving macros out of the box, like Debug (which allows you to pretty-print with the {:?} format string or dbg! macro), PartialEq and Eq for equality checks, etc.

The Rust crates embrace this type of macros, and awesome libraries use it to create higher-level abstractions:

Serde allows you to derive a Serializer and Deserializer for your struct or enum, allowing you to serialize or de-serialize these data structures safely into various formats, like JSON, YAML, TOML, RON…
StructOpt allows you to derive a Clap configuration from your data structures. This is amazing, because it removes so much boilerplate, and co-locate the CLI definition with the data structures.
Snafu allows you to get a great developer experience for error handling, by allowing you to create error enums and define the error messages next to their declaration. It also provides some nice macros to ensure! that something works, and some extensions to data structures like Option and Result for converting them into the meaningful errors you have defined.

The Community

Last year I visited Chicago to attend ReasonConf US. I talked there to great people like Jordan, Sander, Peter and Patrick. It was tons of fun, but also made me realize something I didn’t understand before.

The Reason community was divided — OCaml vs Reason, Native vs BuckleScript vs Js_of_ocaml. Being a small community, we should invest in providing the best tools and experience, and when we can’t provide the best experience if we’re not focused.

When writing an HTTP server in native Reason you might lack a library for New Relic, or Bugsnag, or Sentry. Stack traces are not really a thing. Using Node as a mature VM is very appealing — and if you need something that performs better — you can write it in a different language. Realistically, people ship Node apps all the time, so the performance and safety guarantees Reason provides should be enough.

In fnm, I couldn’t really understand how to use the tar opam package. This is why fnm used to shell out to tar, to extract the Node versions. This would obviously fail on Windows, but fnm didn’t work on Windows anyway, and I had no idea how to make it work in OCaml. In Rust, it is very easy to do conditional compilation for a specific configuration, so there are some differences in the Windows vs *nix versions of fnm now — especially regarding:

The installation files: Node.js is distributed in .tar.xz for *nix binaries, and .zip for Windows binaries.
The simple “shell inference” fnm has, to know on what shell type you’re using, is using ps on *nix, and wmic on Windows. Both share the same return types so the module abstracts away the differences.

Documentation

Rust, being a newer language, has some niceities to it, like centralized documentation on https://docs.rs. It’s an amazing experience, having all the documentation for every crate on one site with a familiar theme. I know both Ulrik and Patrick are very into it and I hope they’ll succeed doing so.

Another cool feature is the doctests which is something that I knew from Elixir and Rust supports it natively too. When you write code in your docs, cargo test will test it. It’s that easy. No more unmaintained README or other documentation. This is the future.

These are two things most languages should learn from.

Overall, feels that since the (big) Rust community is focused around the native toolchains (and not compile-to-JS), makes it easier to build native, performant CLIs in Rust compared to Reason. I no longer have to find out environment variables to compile C libraries with specific flags, because Cargo has feature toggles and I use it instead. I build an ARM-compatible binary to distribute for those running fnm in their Raspberry Pi’s. We now fully support Windows, so no more gatekeeping for people with different OS choices.

All without pounding my head against the wall.

Except from the build time, which is much faster in Reason.

Mocking in TypeScript with `factoree`

Gal Schlezinger — Tue, 02 Mar 2021 00:00:00 +0000

A couple of days ago I had a fantastic experience. Two ambitious developers asked me to review an open source project they are working on in a short video chat. I was flattered and happily accepted the offer.

We found ourselves talking about mocks in TypeScript. Since I started using TypeScript, I adopted a practice where I try to push as much as I can to the type system and use tools like io-ts to hook just enough runtime validations to ensure I can trust it.

A couple of months ago I needed to mock something in one of our tests. We have a pretty big config, generated from a confirmation system, and I needed to use a property from it in my test.

The first idea was to do something like setAppConfig({ myKey: value } as any). This worked well but it stinks from the any, which also have a very big drawback: what if the test is implicitly using a property I did not set?

Enter factoree. A simple factory generator function which will immediately throw an error when accessing a missing property. So, the previous example would be something like:

import { factory } from "factoree";

const createAppConfig = factory<AppConfig>();

setAppConfig(createAppConfig({ myKey: value }));

Can you see that we no longer have as any? Instead of skipping the type system, we generate an object which will throw an error if we accessed a missing key. Instead of playing pretend — we specify rules for the computer to enforce at runtime:

import { factory } from "factoree";
const createAppConfig = factory<AppConfig>();

const config = createAppConfig({ myKey: "hello" });
config.myKey; // => 'hello'
config.otherKey; // => Error: Can't access key 'otherKey' in object { myKey: 'hello' }

Why does it matter?

Imagine the following code under test:

export type User = {
  firstName: string;
  lastName: string;

  // more data
  website: string;
};

export function printName(user: User): string {
  return `${user.firstName} ${user.lastName}`;
}

And when we test it, we can use as unknown as User to provide only the things that are in use in our function:

test(`prints the name`, () => {
  const userDetails = ({
    firstName: "Gal",
    lastName: "Schlezinger",
  } as unknown) as User;
  const result = printName(userDetails);
});

Now, the product manager asked us to add another feature: allow a user’s name to be written in reverse. So, our code changes into:

export type User = {
  firstName: string;
  lastName: string;
  prefersReversedName: boolean;

  // more data
  website: string;
};

export function printName(user: User): string {
  if (user.prefersReversedName) {
    return `${user.lastName} ${user.firstName}`;
  }

  return `${user.firstName} ${user.lastName}`;
}

After the code change, tests should still pass. This is a problem because we access a property (prefersReversedName) which should be a non-null boolean, but we don’t pass value into it, which is undefined. This creates a blind spot in our test. When using factoree, this would not happen: if you forget to define a property, factoree will throw an error — ensuring you can trust your types.

This tiny library helped us make more maintainable code with easier assertions and better tests. No more undefined errors in tests if types have changed. Let the computer do the thinking for us.

Try it, and let me know how that worked for you!

HTML over the wire with Preact

Gal Schlezinger — Sat, 30 Jan 2021 00:00:00 +0000

I’m using Rails on a side project I’m playing with. Many of my peers would probably ask why would I do this to myself. The answer is simple: Rails helps me get stuff done quickly because it is super boring. It is so boring that it makes me excited.

My app is split in two: a widget that every website can use — a JS bundle, and a back-office/API. For the back-office I mainly use Rails and the magnificent Alpine.js. Authoring server-side rendered routes is so much easier to do with these two. Rails provides all the things I need in terms of back-end (even E-mailing comes built in!), and Alpine allows me to sprinkle JS as if my HTML was a React application: declarative, co-located JavaScript. For the widget, I use Preact. I originally started it as a React project, but I wanted to keep a minimal bundle size.

I launched a new project, and I immediately installed graphql-ruby as a GraphQL server implementation, to easily declare resources that can later be translated into type-safe data fetching from my widget. I mostly do TypeScript so it’s soothing me knowing that I can generate types and enforce them at runtime. I used urql as a GraphQL client, because it looked like it would result in a smaller bundle (~4 times smaller than Apollo) and I wanted to experiment with it.

By measuring the bundle size using tools like Webpack Visualizer, I found out that Urql bundles graphql.js to the client, and that’s something that I don’t really need — therefore, I do not want. Turned out, that Urql and its dependencies were more than 50% of my bundle size. I mean, this wasn’t very large and I was quite satisfied with Urql, but this is a widget, not an entire application. The smaller - the better - and I want GraphQL for the amazing developer experience coming from the tight TypeScript integration, but that’s something I’m fine with sacrificing in favor of my production bundle size (or solve later). Therefore, I decided to drop GraphQL and migrate my data fetching to use simple REST endpoints, with swr to hook up with Preact.

As I started building a landing page, I wanted to make an animation to showcase the product — so I made one by myself with Tailwind CSS and Alpine. Eventually, I had a very clean animation with better looks than the current product. However, since my widget is a Preact app and my server is a Rails app, I couldn’t share the components between my backend and the widget.

Or could I..?

Most Preact and React apps use JSON to pass data between client and server. What if the server already knows how to render stuff? Well, instead of serving JSONs we can serve HTML — Exactly what DHH was preaching about lately when they introduced Hotwire. So, instead of the following payload:

{
  "message_id": "abcd1234",
  "text": "Hey, friend!",
  "author": {
    "name": "Chandler Bing",
    "avatar_url": "https://friends.com/chandler.jpg"
  }
}

I could return the following HTML:

<div id="message-abcd1234">
  <img class="avatar" src="https://friends.com/chandler.jpg" />
  <div>Hey, friend!</div>
  <span>— Chandler Bing</span>
</div>

And use dangerouslySetInnerHTML in Preact and React to show the message. Since I’m using Rails and I know for sure that my HTML is sanitized, that’s not done dangerously at all. This way, I can keep my authorization and render specific layout for specific layouts and keep all his logic in my precious, well-tested back-end.

The funny thing is, that it is not a new thing. The web did that before React was a thing! You don’t have to use JSON! But, since React and other SPA frameworks have taken the world by storm, I regularly meet people who don’t know about old-school frameworks like Rails and Django. And sometimes, the greatest solutions come from mixing modern and old solutions.

Now, this path is not all gummy bears. If you’re into optimistic updates, that’s not the path for you — because it relies on the fact you want to keep as much of the business in your back-end. Rendering HTML is the cherry on top of everything.

Personally, I think that most apps are either offline-centric or online-centric. Being somewhere in the middle is confusing. If you want to implement optimistic updates, you’re probably trying to do that by manually crafting an optimistic response. That can be very hard to maintain, and you can probably get better results if you architecture your app to work offline with tools like PouchDB.

When working on my side-project, I don’t want to waste time on optimistic updates. If my server is down, I’d rather get an error. I want my project to be as simple as possible. It’s not a realtime chat application.

It’s also harder to bind to event handlers, compared to Preact-rendered applications. How would you “rehydrate” the HTML coming from the server? How can you ensure the buttons whatever you need when they are being clicked? Consider the following HTML:

<button onclick="what_should_this_fn_be()">Click me!</button>

what_should_this_fn_be() needs to be replaced with something in order for our button to be interactive. It can be inline JS, like the good ol’ days, but we won’t be able to bind it to functions in our bundle if we’re minifying them — or we would have to export them globally. Anyway, this ship has sailed. We need a better solution for event binding in our dynamic HTML sections:

Using event bubbling

This is the “manual” or “explicit” way. It’s been in use for years.

When adding onClick={myFunction} in Preact and React, you will actually get events that bubbled from the children of the provided DOM node — not just events that happened on the specific DOM node. This is a great way to solve our issue — if you have dynamic HTML that can be clicked, you can lift the event handling to the container, which lives in Preact and renders the dynamic HTML. So instead of having just a <button>, you can add some hints like <button data-action="doSomething">, and reference this data-action in your event handler:

function MyComponent() {
  const html = `<button data-action="showAnAlert">click me</button>`;
  return (
    <div
      dangerouslySetInnerHTML={{ __html: html }}
      onClick={(event) => {
        if (event.target?.dataset.action === "showAnAlert") {
          event.preventDefault();
          alert(`Look at me, I'm doing something!`);
        }
      }}
    />
  );
}

This way, the server can declaratively say what is the role of a button, and you can have the implementation in JS land.

Using custom elements

We can expose Preact elements as custom elements. So, instead of having the following code:

<button>What should I do?</button>

We can use a custom component:

<my-alert-button>Show an alert!</my-alert-button>

That would work kinda well with Preact, and can also be reused in our Rails backend. In fact, that’s what I do when rendering icons inside the Rails and the widget app, as I mentioned on this one tweet. That is somewhat a win, but when used heavily, it creates some issues.

First, I will have to work with Shadow DOM and will go outside of Preact land just to go back using Preact using the custom element. So Preact -> HTML -> Custom Element -> Preact. I can live with it but there is a better solution, that doesn’t have that massive accessibility issue:

`dangerouslySetInnerHTML` hurts accessibility

The big issue for both the solutions mentioned before is the accessibility issue coming from dangerouslySetInnerHTML: when the HTML is replaced, the DOM elements will be replaced by detaching them from the DOM and attaching new elements. That means that you lose focus and DOM state — So if you had input fields or details popovers, they will be reset.

When using a library that does DOM diffing for you, doesn’t matter if it’s virtual or not, you want to use this diff. So in Preact, we would probably want to parse our HTML into Preact elements, so Preact will know how to diff them. In React, we would want to make them React elements. In Svelte, I’m pretty sure we wouldn’t have any way of doing so because all the diffing is compiled away — so we would need to use a library like morphdom to do that.

Let’s talk about Preact.

Using `preact-markup`

Preact Markup is a cool project that parses HTML to Preact elements, allowing you to render custom HTML elements using Preact components, without the real component boundary. It even lets you override standard HTML elements with your own components. Check out the following example, which has a my-button element and overriding the standard button one:

Preact Markup’s implementation is rather easy to understand. I suggest you to try building one yourself to fully grasp the ideas there. It can be translated to React very easily. Maybe that could be a future blog post, who knows?

Summing up

Getting HTML back from the server and injecting that to our client-side apps is so nice. It works tremendously with SWR, and helped me building my side-project in a veeeeeery fast pace. The Server Components initiative by the React team is probably onto something — but you don’t need React to get the server magic. It’s all a question of trade-offs. If server-side rendering is mostly your jam, you could stick with it.

Once you need a more complicated behaviors, you can always make a JSON response — and maybe you will find yourself embedding a server-generated HTML into it to sweeten the pill 😉

CLI Apps in TypeScript with `cmd-ts` (Part 1)

Gal Schlezinger — Thu, 26 Nov 2020 00:00:00 +0000

tl;dr — for a while now, I am using a custom module called cmd-ts, which is a type-first command line argument parser. Don’t know what it means? I’ll try to explain below! Anyway, give it a try, and let’s make it better together.

I write a lot of command line applications, both at work and for my own usage. Like many, my go-to toolkit for building them in Node.js was commander or similar packages. They’re great, but after using structopt, the struct-based derive macro for the clap Rust crate, I felt something is missing.

Let’s assume we’re building a powerful cat clone. We want to read files, support reading from the standard input, and making HTTP calls. Check out the following code which implements it in a very simple fashion:

import fs from "fs";

fs.createReadStream(process.argv[2]).pipe(process.stdout);

We can use our cat clone like so:

$ ts-node ./cat.ts ./cat.ts
import fs from 'fs';

fs.createReadStream(process.argv[2]).pipe(process.stdout);

Amazing! It can only read a file, and we need to add the rest of the features, but the code is very nice. but… this doesn’t scale.

We might want to have autogenerated --help
We might want to validate that we get a value in the file name
We might want to add boolean --flags or --option=value arguments

So we need a nicer way to parse the command line arguments the user provides us.

There are not a lot of big CLI apps that are using raw process.argv. Most of them use commander which is a high-level CLI parser, and some use yargs or a similar package. If you’re familiar with Commander, you might find yourself writing something like:

import { Command } from "commander";
import fs from "fs";

new Command()
  .arguments("<path>")
  .action((path) => {
    fs.createReadStream(path).pipe(process.stdout);
  })
  .parse(process.argv);

Commander did satisfy our last requests, which is good:

We can have an autogenerated --help
It validates that we get a value for <path>
It is very simple to add --flags or --option=values

However, it does not provide us any way of type safety. TypeScript obviously can’t identify what path is. It is typed as any. It is exactly the same as named --option=value and boolean --flags. You’re in any land. This is not something we want but Commander doesn’t let us declare types anywhere. Maybe with the template strings features of TS 4.1 the Commander team will write the description string parser in TypeScript and infer everything from the string.

Commander does validate for presence of value in <path>, and it looks like:

$ ts-node cat.ts
error: missing required argument 'path'

Now, consider if you want to validate more stuff, and not just the presence of a value. What if you want to check if the provided path exists? What if we want different parsing/validation behavior, or in other words — why do we treat all input as simple strings?

Enter `cmd-ts`

cmd-ts is a new command-line argument parser library that works kinda differently. It is influenced by Rust’s structopt and provides a “type-first” approach to command line argument parsing:

Everything is type-safe
Types are both in runtime and compile-time, for maximum confidence
Parsing/validation are handled by the argument parser
Extremely easy unit testing and code sharing

Cloning the previous example

cmd-ts’ syntax is very different from Commander’s. Instead of using a builder pattern, cmd-ts favors building applications using simple function composition. This allows you to extract and share logic between applications, commands or modules — or even just to make your code shorter and more manageable. So, to replicate the exact behavior, which doesn’t show cmd-ts’ superpowers, will be the following:

import { command, positional, binary, run } from "cmd-ts";
import fs from "fs";

const cat = command({
  name: "cat",
  args: {
    path: positional(),
  },
  async handler({ path }) {
    fs.createReadStream(path).pipe(process.stdout);
  },
});

run(binary(cat), process.argv);

Let’s break it down:

command is a function that creates a command-line application. These applications can be later composed using the subcommands function. It expects a name and an optional version to be printed with --help and --version.

In order to declare arguments (like we do with .arguments() in Commander), we provide the args object to command. Every key/value pair in args is an argument definition. Arguments can be parsed in various ways, and one of them is positional: taking a position-based argument from the user input.

Each argument is parsed into a type. We provide the string type (this is an object declared in cmd-ts, not to be confused with TypeScript’s string type). These types can be consumed via a 3rd party or be easily built for your custom validation/parsing needs. We’ll see an example in a bit.

The handler function receives all the arguments parsed by args. The key/value pairs are statically typed into handler - so you can destructure the value and be confident that you will get the type you expect. In our example, path is not explicitly typed, so it uses the default one — string — and if we provided a different type (like, number), TypeScript could stop us from making mistakes in compile time.

But again — this implementation doesn’t show the amazing capabilities you can have by using cmd-ts types.

Reading an existing file

Let’s try running our command, and try to print a non-existing file:

$ ts-node cat.ts unknown-file
events.js:291
      throw er; // Unhandled 'error' event
      ^

Error: ENOENT: no such file or directory, open 'unknown-file'
Emitted 'error' event on ReadStream instance at:
    at internal/fs/streams.js:136:12
    at FSReqCallback.oncomplete (fs.js:156:23) {
  errno: -2,
  code: 'ENOENT',
  syscall: 'open',
  path: 'unknown-file'
}

This is not a nice error at all. It happens because createReadStream creates a stream from a non-existing file, and when trying to read it we get an error event which we didn’t handle. A common practice in Commander apps is to validate in your action, and therefore have a userland reporting mechanism.

cmd-ts pushes the validation and parsing into the “type”, which is a part of the parsing process. So, instead of using the default string type, we can use another type. But which type should we use? cmd-ts comes with optional “battery packs” you can use in your project. One of them is the file system pack which exports the File type, which resolves into a path of an existing file. Fails to parse if file doesn’t exist or the provided path is not a file.

The change itself is very simple to do — adding the File type to the positional argument definition:

import { command, positional, binary, run } from "cmd-ts";
import { File } from "cmd-ts/dist/cjs/batteries/fs";
import fs from "fs";

const cat = command({
  name: "cat",
  args: {
    path: positional({ type: File }),
  },
  async handler({ path }) {
    fs.createReadStream(path).pipe(process.stdout);
  },
});

run(binary(cat), process.argv);

Nothing really changed in our implementation detail (the handler function) but we do declare that we expect a file. Check out the following error message for a non-existing file:

$ ts-node cat.ts unknown-file
error: found 1 error

  cat unknown-file
      ^ Path doesn't exist

hint: for more information, try 'cat --help'

A similar error would be if we try to pass a directory to our application:

$ ts-node cat.ts /tmp
error: found 1 error

  cat /tmp
      ^ Provided path is not a file

hint: for more information, try 'cat --help'

Roll Your Own Validations

cmd-ts allows you to create custom types and validate user input yourself, abstracting it from the implementation. These types can be shared across different applications, modules and even internally in different commands. There is no reason the actual handling code should verify path existence, or that the user input is a valid URL, or that the user input matches a list of strings. It can all be baked into the parsing and provide great errors with context to whatever was wrong in their input.

Check out the implementation of the filesystem pack or the simple number type to see how easy is to implement it yourself.

The next part will be a step-by-step guide to build a custom type, which will make our code look even nicer and show how it affects testing and ergonomics.

cmd-ts has some more gems baked into it, so you should probably take a look at the docs. I personally don’t use any other command line argument parser, and it’s not only because my righteous bias — other team members at Wix are already using it to distribute great developer experience across the organization.

So you should definitely check it out, and contact me if you have any questions or issues.

Using Long Paths in Windows and Rust

Gal Schlezinger — Mon, 17 Aug 2020 00:00:00 +0000

Lately, I’ve been working on a Rust clone of fnm. I like Rust and it is a great way to learn the language. Thanks to the Rust cross-platform tooling, I got a simple proof-of-concept for Windows support quickly.

The first thing I got to do was a install_node_dist method, which takes a borrowed Version struct and a path to install into. I wrote a simple test to install Node 12.0.0 and it seemed to work on Linux, MacOS and even Windows! I was excited, but since I don’t really use Windows and fnm works perfectly well for me, I dropped it (no pun intended.)

Not so long ago I saw some tweets by @zkat__ regarding a new package manager for Node written in Rust. It made me want to play with Rust again and I decided to copy the entire fnm end-to-end test suite into the Rust project. The E2E test suite was written in Bash (with some exception for Zsh and Fish), but I migrated it to a Rust DSL so I will be able to test the same code on Bash, Zsh and Fish — “write once, run everywhere”. Maybe I’ll write more about it in later posts.

When I started migrating the tests to PowerShell, I saw that there are some versions I fail to install, because of a “path too long” error. It was weird. But since I haven’t used Windows in years, I decided to install a dev Windows VM in order to make it work. After some debugging, it seemed that the deep directory structure of the Node modules that come with Node v8.11.3 were too deep for Windows to handle with its default configurations, and I had to make some changes.

I didn’t really know how to fix it, but while traversing the web (and finding this tweet by @zkat__) I saw a similar solution in a couple of repos, including Orogene — and applying it solved my issue.

Solving the Long Paths Issue

A Windows executable can have an embedded manifest that tells Windows how to handle the executable!

This is what I was missing. By embedding the following manifest to our binary we are able to use long paths freely. Let’s say this is fnm.manifest:

<?xml version='1.0' encoding='utf-8' standalone='yes'?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
  <application xmlns="urn:schemas-microsoft-com:asm.v3">
    <windowsSettings>
      <longPathAware xmlns="http://schemas.microsoft.com/SMI/2016/WindowsSettings">
        true
      </longPathAware>
    </windowsSettings>
  </application>
</assembly>

We now need to create a resource file (I don’t really know what it is) with the following contents:

#define RT_MANIFEST 24
1 RT_MANIFEST "fnm.manifest"

The last piece of the puzzle is to embed it into our Rust program. To do that, we need to install the following crate: embed-resource and create a Cargo build script:

fn main() {
    embed_resource::compile("fnm-manifest.rc");
}

This should hopefully make your path issues disappear. But maybe in the future it will be embedded into every Rust program, who knows?

Again, thanks again for the code I copied from Orogene. Speedy CLIs for Node development are making me excited: there’s no reason we have slow tools!

Preserving Form State in Refreshes and Navigation with React

Gal Schlezinger — Tue, 07 Apr 2020 00:00:00 +0000

tl;dr: You probably witnessed it as well. You fill a form, you navigate somewhere else and then go back to realize all the form was cleared away. Maybe it was a search form or even a registration one. This shouldn’t be the case: you can write a simple hook to preserve state in the browser history. Try it live here. Also, the code is live on CodeSandbox.

These aren’t easy times. Ever since the COVID-19 pandemic stroke, I’ve been locked up to my apartment. Mainly working remotely and playing Overcooked 2 with my fiancée. Last week I had the chance to volunteer in a non-profit project, where I was writing some front-end code (forms!) in React. I haven’t written actual front-end code for a while, which was a fresh breeze.

The form itself was split to 3 pages, or “stages”, to make filling it easier:

I started by coding every stage on its own. Adding navigation later should be easy and not a problem, thanks to React Router v5. This made my coding experience REALLY fast. When I got to navigation, using RRv5 was kinda easy. I decided to use the browser history state to pass the page results between pages. The browser history state is a way of passing data or storing data in the history stack itself, instead of adding a new global state to the app. So navigating looked like this:

import { useHistory } from "react-router-dom";

function MyComponent() {
  const history = useHistory();

  return (
    <button
      type="button"
      onClick={() => {
        history.push({
          pathname: "/next-page",
          state: {
            firstSectionResult: THE_VALUE_I_WANT_TO_PASS
          }
        });
      }}
    >
      Next step
    </button>
  );
}

How does it work? Well, if you long-press the “back” button on your browser, you’d probably see your history for this specific tab. Using window.history.back() is a handy way to go back programmatically, but it’s not the entire API that the browser gives us. It also gives us the power to manipulate the history stack with pushing a new item and replacing the current item. Each item on the history has a path name and state that you can manage. Most project I witnessed don’t use the history state at all, despite it being a super powerful tool!

I also provided a hook to read the value off the history state:

import { useHistory } from "react-router-dom";

export function useFirstSectionResult(): FirstSectionResult | undefined {
  const history = useHistory();
  const result = history.location.state?.firstSectionResult;
  return result;
}

Now I could use the history state in the next page just by calling this hook. If I got undefined, I could redirect the users back to the first section so they will complete it. I saw that this idea works, and I was excited to try pressing the browser’s “back” button to immediately press “next” to see that the state management actually works.

So I hit the “back button”. The form that I just filled is empty. When I clicked “next” the second stage of the form worked as expected, but I was very annoyed by the fact that all the fields I filled is now completely empty.

Solving the State Preservation Problem

This is a problem we have in modern front-end apps which we hadn’t when we were doing forms generated by some backend (like Rails or ASP) because the browsers do try to remember the values we filled in the forms! Because all the routing and rendering happens on the client side, way after the browser “rehydrates” its inputs, we lose all the state of the form.

This is clearly unacceptable because it’s the worst user experience there is. I discussed with the people who volunteered with me regarding the issue and consulted Google. Seems like like most solutions are using localStorage, sessionStorage and indexedDB. I decided to go with sessionStorage because both localStorage and indexedDB sounded like a long-time cache and a session-long cache sounds appealing to me.

I decided to go and make a custom hook (useSessionState) that worked like useState, only read the initial value from sessionStorage, and wrote all changes to sessionStorage as well. Then, I made all form elements controlled by specifying onChange and value.

Thinking about the solution again, I didn’t think it is good enough. The main problem I have with it, is that sessionStorage is consistent across different browser tabs/windows. It is basically a global cache. That means that you can’t use the form in more than one tab(!). Not exactly what you expect from a web browser. Imagine you open multiple tabs and fill forms just to realize they override each other silently. Absurd!

This would also happen in localStorage and indexedDB because they too work like a global cache. So how can I still make the form work across different tabs while supporting refreshes and navigations?

Altering the History State

Remember the browser history state we have just used to provide state when navigating to a new page? We did it by calling the History push function. What if we could change the current page’s navigation state? Apparently, this is possible using the replace function, which replaces the current item in the history stack instead of pushing a new one (which is the normal behavior of navigation). We can avoid altering the pathname (or URL) part, and only alter the state, like so:

history.replace({
  ...history.location,
  state: {
    ...history.location.state,
    SOME_ITEM: SOME_VALUE
  }
});

This can be wrapped in a hook, to make it look and feel like the useState hook:

import { useHistory } from "react-router-dom";

function useHistoryState<T>(key: string, initialValue: T): [T, (t: T) => void] {
  const history = useHistory();
  const [rawState, rawSetState] = useState<T>(() => {
    const value = (history.location.state as any)?.[key];
    return value ?? initialValue;
  });
  function setState(value: T) {
    history.replace({
      ...history.location,
      state: {
        ...history.location.state,
        [key]: value
      }
    });
    rawSetState(value);
  }
  return [rawState, setState];
}

Now, when we don’t have any plain useState in our form, every form input (and even complex JSON objects) will be preserved across refreshes and page navigations without further thinking. This solution isn’t just for people who use React Router. The attached CodeSandbox has a native implementation you can use anywhere. Make sure to open the preview in a new window because CodeSandbox’s preview pane does not preserve history state.

You see, making forms didn’t use to be hard. Making them work like they did while using modern front-end frameworks shouldn’t be either. Implementing this simple setHistoryState makes us stop thinking about how to manage forms’ state and lets us just write forms with a great experience. All thanks to the History API, which doesn’t only allow us to do magnificent client-side routing, it also helps us preserve meaningful state for our pages. 🎉

Stringly and Strongly typed TypeScript

Gal Schlezinger — Tue, 26 Nov 2019 00:00:00 +0000

There’s a rational fear coming from JavaScript to TypeScript. The thought of having to mess with static types instead of focusing on runtime code sounds annoying. For coders who know static typings from languages with inferior type systems, like Java, or languages with awesome, yet different type systems, like Reason, OCaml, Rust and Swift (which are all examples to the Hindley–Milner type system), static typings might sound very off from the standard way of JavaScript-ing.

In turns out, that TypeScript can express very complicated types, thanks to its conditional types, literals and generics. In this short post we’re going to explore how to use typed string literals to have a safe interfaces to objects. This approach is the underlying mechanism of wrapping libraries like lodash, ramda and my recent @soundtype/commander and @soundtype/eventemitter, all in a type safe manner.

Stringly-typed

Consider the following JavaScript function:

function prop(obj, name) {
  return obj[name];
}

// Usage:

const user = { firstName: "Gal", lastName: "Schlezinger" };
const firstName = prop(user, "firstName");

The prop function above looks like something we can’t type in a static type system. It takes an object, and then a string, which is the property name, and returns an object. A naive implementation in TypeScript would be probably something like:

function prop(obj: object, name: string): any {
  return obj[name];
}

This is, of course, a very unsafe function. How can we make it better? Let’s look at a simpler function, and try to type it first. We’ll talk about the identity function, that gets an object and returns the same object. Or in JavaScript:

function identity(x) {
  return x;
}

Such a simple function! How would we write it in TypeScript? The naive approach, again, would look something like:

function identity(x: any): any {
  return x;
}

But now, once we use identity(10), we get the any type back. This is not what we want. To ensure we get the same type as we provided, we need to make the function generic. Now, whenever we call the identity function, TypeScript will also provide the type of the argument, whether by inference or explicitly by usage. This is how it looks like:

function identity<T>(x: T): T {
  return x;
}

// by inference
const inferred = identity(10); // number

// explicitly
const explicit = identity<number>(10); // number

So, in conclusion, generics can help us leverage the underlying types whenever for type safety.

How do we use generics in a function like prop? Let’s start by adding a generic to the object we want to take data from:

// This won't compile in strict mode!

function prop<T>(obj: T, name: string): any {
  return obj[name];
}

This implementation won’t compile, because we can’t index an unknown object (just a generic T) over a string. Maybe that’s an array? Also, we don’t know what the result type might be, so this is not good enough. A good utility TypeScript provides us is the way to ask the type of the keys of an object. This is done by using keyof Type, so keyof { hello: number, world: string } would result in the 'hello' | 'world' type, which is a union of 2 string literals.

We can leverage this by using it instead of asking for a string:

function prop<T>(obj: T, name: keyof T): any {
  return obj[name];
}

Now, our function compiles, but we still don’t know what type we will get in return, and as we said before, returning an any is not acceptable.

The cool trick we can do, is to add another generic, that will extend the keyof T, let’s call it Key. Then, we can access the return type by returning T[Key]:

function prop<T, Key extends keyof T>(obj: T, name: Key): T[Key] {
  return obj[name];
}

Now, the function is truly generic, and will work as expected:

prop({ hello: "world", year: 2019 }, "year"); // number
prop({ hello: "world", year: 2019 }, "hello"); // string
prop({ hello: "world", year: 2019 }, "missing"); // compilation error

This assures us we won’t have any runtime undefineds, by letting our compiler be smarter and look for mistakes we might do. This tiny example can be used all over the place to provide great developer experience for library users.

The TypeScript type system also allows recursive types, conditional types and much more awesome shenanigans, we might explore in the future.

fnm: Fast and Simple Node.js Version Manager

Gal Schlezinger — Tue, 12 Feb 2019 16:50:47 +0000

fnm is a very fast Node.js version manager, ~40x faster than NVM. It supports .nvmrc files and Fish shell out of the box. It works on Linux and Mac and distributed as a single executable - and it is open source on GitHub!

So,

Two weeks ago, I had opened a new tab on my terminal and complained in agony: “Oh dear god! Every time I open a new terminal it takes like one second!”. My teammates looked at me funny. “This is clearly sub-optimal and hurts my focus, and I believe it’s NVM’s fault.”

I found it’s NVM that is at fault after I did a search around my .zshrc file, checking which line takes the most time. It was NVM’s initialization. I have been using NVM for years, and I always wanted to write a simple replacement, because my use cases are pretty simple:

I want to be able to download any Node version (like nvm install)
I want to be able to switch between them easily (like nvm use)

These tasks aren’t hard to solve. Node.js binaries are distributed in tarballs on their website, and switching versions shouldn’t be more than just changing a symbolic link around. So, why is NVM so slow?

I thought about writing it as a simple Bash script, just like NVM, but I wanted it to be interesting and fun. Also, not all machines have Bash installed, or there might be problems integrating with Bash. I have used Fish shell for years, and in order to use NVM, I had to use a wrapper that fixes things. It wasn’t easy. Using a real executable, on the other hand, would work on every shell!

The first prototype

My first prototype was a TypeScript app. I packaged it with Zeit’s pkg, making it a self-contained executable, because I didn’t want to have dependency on Node. I wanted it to work on a system without Node installed (so the first version of Node would be installed using fnm!)

Node’s startup time wasn’t good enough for me. Just spawning a “hello world” takes around 200ms, which is good for servers, and for command line utilities that you don’t use frequently, maybe, but some people use nvm on every cd, so their Node version will always be in sync. 200ms penalty for every cd is madness and would make the tool unusable.

So it seems like I need to write it in a language that is compiled (so no dependencies on the host system), and with fast boot time. Four languages came to mind: Go, Rust, Crystal and Reason/OCaml.

A Native Reason App

I chose Reason for many Reasons (hehe), some of them are written in another post. I had used esy and pesy, two awesome packages that make the development workflow for native Reason/OCaml apps easy-peasy for Node.js developers.

esy works like a super-powered yarn: it installs packages from npm or OPAM (OCaml package manager) and stores it in a global cache. It also manages a sandbox for the OCaml runtime/dependencies for you, so different OCaml installations won’t interrupt each other. pesy generates build configurations for Dune, OCaml’s build tool, right from the package.json file.

When using both packages, it feels just like Node development — everything works with a single package.json file, with minimum configurations. It can also help other Node devs, just like it helped me, to contribute to the project, because Reason syntax is very close to JS’, and the toolchain feels very JavaScript-ish.

I had built the first prototype, and tested its performance. I had two test files, one using NVM and one using fnm. Both tests spawned a plain Bash, called the “initialization” of the target (NVM/fnm), and then switched to the Node version specified in .nvmrc file in the directory using the target. I ran it 10 times for each binary, and the results were amazing:

NVM’s test case was around 600ms on my machine
fnm’s test case was around 15ms on my machine

So in that test, on my MacBook Pro, fnm was 40 times faster than NVM. That’s pretty huge, despite not being very scientific.

A real-time animated video is on the repo’s README

Releasing to Public

When I had started working on fnm, I joined the Reason Discord server, and asked some help from people. I found that community is so nice. When I decided to release, I wrote a short message on the #native-development channel and immediately got great feedback, telling me it’s a great idea.

The community aspect is such an important part of JavaScript, and Reason’s community feels even nicer than JS’ — maybe because the community is still small, but it is very welcoming.

I released fnm to GitHub as open source, tweeted about it and went to bed. When I woke up,

My twitter notifications were on fire 🔥
The repo had more than 500 stars 💯💯💯💯💯
fnm was #1 on HackerNews 🏆
No one on Reddit/HackerNews called me an idiot! 🤡 (a rare sight)

That’s a big deal.

What Now?

fnm has some features still missing. Here are only a few things we want to add:

Windows support
Version aliases
Support downloading latest LTS
Per-shell usage
Drop dependency on tar and curl
… and more!

So if you feel like you’re ready to use it and start working faster, or you’re a JS/Reason developer willing to contribute to an open source project, download fnm and join us on GitHub!

Fun with Functors and ReasonML

Gal Schlezinger — Sat, 24 Mar 2018 20:57:20 +0000

Or: Reasonable functional programming with Reason, part 1:
A short introduction to ReasonML types and functor types from a beginner.

I started to learn some functional patterns after reading Brian Lonsdorf’s amazing book “Mostly Adequate Guide to Functional Programming in JavaScript”. This book made me crazy about this new paradigm, that I never learned, and made me want to practice these patterns somewhere.

I found myself using it in my fun projects but never in my real-work projects — it always fell in the “most javascript programmers don’t code like this” territory. My colleagues were right, so I decided to learn a different language. Originally, it was Haskell. I started to learn it, but it was too theoretical (or “academic”) for me: I’m a very practical guy, and I like to be able to use and build software with the paradigms and languages I learn first.

So… for the last couple of days, I’ve been learning Reason.

Reason?

Reason, or ReasonML, is a new syntax of OCaml. It looks more like JavaScript so it is easier to get started with. And the OCaml part doesn’t need to tell you much, other than that you have a big community behind you, in a language that is here for years. OCaml has opam as their package management tool, and the community is active. Check out awesome-ocaml to see some cool stuff from the OCaml community.

What does “a new syntax” mean? Having a new syntax for OCaml is like using CoffeeScript or transpiling newer JS syntax to older JS syntax using Babel — writing in one syntax, then compiling it to another syntax. Reason “compiles” to OCaml, and along with BuckleScript, a tool that compiles OCaml to very efficient JavaScript, you can see the chain: Reason ➡ OCaml ➡ JavaScript.

Both OCaml and Reason have a full sound (and inferred) type system, so 100% of your code is covered with types on compile time. That means fewer bugs. The inference part is amazing too; it means that you don’t have to write the types yourself. The compiler understands your code and does that for you.

For developers coming with Java-like type systems, to type systems like Reason has — note that in Reason, nulls aren’t a thing. You can’t send null as an argument for a function which wants to get a string. It’s just not possible. It’s not that the whole concept of absence isn’t baked into Reason, it is just that you have a special way of doing so. That way is called option.

The `option` type

In Reason, you can declare types as constructors. Constructors can have data in them, but it is not mandatory. Let’s take the option type, for instance, its declaration looks like the following:

type option('a) = None | Some('a)

Woohoo, there’s a lot going on here for first comers. Let’s go over this definition together.

First, we declare a type, called option. Then, there are the type parameters: that 'a thing is called “type parameter” — it is used like Generics or Templates in languages like Java, C++, etc. This is so option can “wrap” many different types: you can have option(int) if you have a nullable integer, or option(string) if you have a nullable string! Type parameters are always prefixed with a tick ('), so you can’t unsee it in examples. You can have more than one type parameter — more on that later.

Then, we say that our type is a union of 2 constructors: None, which receives nothing as data, and Some, which receives data with the type 'a, as the type parameter says.

The built-in option type is the way we handle absence in Reason. In Haskell, it is called Maybe. We always know that we receive an option type, and when we have an option type, we always have to unpack it before we use it. We unpack data with a cool feature called pattern matching:

let greet = (optionalName: option(string)) : string =>
  switch optionalName {
  | Some(name) => "Hello, " ++ name
  | None => "Who are you?"
  };

print_endline(greet(Some("Gal"))); /* prints "Hello, Gal" */ print_endline(greet(None)); /* prints "Who are you?" */

See how I unpack the data with ease. When I get None, I return a string that contains Who are you?. When I get Some with some name in it, I return Hello, ${name}. It may look weird that it actually works like that, but it does! (you can click here to see what it compiles to in the Reason Try page)

Okay okay… an optional type. What is a functor?

Now that we know what is the option type, we can continue from here and use it as our example for the rest of the article.

A functor is a data type that can be mapped. That means that you can call the map function on it. The map function takes a functor and a function. Then, applies the provided function to the functor’s value (unwraps it), and wraps the result with an instance of the functor again.

You may already be familiar with Array#map from ES5: array.map(fn). This is because Array is a functor that has multiple values in it. The provided function is evaluated with every value in the array, and in return, you get a new Array! By the way, in Reason, you don’t call methods on a value — that’s OOP. The way of invoking methods is to invoke a function and pass the value to it:

let increment = x => x + 1;
map(Array[1], increment) /* => Array[2] */

The option type, Just like Array, is a functor too. To understand how it would work let’s split it into its two constructors: Some and None.

What would happen if we map over None? I’d suggest that it should have the same behavior as mapping over an empty array: it should do nothing, it shouldn’t execute the provided function at all — it should just return None. For Some, I’d suggest that it should have the same behavior as mapping over an array with a single value. So the single value will be applied to the function, then be packed again with Some:

let increment = x => x + 1;
map(None, increment); /* => None */
map(Some(1), increment); /* => Some(2) */

Implementing this map function is just a couple lines of code:

let mapOption = (opt, fn) =>
  switch opt {
  | None => None
  | Some(value) => Some(fn(value))
  };

Reason’s amazing type system ensures that fn is a function that receives the provided option value, and returns a new option. The full type declaration for mapOption is:

let mapOption = (opt: option('a), fn: 'a => 'b) : option('b)

Let’s go over it together: we first declare a function called mapOption that receives an argument called opt, with the type of option('a). As we already talked about, 'a is a type parameter, making this function get any type of option. then, we receive a function that receives 'a (the type parameter we had in the opt argument), and returns 'b, which is or isn’t a different type. Then, the function returns option('b), which is the same type as the inner function result type but wrapped in an option.

In other words, we receive an option('a), then we receive a function that transforms a value from type 'a to 'b, and then we return option('b): we support transforming between the inner types, while we’re still in option land:

let stringify = x => string_of_int(x); /* int => string */
mapOption(Some(1), stringify); /* => Some("1") */
mapOption(None, stringify); /* => None */

More functor examples

We can declare another type — the result functor. The result functor will be almost like option, but its negative side will have a value too. You can treat its value as a reason, or error, or just failure. When you return the result functor, you’re basically saying that “this method may fail”. You can use result in validations and for database queries, or for anything whose error is important:

let result('s, 'f) = Success('s) | Failure('f)

The map behavior is almost identical to the optionMap behavior. If we have Success, we will take its data and apply it to the provided function. If we have a Failure, we wouldn’t apply the value to the function, and just leave that Failure as it is. The implementation, again, is a couple lines of code:

let mapResult = (res, fn) =>
  switch res {
  | Failure(failure) => Failure(failure)
  | Success(success) => Success(fn(success))
  };

This data structure helps us build our program as a tree. When we have a problem, we stop applying our logic to it. We basically stop going through the “happy path” until we handle the failure. When we map over Failure, we stay with the same failure we had, so no data transformation will happen once we have a Failure.

In the next article, I’m going to write about Monads, a special case of Functors, that can help you a lot while building data transformations.

Up until then, what are your ideas of custom functors?

Thanks for reading!

“Sign up” and “Sign in” forms could (and should) be the same

Gal Schlezinger — Fri, 05 May 2017 15:35:38 +0000

After reading Omri Lachman's article about hidden “log in” buttons. Suddenly, I understood my frustration with recent web apps. I DONT KNOW HOW TO USE THEM BECAUSE THEY WANT ME TO SIGN UP ALL THE TIME.

I am clearly not a UX designer, but I had an idea: instead of having two forms: one for logging in and one for signing upâ€Š–â€Šwhy can’t we have both on the same form?

Think about it. You can try logging in if you fail to log in because of a password you can retryâ€Š–â€Šbut if you fail because of the email provided? Why can’t you just resume to the registration process?

I built a simple mockup (source code is on GitHub) to show how a simple registration/logging in the process could work in practice: once you provide an email of an actual userâ€Š–â€Šit suggests that you need to sign in. Yes, it has some security vulnerabilities that we probably can solve or can actually care about. We can do that it won’t be automatically: once I clicked the “Continue” button, it will try to log in and if it fails due to unknown emailâ€Š–â€Šwe’ll ask to complete some details to sign up.

You can try it online: https://signme.surge.sh

I like that solution because:

It is very easy to implement (I guess most devs will say this is a joke)
Less place for errorsâ€Š–â€ŠI log in where my credentials fit!

Still, I am not a UX designer, so I would really like to have some you all to say what do you think about this pattern. Thanks!

IFTTT Ideas for Software Development

Gal Schlezinger — Tue, 11 Apr 2017 22:15:43 +0000

Recently, I started to use, or actuallyâ€Š–â€Šmisuse, a service called “If This, Then That” which is written and called mostly IFTTT. Modern tools and applications solve one problem very good, and I like it. The drawback from it is that connectivity is the worst problem we’re facing right now. IFTTT came to the rescue by providing an interface to connect all these services, and I’d like to use it well. However, I have no good use for applets right now. Most of what I tried, actually, annoyed me:

When I like something on Twitter, it creates a new task in a Todoist project called “Liked Tweets”. Because most of the time I’d like to see it later.
When I take a screenshot on my iPhone, it sends it to a Telegram group called “Screenshots”. I thought it’d be cool, but it is super annoying.
When I create a task on Todoist, send it to a Telegram group called “Tasks”.

Bah. That sucks. I really want to use IFTTT, but I need to find a good use. I don’t hold a software engineer role for the next couple of months because I volunteered to command in the tech officer training course. However, lately, I started to think about things I could do with IFTTT when I return to software engineering:

Dev Screenshot => Slack: Whenever I take a screenshot on a test/development phone, send it to a “Screenshots” Slack channel. or a Telegram group. Whatever.
Dev Screenshot => Todoist: Whenever I take a screenshot on a test/development phone, add it as a task on a todo list app, so I would know I have to add it inside a pull-request.
Todo Comment => Todoist: Whenever I push a code with a // TODO comment, create a new task in my todo list app.
Todo Comment => Slack: Whenever I push a code with a Todo comment, send it to a slack channel so people can make fun of me (mention me and ask me to do it already)
Dedicated Mailbox => Telegram: Create a mailbox for reminders, so todo apps/calendars etc can send me notifications through Telegram. (Even though I have the native todo apps and calendars for Mac and iOS.. so it will probably just annoy me too)
Telegram => Facebook Group: Whenever I add some kind of hashtag (let’s say, #fullstack_group), share the message with a dedicated Facebook group.
Calendar + Photos => Some photo management: Whenever I take a photo, check on my calendar if I need to be somewhere. If I do need to be there, add the photo to the calendar meeting or something. I don’t use any photo management tools but it sounds cool.
GitHub/GitLab/BitBucket/Whatever => Todoist: whenever I’m mentioned at GitHub/GitLab, add a todo with the link. Two-way bind GitLab’s Todo’s to the todo list app can work as well.

Let's share applets!

Software developers, artists, musicians, and just everybody: what cool IFTTT applets do you have and use regularly? I’d like to experiment with cool stuff!

I failed toÂ deliver.

Gal Schlezinger — Wed, 18 Jan 2017 18:07:50 +0000

I used to be a development infrastructure team leader. Part of my job, as I decided it to be, was to provide tools for teams to communicate with their customers and provide tools to build better and more relevant software.
The team itself worked like a startup company within the organization. We didn't force people to use any of our solutionsâ€Š–â€Šwe tried to make them thrilled and excited about them, so they would support our products and use them with their own will.

While I had success in some cases, there are couple of failures I still carry with me in my head, and lately I figured out that they all share the same problems.

I workedÂ alone

Most of the time, I worked on these tools for too long, alone. They all began with me starting to hack at night, and evolved to real projects, with no one but myself writing them with me. Although it was very fun to begin with it, working alone on these tools wasn't rewarding because I had no one to be excited as me about the projects.

It taught me that demo time is important. Make time to show your projects to your colleagues. Many team leaders, with me included, had this problem that we haven't asked for a demo. I just didn't wanted to interrupt my employees. Just agree on the demo on a specific time, and make it seven, eight, fifteen minutes long demo.
It can be a fun thing to do, and the team can learn and get inspired from the act.

I had no realÂ users

I always seen myself as the user, when I clearly wasn't. This is a basic rule in UX design: thinking about myself as the user makes me to make wrong assumptions about the tools and the way I solve the problems. Hell, I am sometimes wrong about the problems themselves, without consulting with a real (or another) user. One example is my love for command line utilities and VIM in particular, while other colleagues are terrified by it.

Go out for a walk, think about your problem and characterize your users. Who are they? If they're your coworkers, talk to them. If they are 23 years old bartenders, go to a nice night out with a pen and a piece of paper and just talk to a bartender.

The important thing here is to talk to another human being. Even if you are a future user for the app, you should understand what to address first. Many times we see the big picture and we want to solve it from one end to the otherâ€Š–â€Šbut sometimes providing a really simple and basic tool is enough for start.

Providing a good MVP to your users is the most important thing. It might feel like a simple CRUD application, but it might solve a tiny bit of the problem. The only way to have a good MVP is to understand what HAS to be in the app and what is just NICE TO HAVE for now.

I tried to satisfyÂ others

I showed one of the tools to my boss. The tool was a micro-blogging/blogging/mailing list tool, making teams interact with their customers. My boss took my demo and showed it to some department managers in our organization. They loved it, and asked for a couple of features. One of the features, was to create a “secret” mailing list, changing the solution surface and actually changing the problem that the tool solved.

I just needed to say “no”. However, I'm not used to it, and I really hate to be a no-man, since I really believe in making people happy. Because I had no “real users” either, I thought that my vote doesn't count.

You can't satisfy everyone, so most of the time, you better satisfy yourself.

Now, I know what the vision of the tool should have been: “Open communication between teams and their customers”. Providing this specific vision could make these department managers understand what the tool is for and what it isn't for.
Making sure you address the right problems is an important part of your application. This way you can measure yourself against your competitors and have some agenda why you provide a better tool. You can also get more customers this way, and have people believe in your way, and make FANS for your software. Which is pretty damn wicked.

I was more excited about the code than theÂ product

I saved this one for last. Not that long ago, I worked on a kind-of a Medium clone. In this project, I used Draft.js for the first time, and spent most of the time trying to add images with drag and drop and making a great user experience. I actually wrote an article about Composable SQL in JavaScript while working on this project because I was so thrilled about the way I queried the database.

I'll say it again. I was thrilled about the way I queried the database. I was thrilled how I queried a SQL database, I used for years with Rails, PHP and even plain ASP.

You can't say it's a bad thing, because it is the opposite. Yet the fact that I tried to implement the things I read on Brian Lonsdorf's (drboolean) awesome and life-changing book about JavaScript made me put so much time and effort on the way my code looks and acts. This is awesome for a side project or just testing a feature inside your project, but it should not slow you down in a real project.

If the only thing that excites you in a project is how you write it, well, let me tell you something, the product won't be as good as your code. Try to be a boring programmer. Make decisions about your product and not about your code. Remember that you have to deliver a product. Your users probably don't care about your functional programming skills as long as your product works. They just want to use it.

So,

Is jQuery enough for this app or you should use React? Just build the damn thing, show it to your coworkers and give it to your real users already. That's how you deliver, and that's what you're paid to do basically. ðŸ’°