Antoine Lehurt

What cheap code solves

Sat, 11 Apr 2026 00:00:00 GMT

A few months ago I built a coffee tracker. Not because I desperately needed one. I'd been using an off-the-shelf app and it was fine. It did the job. It just wasn't tuned for how I actually use it, and it came with a pile of features I never touched.

This time I could build exactly what I wanted. A few hours with an AI agent, and the thing worked the way I'd always wanted it to. Two years ago this project dies on the second weekend. The gap between what's in my head and what's on screen is still too wide, and the motivation is already gone.

I have a graveyard of those.

AI coding agents collapsed the friction that used to kill that kind of software. I've been rebuilding a small ecosystem of tools around how I actually work, capture, reading, tracking.

Personal software is where the shift feels most obvious. I already know the user and the workflow. I don't need research, alignment, or buy-in. I just need to turn a private annoyance into a working tool before I lose interest. That's why more of these things become worth making.

Internal software is different. Cheap code helps there too, but mostly when the hard parts are already settled. The users are known. The workflow is visible. The data already exists, usually scattered across a few systems and one cursed spreadsheet. The work is in the last mile, building the layer that makes an existing workflow less painful.

I've seen that at work. Support teams have used Lovable to build tools on top of data they already had access to. Engineering still mattered, and so did the underlying constraints. What got cheaper was the last mile, the workflow layer that turned existing data into something actually useful. It also meant they didn't need to wait for engineering to prioritize that exact layer for them.

That is real leverage. It works because the coordination problem is already mostly solved.

Cheap code helps most where usefulness can outrun rough edges. A personal tool can be messy and still earn its keep. A workflow layer inside a team can too. Customer-facing products are different.

This is where the cheap-code story starts to thin out. You still need a problem enough people care about, and you still need them to switch and stay.

Cheap code helps most once you already have a hypothesis. It makes exploration cheaper, and it makes early validation easier because you can put a rough version in front of people fast. You can learn with something real instead of a doc or a mockup. But the later questions still wait for you: adoption, trust, and long-term complexity.

That's why The Hacker News tarpit lands so hard. JA Westenberg cloned Hacker News in a few hours. On the surface it looks simple: links, votes, comments, accounts. But nobody is going to use that clone, because Hacker News is not mainly a bundle of features. It's audience, norms, moderation, status, and habit layered on top of ordinary software.

Hacker News is an extreme case. The mechanism isn't.

When you're building for strangers, the hard part is getting into somebody else's life. You have to reach people, earn enough trust for them to try the thing, and give them a reason to change habits they already have.

That also changes the kind of discipline software demands. When adding something gets cheap, bloat becomes the default failure mode. Features pile up because they're easy to ship, not because they make the product sharper. Maintenance may get cheaper too, at least for a while. Complexity doesn't. It compounds.

And compounding complexity is exactly where both humans and agents start to lose the map. Shipping gets easier faster than understanding does. Humans were never great at holding a full model of a growing system in their heads, and I don't see much reason to believe agents have solved that problem either. If anything, they make it easier to defer the understanding until the system is already harder to reason about.

Maybe that's the real change. Cheap code doesn't make software simple. It makes more software worth attempting.

Personal tools, rough prototypes, and narrow internal layers can survive with rough edges because usefulness outruns polish. Customer-facing products live under a different gravity. Trust, habit, coordination, and complexity catch up fast.

Getting to a working thing is cheaper now. The harder part begins when other people have to trust it, use it, and keep depending on it.

The craft was never the typing

Mon, 06 Apr 2026 00:00:00 GMT

I've been chasing better code since I started programming. Every review, every refactor, every late realization that last month's approach was wrong, that was the craft. An infinite loop of learning, and I was always hungry for the next iteration.

Then an agent started writing code that looked a lot like mine. At first, it wasn't good enough. The output was close but not something I'd ship, and I spent more time fixing than I would have writing it myself.

But the models got better. Opus 4 was a real jump. I started delegating the coding part entirely, and for a while it felt like I'd just gotten faster. Then the review cycles started piling up. Back and forth, back and forth. The agent wasn't wrong exactly, it just wasn't making the choices I would have made, because I hadn't told it to.

That's when the work shifted. I started planning more deliberately than I ever had when the code came from my own hands, spelling out architecture and tradeoffs and exactly how something should feel to use. Decisions I used to make silently while typing, from instinct. The agent can't work from instinct. It needs that precision. And putting it down, finding the words for what I used to just know, that was a skill I'd never needed before.

I was never just writing software. Nobody using it cares who typed it.

I was building something for a person, inside the constraints of a business, and the code was one tool I reached for among several. A tool I still care about (I'd be lying if I said otherwise), but never the whole job.

I'm still chasing better code. I just don't type it anymore.

The map coding left behind

Mon, 06 Apr 2026 00:00:00 GMT

A year ago, I started delegating most of my coding to AI agents. The longer I worked that way, the less confident I felt in what I shipped.

The features I'd built by hand years ago, I could still trace end to end: the data flows, the edge cases, why we'd picked one approach over another. But anything new, anything where the agent did the building and I did the reviewing, felt different. I'd planned thoroughly, researched with the agent, and approved every line. My mental model felt thinner than it used to be.

I kept asking myself why I trusted what I shipped when I wrote the code myself. It was what coding left behind: a map of how everything connected. The product, the domain, the system I was building inside of.

For most of my career, coding was how I built that map. Every choice I made while writing code added to it. Fitting a new feature into the existing architecture, keeping things maintainable, leaving the code in better shape than I found it. None of those choices were free. Each one cost attention, and that attention became understanding. I couldn't shape something I didn't grasp.

I've always shared the map with others. Every engineer does. The colleague who owns the payments service has their own map of that territory, worn in over months of working in the code. When they tell me how it really behaves (not how the docs say it does), I'm borrowing a piece of theirs to fill a gap in mine.

AI agents offer something that feels similar. I describe what I want, the agent produces something close to what I would've written. But the agent's map is disposable, built from scratch every session and thrown away at the end. It doesn't know where the gaps are.

Some things I can hand off without losing much. The boilerplate, the patterns I've written a hundred times. I can read those and know what I'm looking at. But the domain, the business logic, the shape of the system. An agent I don't fully trust can't give me that.

I used to go deep into the foundations of our systems, beyond the feature I was building, down to the code it sat on top of. That's how I learned to trust what I shipped.

Maybe the answer is building the map earlier. I've started planning differently with the agent. More than the feature details. The architecture, the boundaries, how everything connects. In unfamiliar territory, I dive into the code myself first. By the time the agent writes code, I know the territory. I still review what it produces, but that's not where I expect to catch gaps anymore.

I'm still iterating on the process. But I need the map before I can trust what I'm building.

Integrating AI into my workflow

Tue, 22 Aug 2023 00:00:00 GMT

Earlier this year I joined Sana and opened the backend codebase. It was written entirely in Kotlin. I'd never written a line of it. The frontend was TypeScript, which I knew well, but the backend was a different world. The syntax looked close enough to Java (which I'd worked with at Spotify a few years prior) that I could squint and follow the shape of things, but the idioms were foreign. Extension functions, data classes, scope functions like let and apply chained in ways I couldn't parse on first read.

My instinct was to open the Kotlin docs, find a tutorial, maybe skim a "Kotlin for Java developers" guide. Instead, I pasted a block of code into GPT and typed: "Explain what this does, line by line."

It worked.

Not perfectly. Not every time. But well enough that I kept doing it. I'd write a function, paste it in, and ask: "Is this idiomatic Kotlin, or am I just writing TypeScript with different punctuation?" GPT would come back with suggestions (use also here, replace this if chain with a when expression, this whole block can collapse into a single let call) and I'd rewrite, paste again, ask again. A feedback loop that felt less like reading documentation and more like pair programming with someone who never gets impatient.

I'd tried ChatGPT before this. Asked it to generate code, got back something that looked plausible but wasn't usable. Didn't see the point over just writing it myself. But learning Kotlin was different. I wasn't asking GPT to write code for me. I was asking it to explain code I was already looking at, to critique code I'd already written. I had something specific to push against, and that changed everything. I ran it through Raycast AI (powered by GPT-4), a tool I already used daily that had just shipped their AI features.

It's a rubber duck that talks back.

I don't mean that dismissively. Rubber duck debugging works because the act of explaining your problem forces you to think clearly about it. GPT does that, but it also responds, and the response doesn't have to be brilliant. It just has to be close enough to give you something to push against. You paste an ugly function, it offers a cleaner version, you spot what it missed, and now you understand the code better than if you'd just stared at it.

Refactoring is where this hits hardest. You're working in an existing codebase, you find a function that grew ugly over six months of patches, and you need to clean it up without breaking anything. That's grunt work. The kind of task where having a second pair of eyes (even artificial ones) saves real time. I paste the function, ask for a refactored version, and use the output as a starting point. "Sometimes maybe good, sometimes maybe shit." When it's off, I start over, explain what I'm actually trying to do, paste again. GPT has the biggest patience in the world. It doesn't care if I ask the same question five different ways. It just keeps answering.

And then there are TypeScript errors. Anyone who's worked with complex TypeScript generics knows the feeling. The compiler spits out a type error four lines long, nested three levels deep, referencing types you didn't write. I used to squint at those for minutes, mentally unpacking each layer. Now I paste them into GPT and get back a plain-language explanation of what's actually mismatched.

But none of this works if you can't tell when it's wrong. GPT hallucinates. It invents plausible Kotlin APIs that don't exist. It suggests TypeScript patterns that compile but introduce subtle bugs. It rewrites your function and quietly drops an edge case. You need to know enough to catch that, to read the suggestion and feel the thing that's off before you run it.

I still write Kotlin every day. I can write decent code now, but I still need a reviewer (a colleague, or increasingly, an AI) to catch the things I miss, to push it from functional to idiomatic. GPT didn't teach me Kotlin. But it compressed the awkward early phase (the phase where everything takes three times as long because you're translating in your head) into something shorter and less painful. I'll take that.

Newsletter to RSS feed

Fri, 21 Jul 2023 00:00:00 GMT

Earlier this year, I shifted back to RSS feeds for my news consumption. However, one common challenge I encountered was the lack of RSS feeds support from newsletters.

While some RSS readers, like Inoreader, offer the option to receive newsletters within the app, my preferred apps, Reeder on MacOS and iPhone, don't provide that support. Luckily, I discovered a solution called Kill the Newsletter. This service allows users to create a dedicated email address for each newsletter, automatically generating an RSS feed that can be easily subscribed to. Easy to use and straight to the point. I love it!

Managing multiple Git configurations with [includeIf]

Thu, 11 May 2023 00:00:00 GMT

I often need to juggle between different Git settings depending on the type of project. For instance, I need to use a different email address and signing key when committing. Luckily, Git has a feature called [includeIf] that helps me manage multiple Git configurations with ease.

For example, I store my work projects in ~/workspaces/work and my personal projects in ~/workspaces/personal. In my ~/.gitconfig, I added the following [includeIf] statements:

[includeIf "gitdir:~/workspaces/work/"]
  path = ~/.config/git/work-config

[includeIf "gitdir:~/workspaces/personal/"]
  path = ~/.config/git/personal-config

# ...all other Git settings

This tells Git to include the configuration file at the specified path when I'm working in the matching directory.

For example, in ~/.config/git/personal-config, I set my GitHub email address and signing key:

[user]
  email = kewah@users.noreply.github.com
  signingkey = ssh-ed25519 AAAAweriaksjldhfkjasbvlkasbv

Now, when I'm working in the ~/workspaces/personal directory, Git automatically uses the [user] settings in ~/.config/git/personal-config.

Setting up Vercel Analytics in an Astro project

Wed, 19 Apr 2023 00:00:00 GMT

I have recently migrated my website to host it on Vercel. I was interested in experimenting with the analytics service that tracks Web Vitals. It's not crucial for this lightweight static website—it even adds a JavaScript script—but I wanted to see what data we get from it.

It was straightforward to set up following the Astro documentation page:

Install the dependency

pnpm add @astrojs/vercel

Update the astro.config.mjs

import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/static';

export default defineConfig({
  output: 'static',
  adapter: vercel({ analytics: true }),
});

Enable Vercel Analytics in the project in the Vercel interface
Deploy and profit!

Well, not yet for me—I got the error [Analytics] VERCEL_ANALYTICS_ID not found in the dev tools console.

When running the build command, the line const analyticsId = import.meta.env.PUBLIC_VERCEL_ANALYTICS_ID got minified to e={}.PUBLIC_VERCEL_ANALYTICS_ID. To fix it, I needed define the custom variable in the astro.config.mjs to replace it with process.env.VERCEL_ANALYTICS_ID env var passed by Vercel on build time.

import vercel from '@astrojs/vercel/static';
import { defineConfig } from 'astro/config';

export default defineConfig({
  output: 'static',
  adapter: vercel({ analytics: true }),
  vite: {
    define: {
      'import.meta.env.PUBLIC_VERCEL_ANALYTICS_ID': JSON.stringify(process.env.VERCEL_ANALYTICS_ID),
    },
  },
});

Alright, now it works!

Back to RSS

Fri, 06 Jan 2023 00:00:00 GMT

Following the recent events at Twitter, I've chosen to delete all my content and discontinue using the platform. However, I haven't been able to fully delete my account yet. Nevertheless, I still feel nostalgic about what Twitter once symbolized. It played a vital role in my online journey for more than ten years, enabling me to connect with fellow developers and establish communities.

Now, with a compelling reason to curb my Twitter dependency, I find myself at an opportune moment to reevaluate my information consumption and sharing habits.

Over time, I've grown increasingly vigilant about how products manage my data. Gradually, I've migrated towards services that prioritize privacy, such as Fastmail and DuckDuckGo, and more recently, local-first applications like LogSeq.

The decentralized social media space is evolving rapidly with new protocols and services being announced. Mastodon is currently receiving the most attention. I've started using it again (my fourth attempt) as more people I follow on Twitter are active there. However, I don't want to settle for it—I want to focus my attention and effort on returning to RSS feeds.

RSS strikes the right balance of decentralization for me. It enables individuals to host their content wherever they prefer, ensuring control over ownership. All that's required is to expose an XML file. The rest is in our hands—we can construct everything ourselves or employ services to assist us with publishing. While it might not be the most efficient format for discovery, it has demonstrated its reliability and currently powers the podcasting industry (despite Spotify's attempts to monopolize it with their walled garden).

I'm confident that RSS will satisfy my need to stay current and learn from other professionals in the web industry. I've added all my favorite blogs to Reeder and subscribed to various link aggregators' newsletters[^1] with an RSS feed to uncover new content and broaden my horizons.

It seems like we're entering a new era of social media, and I'm excited to see its evolution. Meanwhile, I've returned to using RSS.

[^1]: Hackernewsletter daily, Programming digest, Performance newsletter, React digest, and TypeScript weekly.

Engineers need to write well

Sun, 19 Dec 2021 00:00:00 GMT

In a remote-first company like Acast, written communication is an essential skill to master at any level—from IC1 to CEO. We write Shortcut tickets, Slack messages, commit messages, PR reviews, or feedback throughout the day. Our work won't be leveraged or impactful if we can't share ideas, arguments, or information. When we can't communicate clearly, our value in a team is drastically diminished. As we move to senior roles, it becomes critical.

Taking the time to write

There is no rush. No one is expected to respond within a minute. In the same way, when we refactor while coding, we can take the time to review what we are writing. Remember that while we write something once, a variety of people will see it many times. Making sure that the context is understood and that the message is focused on the subject is vital. Like code, we want to share our box model with the next person reading it. Readers must switch contexts from what they were doing to read a message, which requires a lot of energy. Our goal is to reduce that effort. Although it's more work, it'll be easier for people to provide feedback and build ideas on top.

Writing for thinking

Connecting ideas or developing arguments can be tricky on the first try. We may even have more questions than we did when we started. However, writing clarifies our thoughts, helping us explain them more easily. An excellent quote from Leslie Lamport challenged my view in the past.

If you think without writing, you only think you're thinking.

It's a long journey. It will take an active effort to think about what we write, but we need to practice every day to improve. The goal is not to be a novelist. However, we can still use relevant tips to improve our communication at work every day.

The following resources help me improve my writing:

On writing well by William Zinsser.
If you prefer a shorter version, Julian Shapiro condensed a lot of information in the writing well handbook.
He is also active on Twitter and often shares threads that extract notes from his handbook. For instance, "How to rewrite bad writing"
Finally, I heavily use Grammarly. They have helpful suggestions and correction algorithms.

CDK pattern – Caching static assets with AWS S3 and CloudFront

Fri, 30 Jul 2021 00:00:00 GMT

The code below is a pattern for client-side applications or for serving static files. We want to serve files through a CDN and cache them for an extended period.

In the AWS ecosystem, we need to store the files in S3 and set the cache-control header to tell the CloudFront distribution how long it should cache the file.

It’s recommended to include a hash in the filename, for instance, using [contenthash] in webpack, so we only update changed files and prevent locking the user in an old version.

import * as acm from '@aws-cdk/aws-certificatemanager';
import * as cloudfront from '@aws-cdk/aws-cloudfront';
import * as iam from '@aws-cdk/aws-iam';
import * as route53 from '@aws-cdk/aws-route53';
import * as targets from '@aws-cdk/aws-route53-targets';
import * as s3 from '@aws-cdk/aws-s3';
import * as s3Deploy from '@aws-cdk/aws-s3-deployment';
import { CacheControl } from '@aws-cdk/aws-s3-deployment';
import * as cdk from '@aws-cdk/core';
import { Duration } from '@aws-cdk/core';
import config from 'config';

export class StaticFilesStack extends cdk.Stack {
  constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const cdnDomain = config.get('domain');
    new cdk.CfnOutput(this, 'Site', { value: `https://${cdnDomain}` });

    const cloudfrontOAI = new cloudfront.OriginAccessIdentity(this, 'cloudfront-OAI', {
      comment: `OAI for ${cdnDomain}`,
    });

    const siteBucket = new s3.Bucket(this, 'SiteBucket', {
      // We only allow traffic to the bucket through CloudFront.
      publicReadAccess: false,
      blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
      websiteIndexDocument: 'index.html',
      websiteErrorDocument: 'index.html',
    });

    // Grant access to CloudFront.
    siteBucket.addToResourcePolicy(
      new iam.PolicyStatement({
        actions: ['s3:GetObject'],
        resources: [siteBucket.arnForObjects('*')],
        principals: [
          new iam.CanonicalUserPrincipal(cloudfrontOAI.cloudFrontOriginAccessIdentityS3CanonicalUserId),
        ],
      })
    );
    new cdk.CfnOutput(this, 'Bucket', { value: siteBucket.bucketName });

    const hostedZone = route53.HostedZone.fromLookup(this, 'hostedZone', {
      domainName: config.get('domainZone'),
    });

    const certificate = acm.Certificate.fromCertificateArn(this, 'Certificate', config.get('certificate'));

    const distribution = new cloudfront.CloudFrontWebDistribution(this, 'SiteDistribution', {
      viewerCertificate: cloudfront.ViewerCertificate.fromAcmCertificate(certificate, {
        aliases: [cdnDomain],
      }),
      viewerProtocolPolicy: cloudfront.ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
      originConfigs: [
        {
          s3OriginSource: {
            s3BucketSource: siteBucket,
            originAccessIdentity: cloudfrontOAI,
          },
          behaviors: [{ isDefaultBehavior: true }],
        },
      ],
    });
    new cdk.CfnOutput(this, 'CloudFrontUrl', {
      value: `https://${distribution.distributionDomainName}`,
    });

    new route53.ARecord(this, 'SiteAliasRecord', {
      recordName: cdnDomain,
      target: route53.RecordTarget.fromAlias(new targets.CloudFrontTarget(distribution)),
      zone: hostedZone,
    });

    // We set the long cache-control header for all files except the index.html.
    new s3Deploy.BucketDeployment(this, 'BucketDeploymentWithCache', {
      sources: [
        // `dist` is the webpack output folder.
        s3Deploy.Source.asset('dist', { exclude: ['index.html'] }),
      ],
      destinationBucket: siteBucket,
      distribution,
      distributionPaths: ['/*'],
      cacheControl: [
        CacheControl.setPublic(),
        CacheControl.maxAge(cdk.Duration.days(365)),
        CacheControl.fromString('immutable'),
      ],
      prune: false,
    });

    // Set the short cache-control header for the index.html.
    // In this example I put the cache to 0 seconds, but you should adapt it to your needs.
    new s3Deploy.BucketDeployment(this, 'BucketDeploymentNoCache', {
      sources: [
        s3Deploy.Source.asset('dist', {
          exclude: ['*', '!index.html'],
        }),
      ],
      destinationBucket: siteBucket,
      distribution,
      distributionPaths: ['/*'],
      cacheControl: [
        CacheControl.setPublic(),
        CacheControl.maxAge(cdk.Duration.seconds(0)),
        CacheControl.sMaxAge(cdk.Duration.seconds(0)),
      ],
      prune: false,
    });
  }
}

Once the stack is deployed, we can check the response header contains the correct values and hit the cache.

HTTP/2 200 OK
content-type: application/javascript
date: Fri, 30 Jul 2021 16:56:43 GMT
last-modified: Fri, 30 Jul 2021 16:56:40 GMT
etag: W/"12345"
// highlight-start
cache-control: public, max-age=31536000, immutable
// highlight-end
server: AmazonS3
content-encoding: gzip
vary: Accept-Encoding
// highlight-start
x-cache: Hit from cloudfront
// highlight-end

Using Lighthouse, we can also verify that we don’t get any warning related to “serving static assets with an efficient cache policy.”

AWS CloudFront Functions

Fri, 14 May 2021 00:00:00 GMT

AWS recently released CloudFront Functions—a new serverless scripting platform that allows us to run lightweight JavaScript code at the CloudFront edge locations. These new functions are designed for low latency web request customization.

What's the difference with Lambda@Edge?

CloudFront Functions and Lambda@Edge are both triggered by events generated by CloudFront. But, CloudFront Functions sit in front of the CloudFront cache. The functions are executed on every request or every response—that's why CloudFront Functions need to run under 1ms. In comparison, a Lambda sits between the CloudFront cache and the origin, so it's executed only when the cache is not valid.

— Source

AWS built the CloudFront Functions to address scaling and performance issues that we could face with Lambda@Edge. For instance, cold starts would impact the performance for doing token authorization. Or, in the case of high traffic spikes, we would be limited by lambda throttling or concurrency. With CloudFront Functions, no matter how many requests we get, it will scale indefinitely to match the traffic.

— Source

When to use CloudFront Functions?

If we need to rewrite (i.e., AB flag), redirect, authorize (i.e., JWT token) a request, we should consider using a CloudFront Function.

If we need to do heavier computing, like server-side rendering, or data aggregation/transformation that wouldn't fit the performance budget, we should use a Lambda@Edge.

Resources:

AWS announcement article: Introducing CloudFront Functions
AWS Tech podcast episode: CloudFront Functions Edge Computing Special

API Gateway-first approach

Thu, 25 Feb 2021 00:00:00 GMT

The "API Gateway-first approach" is the idea that, in the context of an AWS cloud stack, when we build a new service, we first consider using API Gateway. If it doesn't fit our use case, we can consider something else, such as a load balancer in front of a Node.js server running on Fargate.

API gateway is a powerful service and by far my favorite of the AWS ecosystem. It is the glue that connects a web request to another AWS service—like Lambda or DynamoDB—which gives us the ability to take granular design decisions for each endpoint of our service. It helps us define strict boundaries in our code to leave the orchestration code out of our business logic code—handled in a Lambda, for example.

If you are used to building Node.js microservices, you can see API Gateway as the combination of a load balancer and a routing system (express router or koa router).

What I like about API Gateway:

AWS fully manages it, so we don't need to handle its availability, and we can set it up using CloudFormation (CDK).
We can collocate different stacks under the same domain. For instance, we can run a React application (Fargate) alongside a REST API (Lambda + DynamoDB). That allows us to choose different solutions depending on the endpoint's need. Therefore it will be easier to maintain the service over time because we can replace components separately. It is worth noting that API Gateway can proxy to different types of AWS services, so we don't necessarily need to use a Lambda. A rule of thumbs is that if the Lambda is only responsible for passing data from one service to another, it's a sign that we can use an API Gateway integration. For instance, we can directly map a request coming through API Gateway to DynamoDB using mapping templates.
We can scale at the endpoint level instead of at the service level. However, like any serverless service, we can't scale indefinitely—we need to consider the API Gateway request per second limit and concurrency burst limit.
We can grant different permissions for each endpoint to reduce the blast radius if the service is compromised (following the least privilege principle).
It's the perfect candidate to apply the strangler pattern for migrating a legacy application to a new stack. When we start the migration, API Gateway will proxy all queries to the legacy service. Piece by piece, we can migrate each endpoint individually to point to a new integration.
There is integrated support with CloudFront (for caching and running our service at the edge) and CloudWatch (to track errors and other metrics), so it is easier to set up, and we have less boilerplate code.

However, API Gateway is not a silver bullet and has some limitations. Remember that it is a "first approach," not an "only approach." Drawbacks of API Gateway:

It connects different services with their limitation (API throttling, timeout, etc.), impacting performances or leading to failure. When designing a system, we also need to take them into account.
Since each endpoint can be a different integration, it makes testing more challenging. For instance, if we use API Gateway + DynamoDB we cannot run it locally. We need to deploy a test stack against which we run our tests (end-to-end tests). It gets slow to run on a CI because deploying and destroying a stack takes several minutes. Some solutions, like LocalStack, can mock different AWS services locally, which will reduce the time to run the tests, but we lose the benefits of testing against the real environment.
The possibility to use a mapping template to transform the data from API Gateway to another service is excellent in theory. Because it removes the need to build and monitor another Lambda, and we leave it to AWS to fully handle the transaction. However, the template language can be tricky to use and debug. Since we are writing a string, our editor has no support to help us figure out what data we're handling. The only source of information is the documentation page. So, the learning curve can be steep, and depending on your needs, it might be simpler to use a Lambda.

Next time you start to build a new service before jumping on Node.js, Express, and Docker, think about it, can you use API Gateway instead?

Speed up your CircleCI pipeline by using the RAM disk

Thu, 21 Jan 2021 00:00:00 GMT

During a presentation—held internally at Acast by my colleague Daniel Grefberg—I discovered a one-line change that reduced by 2 minutes the execution time of my current project's CI pipeline.

- working_directory: ~/my-project-name
+ working_directory: /mnt/ramdisk/my-project-name

CircleCI allows us to mount the project on the RAM disk and use it as a "temporary file storage paradigm." That means, when caching a project's dependencies, CircleCI will use the RAM disk instead of the disk drive.

When working on a Node.js project, it is common to cache the node_modules folder. It allows us to re-use it in the other jobs to avoid running the install command every time. On paper, that should be faster than running npm ci (or yarn install --frozen-lockfile) for each job, but that's not necessarily the case. It usually takes ~2 minutes to restore the cache of ~400MB. This time is mainly taken for decompressing the thousands of files from the folder on the disk. But, this step gets down to ~20 seconds by moving it to the RAM disk.

This change is a quick win to save a few minutes for running our pipeline. The only drawback is that we are limited to the RAM capacity—defined by the job's resource_class attribute. By default, it runs on a 4GB RAM (medium resource class), so depending on our project and the dependencies' size, we might need to increase the resource class.

version: 2.1

aliases:
  - &default_image
    working_directory: /mnt/ramdisk/my-project
    docker:
      - image: cimg/node:12.20

  - &cache_key v1-cache-{{checksum ".circleci/config.yml"}}-{{checksum
    "yarn.lock"}}
  - &restore_cache
    restore_cache:
      keys:
        - *cache_key

jobs:
  initialize:
    <<: *default_image
    steps:
      - checkout
      - *restore_cache
      - run: yarn install --frozen-lockfile
      - save_cache:
          name: Save cache
          key: *cache_key
          paths:
            - node_modules

  test_unit:
    <<: *default_image
    steps:
      - checkout
      - *restore_cache
      - run: yarn test:unit --maxWorkers=2

Write more, but shorter

Sun, 17 Jan 2021 00:00:00 GMT

I recently stumbled upon an article from Mike Crittenden, Write 5x more but write 5x less, in which he shortly explains why we should write more, but shorter.

It’s a concept that resonates a lot with me. Since I started to follow the Zettelkasten method for taking notes, it became clear that I must write to have clearer thoughts. It helps me to be sure that I understand a concept by explaining it. By using the notes I create, I also aim to publish more articles on my website. That’s a great way to feel accountable and push me to be as straightforward as possible because someone else could read it.

By writing more, I'll articulate better my thinking and sharpen my writing skill over time. It's even more critical now that I work remotely and that most of my communication with my team is done by writing. It will also feel more natural for me to write things down because I will build the habit of writing. (By building habits, we don't rely on motivation to do something.)

By writing shorter content, I'll reduce my expectation on how long an article should be before publishing it. It's also a great exercise to briefly explain an idea or concept to make the content more digestible.

After the "keep it simple" in programming, the "keep it short" for writing.

Roam is my space for organized chaos

Sat, 02 Jan 2021 00:00:00 GMT

<span class="intro"> For the past six months, I have been using <a href="https://roamresearch.com">Roam</a> as my primary application for note-taking and knowledge management. This article will share what drove me to start using Roam and what made me stick to it. </span>

My road to Roam

From my interest and work, I read many articles, books or listen to podcasts. But, apart from highlighting some quotes, I didn't extract much of it. Moreover, I struggled to remember where I could find the information afterward.

At the end of 2019, I stumbled upon the Zettelkasten method while reading the book How to Take Smart Notes. This method aims to write one idea per note and organize them using a keyword index to link them together. The goal is to synthesize what we learn for improving retention of information and connect ideas that could, in the first place, look unrelated.

Multiple members of the Zettelkasten's community, including Sönke Ahrens, advised using Roam for implementing the method. So, I decided to give it a try and experiment with it.

Connecting the dots

Roam has a different approach than other applications that I used in the past—Evernote, Apple Notes, and Notion—because It doesn't have a file or folder system. It only has pages that can be linked together using hyperlinks. One of Roam's significant features is that linking is bidirectional; when adding a link from a page, it will create a backlink reference on the other page.

Example of a backlink in my page Maggie Appleton

The backlink system reminds me of how I use my text editor for inspecting a codebase to build the program's mental model or part of it. I mentally visualize a program as a graph—I go to different nodes by following where a function is implemented or checking where a function is referenced. The linking system in Roam allows me to do that in my notes. I can navigate to a page by following the hyperlink or find where I reference it by looking at the bottom of the page where Roam put the linked references.

Another key part of Roam is its blocks (they are like bullet points that compose a page). For me, that's where Roam's power lies compared to other applications. It assigns a unique ID to each block, so we can link them together or even embed them in different pages. Thus we can be more granular when linking ideas, quotes, or notes and put them in a different context.

At first, I created a new page for each note to follow the Principle of Atomicity. But, with the blocks, I can also apply this principle at their level. Now, most of my writing happens in the daily notes pages; I create pages for keywords to reference the content or my evergreen notes. The mix of backlinks and block references removed a lot of friction as I don't need to overthink where a note should live. I know that I'll be able to find it when searching for it using specific keywords.

Screenshot of a daily note page containing reference notes

The needle in a haystack

The keywords are a central part of my workflow in Roam. I avoid using a metadata section where I will put down a list of tags. I prefer the verbosity of writing a sentence about why this note is related to a term. It brings more context that will help me identify if I need this specific note. I find the tagging system too disconnected from the content; it takes more time and energy to figure out what this note is about to tag and evaluate.

To find content in Roam, we can either use backlink reference, the search bar or use the query feature. Queries give us the possibility to ask Roam to surface all content that contains links to a given page. Their significant advantage is that we embed them in our pages so that they won't disappear—unlike with the search bar—and they can live next to our contents. This feature is handy when we need to gather the references for an article or, for instance, if we want to have a page where we can find overdue tasks.

Example of a query to gather notes for the article.

If you are interested to learn more about Roam's queries, I recommend watching the video made by Rob Haisfield. It covers the different operators, use cases, and workarounds that you might need to improve the search results. The syntax might be a bit unsettling at first glance, but after one or two queries written, it quickly became my go-to search feature.

My messy room

Roam is my space for organized chaos: it's not pretty, it doesn't look ordered for someone else than me, but I have the confidence that I'll find and won't lose anything in there. And that's something I have struggled with in the past with other applications.

Relying only on links and blocks brings a lot of flexibility. It allows me to change the structure over time without spending countless hours moving things around. From the beginning, my goal was to use it as a knowledge management tool. Although I recently started to follow the interstitial journaling workflow. It combines my note-taking, task management, and time tracking from the daily notes. That will be an excellent way to expand my use case and experiment with managing my day in Roam.

Roam is still rough on the edge, but I like how the team behind it experiments with new features. They also provide the possibility to inject JavaScript scripts and override CSS in the application, so it opens many options to improve the UX in a hacky way. I look forward to seeing how Roam will continue evolving. I can't wait for the team to release a public API and see how the community could enhance the experience.

CDK pattern – API Gateway caching

Fri, 05 Jun 2020 00:00:00 GMT

API Gateway has built-in support for caching endpoint’s responses. So, we don’t have to set up CloudFront by ourselves.

Enable API Gateway caching

To enable caching, we need to use an edge optimized endpoint and set some values on the deployOptions.

const api = new apigateway.RestApi(this, id, {
  domainName: {
    endpointType: apigateway.EndpointType.EDGE,
  },
  deployOptions: {
    cachingEnabled: true,
    cacheClusterEnabled: true,
    cacheTtl: cdk.Duration.minutes(30),
  },
});

Note that if we need to use a custom domain for our API the certificate needs to be in the us-east-1.

To use an ACM certificate with an API Gateway edge-optimized custom domain name, you must request or import the certificate in the us-east-1 Region (US East (N. Virginia)). To enable caching with need to use an edge optimized endpoint.

We can now query our endpoint and check CloudWatch to check that we are hitting the cache.

Query string support

That works great until we start to use query strings. For instance, if we build an OEmbed API, we need to support url and format query strings. With the current setup, we will always get the same cached response when hitting the endpoint even if we change the url value.

To fix that, we need to set up the request parameters to take the query strings into account.

const integration = new apigateway.LambdaIntegration(lambda, {
  cacheKeyParameters: ['method.request.path.url', 'method.request.path.format'],
  requestParameters: {
    'integration.request.path.url': 'method.request.path.url',
    'integration.request.path.format': 'method.request.path.format',
  },
});
endpoint.addMethod('GET', integration, {
  requestParameters: {
    'method.request.path.url': true,
    'method.request.path.format': true,
  },
});

If you know a less verbose solution, please don't hesitate to ping me on Mastodon.

All together solution

export class Stack extends cdk.Stack {
  constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const lambda = new lambda.Function(this, 'SomeFunctionId', {
      runtime: lambda.Runtime.NODEJS_12_X,
      code: lambda.Code.fromAsset('functions/dist/handler'),
      handler: 'index.handler',
    });

    const api = new apigateway.RestApi(this, id, {
      domainName: {
        endpointType: apigateway.EndpointType.EDGE,
      },
      deployOptions: {
        cachingEnabled: true,
        cacheClusterEnabled: true,
        cacheTtl: cdk.Duration.minutes(30),
      },
    });
    const v1 = api.root.addResource('v1');
    const endpoint = v1.addResource('some-route');

    const integration = new apigateway.LambdaIntegration(lambda, {
      cacheKeyParameters: ['method.request.path.url', 'method.request.path.format'],
      requestParameters: {
        'integration.request.path.url': 'method.request.path.url',
        'integration.request.path.format': 'method.request.path.format',
      },
    });
    endpoint.addMethod('GET', integration, {
      requestParameters: {
        'method.request.path.url': true,
        'method.request.path.format': true,
      },
    });
  }
}

Tools to work with accessibility on the Web

Wed, 08 Jan 2020 00:00:00 GMT

Accessibility is often viewed as making your site work on screen readers. In reality, web accessibility is a subset of User Experience (UX) focused on making your websites usable by the widest range of people possible, including those who have disabilities.

https://a11yproject.com/posts/myth-accessibility-is-blind-people

It's important to acknowledge that when we talk about accessibility, we don't only talk about making the website available for people with permanent disabilities, for instance, someone blind or deaf. But, we also include people with temporary disability. Think of someone with a broken arm or a parent with a child in his/her arms. And finally, there could be people in a situation of disability. Like when we have a glow on the screen because of the sunlight. Anyone can be affected in a moment in time by a disability that would prevent us from using a service.

According to the new figures released by the Census Bureau on July 25, 2012, 56.7 million Americans (18.7% of the U.S. population) have some type of disability and out of this number, an estimated 38.3 million (12.6%) have a severe disability.

https://www.interactiveaccessibility.com/accessibility-statistics

Taking accessibility into account means increasing our target audience by allowing as many people as possible to use our services.

And finally, the number of lawsuits in the US has increased by 177% from 2017 to 2018, and we can expect it to continue on that trend. For instance, Dominos lost last year against a blind man named Guillermo Robles. So, by taking accessibility into account early in the process of development, we avoid having to hire more lawyers ;)

With Acast design system Decibel, we aim to have accessible components. It reduces the possibility of having non-accessible interfaces. Still, it doesn't entirely remove the need for the developer to test their product to make sure that everything fits well together. Therefore it's important to include accessibility into our workflow.

Accessibility tools

There are several tools available to help us when working on the client-side. It's easy to miss an Aria attribute, I've done it myself many many times, so the tools I will introduce are here to give us some hints about what could be improved.

VoiceOver

VoiceOver is the screen reader for macOS. It helps us to validate that users can navigate between pages or if elements can easily be reached. People using mouses don't wait to read the full page to make a decision. The same goes for people using screen readers. They don't wait for the voice over to read the full page to decide what they want to do. I recommend checking Youtube videos from people using screen readers to see how effective they can be. They usually use the rotor to navigate between pages quickly.

As a developer, it's essential to verify that the page architecture is correct, and all links or interactive elements are available in the rotor.

To open the rotor, we need to press cmd+f5 to start VoiceOver, then ctrl+opt+u. The, we can navigate between the section using arrow keys.

For instance, it can help us catching if a button has a meaningful label. In the screenshot below, the "button" refers to the play button, so it's complicated for the user to know what the "button" will do.

Another example is buttons that are not implemented as such. It's common for developers to use <div>s because it's quicker to style. But, if we forget to add Aria attributes to specify what the div is, the screen reader won't be able to find it. In the screenshot below, the "sign up" button can't be found in the "Links." So people using screen readers or navigating with keyboards won't be able to reach for the button and join Acast.

On a side note, VoiceOver works better when using Safari. So, it's recommended to use it while testing with VoiceOver.

Axe

Axe is an accessibility engine that is available through different types of plugins. They make sure that their accessibility tests have 0 false positives. So, they only test violations that they are confident about.

Devtool plugin (Firefox and Chrome)

Axe can be used as a devtool extension. When opening it in the devtool it will display the list of issues that can be fixed in the current page.

React plugin (react-axe)

There is also a React plugin that will display the report in the console. You can enable it in the entry point of your react app (where you mount the root component).

import React from 'react';
import ReactDOM from 'react-dom';

if (process.env.NODE_ENV !== 'production') {
  const axe = require('react-axe');
  axe(React, ReactDOM, 1000);
}

Cypress (cypress-axe)

The Cypress plugin will inject Axe and check the DOM when navigating to a page. It will make your test fail when there is an a11y violation.

describe('doc example', () => {
  beforeEach(() => {
    cy.visit('http://localhost:9000');
    cy.injectAxe();
  });

  it('Has no detectable a11y violations on load', () => {
    cy.checkA11y();
  });

  it('Has no a11y violations after button click', () => {
    cy.get('button').click();
    cy.checkA11y();
  });
});

Tota11y

Tota11y is an accessibility visualization toolkit developed by the Khan Academy. It has several overlaps with VoiceOver rotor and Axe, but I think it's an excellent complement. I find it useful to review a page for specific elements quickly. For instance, we can check the heading hierarchy and spot if we are misusing a heading level.

The plugin is available for Firefox and Chrome.

Or if an input doesn't have any label

Aside from these tools, I also recommend using as much as possible React Testing Library selectors to target attributes that the user sees. It's a good practice to avoid using *ByTestId but instead rely on other selectors such as *ByLabel, *ByAltText, etc.

So far, I haven't found a better tool than a screen reader to fully test the user experience. Please, don't hesitate to share the tools you are using to test accessibility.

Decibel: Acast’s design system

Wed, 11 Dec 2019 00:00:00 GMT

I wrote about the component library side of our design system at Acast. Including how we work with it as a remote first company and the tools we use.

Read the article on Acast's tech blog

You can also watch my presentation at Sthlm.js meetup in which I talk about our journey to build Decibel.

The slides can be downloaded here.

How to keep small PRs

Sun, 14 Jul 2019 00:00:00 GMT

Pull Requests (or PRs) are an essential part of team collaboration. It helps to catch issues, spread knowledge, and it brings confidence in our changes. When reviewing code, the reviewers also take responsibility for the changes that will be merged. So, when opening a PR, it's important to share as much information as possible. It helps the reviewers to recreate the mental model we had when working on the task (Why we did that change? How we did it? Why we did it that way). The key is to keep our PRs small and focused. It's fine to have a PR with several commits, and it's even an excellent way to share the flow of our thoughts and changes. But the changes have the be related to the same goal. When PRs are significant, it's harder to spot bugs, design flaws and the reviewers might feel overwhelmed. The worse case would be to approve the change without paying attention to it, which would defeat the initial purpose of working with PRs.

In this article, we will go through different scenarios to split a PR into smaller chunks.

Scenario 1: clean history, but too many unrelated changes

Before opening our PR, we realize that we could move some commits into a different PR. For instance, we created a new helper function on the way, and it will help reviewers to pay more attention to it.

$ git log
## branch: new-feature
* 8ee70d7 Commit 3
* b6a5da4 Add new helper
* d3b11d2 Commit 1

We will create a new branch from master and reuse the commit "Add new helper" using cherry-pick. And then create a PR for that new branch.

$ git log
## branch: new-feature

$ git checkout -b style-helper master
## branch: style-helper
$ git cherry-pick b6a5da4
$ git push origin

We can now go on GitHub and open the pull request.

The last step is to push new-feature to GitHub, but when we open the pull request, we need to change the base branch and use style-helper branch. (On GitLab it's called the "target branch".) We can check the commit history on the GitHub interface and see that "Add new helper" is not part of it. After merging style-helper PR, we should not forget to change the base branch to master before merging new-feature.

Scenario 2: need to split some commits

This time, we have mixed different changes in the same commit. We still want to create a different PR for our style helper, so we need to split that commit into multiple commits.

$ git log
## branch: new-feature
* 8ee70d7 Commit 2
* d3b11d2 Commit 1 <-- commit we want to split

The first step is to go back to "Commit 1" using rebase, and then we will reset that commit to split it using add --patch.

## branch: new-feature

git rebase -i d3b11d2^

Vim, or the editor defined in your gitconfig, will open and we specify which commit we want to edit.

pick 8ee70d7 Commit 2
e d3b11d2 Commit 1

We are now back at "Commit 1" and it's now time to split it. We first need to reset the commit to put the change back in an unstaged state so we can later use add --patch.

$ git reset HEAD~
$ git add --patch

We follow the prompt and decide which hunk we want to stage using yes, no or edit.

$ git commit -m "Split 1"
$ git add --patch
$ git commit -m "Split 2: style helper"

We are now done with splitting the commit. We can complete the rebase.

$ git rebase --continue
$ git log
## branch: new-feature
* 8ee70d7 Commit 2
* 02dbeb3 Split 2: style helper
* cf4ca41 Split 1

We are at a similar stage as the first scenario, and we will go through the same steps for opening the two PRs.

Scenario 3: it's a mess, let's rewrite history

Sometimes things don't go according to plan, and we end up with a spaghetti Git history. The best, in that case, is to rewrite it.

The first step is to find from which commit we want to start fresh.

$ git log
## branch: new-feature
* 255e8d5 Stuff 4
* 5c3fa7e Stuff 3
* deea3e8 Stuff 2
* 10a2b4a Stuff 1 <-- from here

$ git reset 10a2b4a^

Now everything is back to an unstaged state. We will commit the change we want to include in our first PR using add --patch. Then stash the rest to create a new branch and continue to commit from there and finally open our second PR.

## branch: new-feature

$ git add --patch
$ git commit -m "Commit 1"
$ git stash
$ git push origin

We can open the first PR using master as base branch.

Next, we create a new branch for the second PR.

## branch: new-feature

$ git checkout -b pr-2
## branch: pr-2
$ git stash pop
$ git add --patch
$ git commit -m "Commit 2"
$ git stash
$ git push origin

We can open the second PR using new-feature as base branch.

We repeat these steps until we don't have anything left in the stage.

Conclusion

It might feel cumbersome to go through these steps, but I think it's important to show empathy to the reviewers and put them in good condition.

These are the scenarios I have encountered to split a PR into smaller chunks, feel free to share a different way of doing.

Why I use React Testing Library instead of Enzyme

Fri, 14 Jun 2019 00:00:00 GMT

Enzyme has been my weapon of choice since 2016 for testing my React components. What I liked the most with Enzyme was the isolation of the component when testing it using shallow rendering. I could focus on testing the component behaviour and checking that the correct props were passed down to the children (mostly using snapshot testing). That allowed me not to have to mock the children components, for instance for root components, and have tests that run quickly. So, I was only testing at the unit level, each component separately, and tested the big picture using Cypress (end to end testing).

It’s only when I started to use React 16.8 (“The One With Hooks”) that I looked at other testing libraries. The main reason was the non-possibility to test custom hooks with Enzyme and not being able to use shallow rendering. Which led me to be more curious with other solutions and to dig into react-testing-library finally.

Issues with Enzyme

When rendering a component using Enzyme, it wraps the component and allows us to traverse the tree and access the component’s data (instance, props, state, children, …) using a rich API. But, great power comes great responsibility and being able to access internal state of the component (.state(), .setState(), .instance()) often leads to test its implementation. I saw it many times when working on a React codebase, sometimes because it’s “easier and faster than having to reproduce the user steps”. For instance, in a component that has buttons I used to search for a Button component and call its onClick prop instead of having to mount and simulate the click on that element.

wrapper.find('Button').at(0).prop('onClick')();

But, the test would break if we replace the Button with a component having similar functionalities or if we decide to move the button at a different index. It can get really complicated to work with this type of test, since every time you touch the implementation a test breaks. Which makes refactoring really painful. It’s not Enzyme faults per se, but giving access to the private properties to developers allow them to take shortcuts and test the implementation detail which results in brittle tests.

Different approach

React testing library has a different approach to testing than Enzyme. It’s closer to integration testing than unit testing. It renders the component and attaches it to the DOM. We only have access to the elements that are in the DOM. No internal state, no instance methods, just what the user can interact with. And that’s at the end the most important, we want to make sure that our code won’t break when it gets in the user’s hands. It helped me to rethink how and what I test when working on React components.

So far, it's been a great experience:

I like that there is only one type of rendering, so I don't need to think about it;
Tests are still fast to run. I was in the wrong impression that rendering the component on the DOM between each test would be more expensive;
The DOM utils are focused on accessibility (getByRole, getByAltText, etc);
I rely less on snapshot testing and test more individual elements (jest-dom is handy for that) so tests break less when I change an unrelated node element;
My test structure is very similar to what I used to do with Enzyme using a setup factory.

But, it also comes with some downside like having to mock children dependencies, for instance, if it fetches data on mount. So depending on the need, I might use jest.mock to mock a child component.

import { render } from '@testing-library/react';
import React from 'react';
import App from './App';
import SomeAppSection from './SomeAppSection';

jest.mock('./SomeAppSection');

SomeAppSection.mockReturnValue(<div>SomeAppSection</div>);

const setup = (props = {}) => render(<App logout={jest.fn()} {...props} />);

it('renders SomeAppSection', () => {
  const logout = jest.fn();
  const { getByText } = setup({ logout });

  getByText('SomeAppSection');
  expect(SomeAppSection).toHaveBeenCalledWith({ logout }, {});
});

In this example, I don’t want to have to deal with SomeAppSection behaviour since it will require me to have too many things to mock or keep track of when the component will change in the future. So, I fall back to what I used to do with Enzyme by mocking it away.

Great reads related to testing-library or testing in general:

React Hooks by example: useState, useCallback, useEffect, useReducer

Fri, 07 Jun 2019 00:00:00 GMT

In this article, we will touch upon how to use useCallback, useEffect, useReducer and useState hooks.

We will build a component that gives the user the ability to search for a list of users. The component will store the data about the request state (if it’s loading) and response (the user list or the error information). It will listen for the form submit event and call the backend with the input’s value to get the list of users. There are different ways to achieve it, such as using Redux, but we will keep it basic since we will focus on the hooks.

The class way (without hooks)

Using a class component, it could look like this:

class UserSearch extends React.Component {
  constructor(props, ...rest) {
    super(props, ...rest);

    this.state = {
      loading: false,
      error: undefined,
      users: undefined,
    };
  }

  componentWillUnmount() {
    if (this.request) {
      this.request.abort();
    }
  }

  handleFormSubmit = (event) => {
    this.setState({ loading: true });

    this.request = superagent.get(`http://localhost:8080/users/${event.target.elements.username.value}`);
    this.request
      .then((response) => {
        this.setState({
          loading: false,
          users: response.body.items,
        });
      })
      .catch((error) => {
        this.setState({
          loading: false,
          error,
        });
      });
  };

  render() {
    const { loading, error, users, searchValue } = this.state;

    return (
      <form onSubmit={this.handleFormSubmit}>
        {error && <p>Error: {error.message}</p>}

        <input type="text" name="username" disabled={loading} />
        <button type="submit" disabled={loading}>
          Search
        </button>

        {loading && <p>Loading...</p>}

        {users && (
          <div>
            <h1>Result</h1>
            <ul>
              {users.map(({ id, name }) => (
                <li key={id}>{name}</li>
              ))}
            </ul>
          </div>
        )}
      </form>
    );
  }
}

The functional way

We will refactor the UserSearch component step by step and introduce the hooks on the way.

We no longer need to use classes when we use hooks. The first step is to extract the render method into a function based component. We also inline the state and the event handlers, but currently, they don’t do anything.

const UserSearch = () => {
  const loading = false;
  const users = undefined;
  const error = undefined;

  const handleFormSubmit = () => {
    // TODO
  };

  return (
    <form onSubmit={handleFormSubmit}>
      {error && <p>Error: {error.message}</p>}

      <input type="text" name="username" disabled={loading} />
      <button type="submit" disabled={loading}>
        Search
      </button>

      {loading && <p>Loading...</p>}

      {users && (
        <div>
          <h1>Result</h1>
          <ul>
            {users.map(({ id, name }) => (
              <li key={id}>{name}</li>
            ))}
          </ul>
        </div>
      )}
    </form>
  );
};

Introducing hooks

useState

We can use the useState hook to store the different states we have in our component (loading, users, error). useState takes the initial value as a parameter and returns a tuple of the state value and a function to update the value.

const [value, setValue] = useState(initialValue);

Let’s update our states using setState. Currently, we only initialize the states, but we need to implement the logic.

const UserSearch = () => {
  // highlight-start
  const [loading, setLoading] = userState(false);
  const [users, setUsers] = useState();
  const [error, setError] = useState();
  // highlight-end

  const handleFormSubmit = () => {
    // TODO
  };

  return (
    <form onSubmit={handleFormSubmit}>
      {error && <p>Error: {error.message}</p>}

      <input type="text" name="username" disabled={loading} />
      <button type="submit" disabled={loading}>
        Search
      </button>

      {loading && <p>Loading...</p>}

      {users && (
        <div>
          <h1>Result</h1>
          <ul>
            {users.map(({ id, name }) => (
              <li key={id}>{name}</li>
            ))}
          </ul>
        </div>
      )}
    </form>
  );
};

useCallback

A function-based component doesn’t have lifecycles and React calls the function for each new render, which means that for each re-render every hoisted object will be recreated. For instance, a new handleFormSubmit function is created every time. One of the issues is that it invalidates the tree because <form onSubmit={handleFormSubmit}> is different between renders (previous handleFormSubmit ≠ next handleFormSubmit because () => {} !== () => {}).

That’s where useCallback comes into play. It caches the function and creates a new one only if a dependency changes. A dependency is a value that is created in the component but is outside the useCallback scope.

const fn = useCallback(() => {}, [dependencies]);

In the documentation, they recommend “every value referenced inside the callback should also appear in the dependencies array.” Although, you may omit dispatch (from useReducer), setState, and useRef container values from the dependencies because React guarantees them to be static. However, it doesn’t hurt to specify them. Note that If we pass an empty array for the dependencies, it will always return the same function.

I recommend you to use eslint-plugin-react-hooks to help you to know which values we need to include in the dependencies.

You should also check the article written by Kent C. Dodds about when to use useCallback since it also comes with a performance cost to use it over an inline callback. Spoiler: for referential equality and dependencies lists.

So, if we follow how it was done with the class, we could execute the GET request directly in the useCallback.

const UserSearch = () => {
  const [loading, setLoading] = userState(false);
  const [users, setUsers] = useState();
  const [error, setError] = useState();

  // highlight-start
  const handleFormSubmit = useCallback(
    (event) => {
      event.preventDefault();

      setLoading(true);

      const request = superagent.get(`http://localhost:8080/users/${event.target.elements.username.value}`);
      request
        .then((response) => {
          setLoading(false);
          setUsers(response.body.items);
        })
        .catch((error) => {
          setLoading(false);
          setError(error);
        });
    },
    [setLoading, setUsers, setError]
  );
  // highlight-end

  return (
    <form onSubmit={handleFormSubmit}>
      {error && <p>Error: {error.message}</p>}

      <input type="text" name="username" disabled={loading} />
      <button type="submit" disabled={loading}>
        Search
      </button>

      {loading && <p>Loading...</p>}

      {users && (
        <div>
          <h1>Result</h1>
          <ul>
            {users.map(({ id, name }) => (
              <li key={id}>{name}</li>
            ))}
          </ul>
        </div>
      )}
    </form>
  );
};

⚠️ It works, there are few issues by doing that. When React unmounts the component, nothing aborts the request the same way we did in componentWillUnmount. Also, since the request is pending React keeps a reference to an unmounted component. So, it wastes browser resources for something the user will never interact with.

useEffect

useEffect brings the lifecycle to a function based component. It is the combination of componentDidMount, componentDidUpdate, and componentWillUnmount. The callback of useEffect is executed when a dependency is updated. So, the first time the component is rendered, useEffect will be executed. In our case, we want to start the request when the search value is updated (on form submit). We will introduce a new state searchValue that is updated in the handleFormSubmit handler and we will use that state as a dependency to the hook. Therefore when searchValue is updated the useEffect hook will also be executed.

Finally, the useEffect callback must return a function that is used to clean up, for us this is where we will abort the request.

const UserSearch = () => {
  const [loading, setLoading] = userState(false);
  const [users, setUsers] = useState();
  const [error, setError] = useState();
  const [searchValue, setSearchValue] = useState();

  const handleFormSubmit = useCallback(
    (event) => {
      event.preventDefault();
      // highlight-start
      setSearchValue(event.target.elements.username.value);
      // highlight-end
    },
    [setSearchValue]
  );

  // highlight-start
  useEffect(() => {
    let request;

    if (searchValue) {
      setLoading(true);

      request = superagent.get(`http://localhost:8080/users/${event.target.elements.username.value}`);
      request
        .then((response) => {
          setError(undefined);
          setLoading(false);
          setUsers(response.body.items);
        })
        .catch((error) => {
          setLoading(false);
          setError(error);
        });
    }

    return () => {
      if (request) {
        request.abort();
      }
    };
  }, [searchValue, setLoading, setUsers, setError]);
  // highlight-end

  return (
    <form onSubmit={handleFormSubmit}>
      {error && <p>Error: {error.message}</p>}

      <input type="text" name="username" disabled={loading} />
      <button type="submit" disabled={loading}>
        Search
      </button>

      {loading && <p>Loading...</p>}

      {users && (
        <div>
          <h1>Result</h1>
          <ul>
            {users.map(({ id, name }) => (
              <li key={id}>{name}</li>
            ))}
          </ul>
        </div>
      )}
    </form>
  );
};

Dan Abramov has written an excellent blog post about useEffect hooks: a complete guide to useEffect.

useReducer

We have now a working version of our component using React Hooks 🎉. One thing we could improve is when we have to keep track of several states, such as in the request's response we update three states. In our example, I think it’s fine to go with the current version. However, in the case we need to add more states, useReducer would be a better suit. That allows us to gather related states in the same area of our code and have one way to update the states.

useReducer expects a reducer function (that function takes an action and returns a new state) and the initial state. Similar to useState it returns a tuple that contains the state and the dispatch function that we use to dispatch actions.

const [state, dispatch] = useReducer(reducer, initialState);

// highlight-start
const initialState = {
  loading: false,
  users: undefined,
  error: undefined,
  searchValue: undefined,
};

const SET_SEARCH_VALUE = 'SET_SEARCH_VALUE';
const FETCH_INIT = 'FETCH_INIT';
const FETCH_SUCCESS = 'FETCH_SUCCESS';
const ERROR = 'ERROR';

const reducer = (state, { type, payload }) => {
  switch (type) {
    case SET_SEARCH_VALUE:
      return {
        ...state,
        searchValue: payload,
      };

    case FETCH_INIT:
      return {
        ...state,
        error: undefined,
        loading: true,
      };

    case FETCH_SUCCESS:
      return {
        ...state,
        loading: false,
        error: undefined,
        result: payload,
      };

    case ERROR:
      return {
        ...state,
        loading: false,
        error: payload,
      };

    default:
      throw new Error(`Action type ${type} unknown`);
  }
};
// highlight-end

const UserSearch = () => {
  const [state, dispatch] = useReducer(reducer, initialState);

  const handleFormSubmit = useCallback(
    (event) => {
      event.preventDefault();

      // highlight-start
      dispatch({
        type: SET_SEARCH_VALUE,
        payload: event.target.elements.username.value,
      });
      // highlight-end
    },
    [dispatch]
  );

  useEffect(() => {
    let request;

    if (state.searchValue) {
      // highlight-next-line
      dispatch({ type: FETCH_INIT });

      request = superagent.get(`http://localhost:8080/users/${state.searchValue}`);
      request
        .then((response) => {
          // highlight-next-line
          dispatch({ type: FETCH_SUCCESS, payload: response.body.items });
        })
        .catch((error) => {
          // highlight-next-line
          dispatch({ type: ERROR, payload: error });
        });
    }

    return () => {
      if (request) {
        request.abort();
      }
    };
  }, [state.searchValue, dispatch]);

  return (
    <form onSubmit={handleFormSubmit}>
      {/* highlight-start */}
      {state.error && <p>Error: {state.error.message}</p>}

      <input type="text" name="username" disabled={state.loading} />
      <button type="submit" disabled={state.loading}>
        Search
      </button>

      {state.loading && <p>Loading...</p>}

      {state.users && (
        <div>
          <h1>Result</h1>
          <ul>
            {state.users.map(({ id, name }) => (
              <li key={id}>{name}</li>
            ))}
          </ul>
        </div>
      )}
      {/* highlight-end */}
    </form>
  );
};

As mentioned before, the benefits are not directly apparent since we don't have that many states to handle in our example. There is more boilerplate than the useState version, but all states related to calling the API are managed in the reducer function.

Continuous deployment of a Phoenix project using GitLab CI/CD

Sun, 02 Jun 2019 00:00:00 GMT

In this article, we will walk through the setup of GitLab CI/CD pipelines to run the tests and deploy the latest version for each merge on master. We assume that you already have a Phoenix project up and running, and created a GitLab repository for your project.

We need to create the gitlab-ci.yml file at the root of the repository. In this file, we will define the different jobs that are required to deploy a new version to production automatically:

init: we download the dependencies and build the project;
lint: we make sure that the code follows our style guide;
test: we make nothing has broken with our changes;
deploy: push the new version to production. This step is only executed when we merge a feature branch on master.

TLDR; jump at the end of the article to have the full gitlab-ci.yml config file.

Default settings

I the gitlab-ci.yml file we define:

the list of stages;
the env variables that are used by Phoenix for the database;
the default settings for Elixir and JavaScript we will re-use for each jobs.

stages:
  - init
  - lint
  - test
  - deploy

variables:
  POSTGRES_DB: test_test
  POSTGRES_HOST: postgres
  POSTGRES_USER: postgres
  POSTGRES_PASSWORD: 'postgres'
  MIX_ENV: 'test'

.elixir_default: &elixir_default
  image: elixir:1.8
  before_script:
    - mix local.hex --force
    - mix local.rebar --force

.javascript_default: &javascript_default
  image: node:alpine
  before_script:
    - cd assets

Init stage

In the init stage, we set up the environment for the next jobs by compiling the project, downloading the dependencies and saving the artifacts.

elixir_compile:
  <<: *elixir_default
  stage: init
  script:
    - apt-get update
    - apt-get install -y postgresql-client
    - mix deps.get --only test
    - mix compile --warnings-as-errors
  artifacts:
    paths:
      - mix.lock
      - _build
      - deps

javascript_deps:
  <<: *javascript_default
  stage: init
  script:
    - npm install --progress=false
  artifacts:
    paths:
      - assets/node_modules

Lint stage

Credo for Elixir

We use Credo to lint the Elixir part of the project. To install it we add its dependency to mix.exs.

defp deps do
  [
    {:credo, "~> 1.0.0", only: [:dev, :test], runtime: false}
  ]
end

There are plenty of settings that are available with Credo to match your style guide.

Eslint and Prettier for JavaScript

For JavaScript, we use Eslint + Prettier. We add the required dependencies that are automatically added in assets/package.json.

cd assets && npm install --save-dev babel-eslint eslint eslint-config-prettier eslint-plugin-prettier prettier

We define the Eslint config in assets/.eslintrc.

{
  "parser": "babel-eslint",
  "extends": ["eslint:recommended", "prettier"],
  "plugins": ["prettier"],
  "rules": {
    "prettier/prettier": "error"
  },
  "env": {
    "browser": true,
    "jest": true,
    "node": true
  }
}

And the Prettier config in assets/.prettierrc.

{
  "trailingComma": "es5",
  "tabWidth": 2,
  "semi": false,
  "singleQuote": false
}

Finally, we update assets/package.json to add the lint task.

"scripts": {
  "deploy": "webpack --mode production",
  "watch": "webpack --mode development --watch",
  "lint": "eslint . --max-warnings=0"
}

CI jobs

We can now add the jobs in gitlab-ci.yml to run the linters in the CI.

elixir_lint:
  <<: *elixir_default
  stage: lint
  script:
    - mix format --check-formatted
    - mix credo --strict

javascript_lint:
  <<: *javascript_default
  stage: lint
  script:
    - npm run lint

Test

Jest for JavaScript

We will use the test task in our assets/package.json to execute the client tests. I recommend using Jest. It's a fast test framework, has an easy way to mock dependencies, has a nice interactive CLI, and it comes with jsdom by default.

cd assets && npm install --save-dev jest

You can setup Jest config by running npx jest --init.

We run Jest in the test task by adding it to the assets/package.json

"scripts": {
  ...
  "test": "jest"
},

CI jobs

Let's add the test jobs in our gitlab-ci.yml file

elixir_test:
  <<: *elixir_default
  stage: test
  services:
    - postgres:11.3
  script:
    - mix ecto.create
    - mix ecto.migrate
    - mix test

javascript_test:
  <<: *javascript_default
  stage: test
  script:
    - npm run test

Deploy

We will use Gigalixir as a hosting platform. It's a PaaS designed for Elixir and Phoenix. The deployment is similar to Heroku, where we deploy by pushing to a remote branch. Moreover, it has a free plan that allows us to run our app with a Postgres database.

Before adding the deployment config for GitLab, we need to make sure everything is set up for Gigalixir locally.

First we need to install the Gigalixir command line tools:

pip install gigalixir --ignore-installed six

And then login:

gigalixir login

We can now create a new app with a Postgres database on their platform:

gigalixir create -n my-app
gigalixir pg:create --free

Gigalixir has a good documentation to config the production environment of our Phoenix project.

We need to delete prod.secret.exs file since Gigalixir is handling it for us and we will use the environment variable instead. Then we open prod.exs and delete the import of import_config "prod.secret.exs". And finally, we add the configuration to connect to Gigalixir.

config :my_app, MyAppWeb.Endpoint,
  http: [port: {:system, "PORT"}],
  url: [host: System.get_env("APP_NAME") <> ".gigalixirapp.com", port: 80],
  secret_key_base: Map.fetch!(System.get_env(), "SECRET_KEY_BASE"),
  server: true

config :my_app, MyApp.Repo,
  adapter: Ecto.Adapters.Postgres,
  url: System.get_env("DATABASE_URL"),
  ssl: true,
  pool_size: 2

The environment variables are automatically set by Gigalixir when we deploy.

Specify versions

Next, we need to specify the versions we are using to build the project. At the root of the repository, we create the files:

elixir_buildpack.config

elixir_version=1.8.2
erlang_version=21.2.5

phoenix_static_buildpack.config

node_version=10.16.0

Build client side

We need to add a new file at the root of the repository called compile and paste the following lines:

npm run deploy
cd $phoenix_dir
mix "${phoenix_ex}.digest"

We are now ready to deploy. Commit the changes and manually push the first version to Gigalixir to make sure everything works as expected.

git push gigalixir master

We can navigate to the link of the app to check or check the logs by running gigalixir logs.

CI job

We are now ready to add the deploy step in our gitlab-ci.yml file.

deploy:
  stage: deploy
  script:
    - git remote add gigalixir $GIGALIXIR_REMOTE_URL
    - git push -f gigalixir HEAD:refs/heads/master
  when: manual
  only:
    - master

Note that you can remove the line when: manual if you want to deploy a new version to production every time you merge to master. Otherwise, with when: manual you will need to go on GitLab pipeline interface and start this step manually.

We added a new environment variable $GIGALIXIR_REMOTE_URL. You need to set its value in GitLab project's settings (settings → CI/CD → variables). It should have the following format:

https://name%40mail-provider.com:password@git.gigalixir.com/my-project-name.git

You can find the values by opening ~/.netrc

machine git.gigalixir.com
  login doe@fastmail.com
  password 1234-5678-9

So, for our my-app project the remove URL is:

https://doe%40fastmail.com:1234-5678-9@git.gigalixir.com/my-app.git

Let's merge our changes on master and watch GitLab deploying our app on Gigalixir 🎉

The all together gitlab-ci.yml

variables:
  POSTGRES_DB: test_test
  POSTGRES_HOST: postgres
  POSTGRES_USER: postgres
  POSTGRES_PASSWORD: 'postgres'
  MIX_ENV: 'test'

stages:
  - init
  - lint
  - test
  - deploy

.elixir_default: &elixir_default
  image: elixir:1.8
  before_script:
    - mix local.hex --force
    - mix local.rebar --force

.javascript_default: &javascript_default
  image: node:alpine
  before_script:
    - cd assets

elixir_compile:
  <<: *elixir_default
  stage: init
  script:
    - apt-get update
    - apt-get install -y postgresql-client
    - mix deps.get --only test
    - mix compile --warnings-as-errors
  artifacts:
    paths:
      - mix.lock
      - _build
      - deps

elixir_lint:
  <<: *elixir_default
  stage: lint
  script:
    - mix format --check-formatted
    - mix credo --strict

elixir_test:
  <<: *elixir_default
  stage: test
  services:
    - postgres:11.3
  script:
    - mix ecto.create
    - mix ecto.migrate
    - mix test

javascript_deps:
  <<: *javascript_default
  stage: init
  script:
    - npm install --progress=false
  artifacts:
    paths:
      - assets/node_modules

javascript_lint:
  <<: *javascript_default
  stage: lint
  script:
    - npm run lint

javascript_test:
  <<: *javascript_default
  stage: test
  script:
    - npm run test

deploy:
  stage: deploy
  script:
    - git remote add gigalixir $GIGALIXIR_REMOTE_URL
    - git push -f gigalixir HEAD:refs/heads/master
  when: manual
  only:
    - master

Writing a meaningful commit message

Fri, 16 Nov 2018 00:00:00 GMT

When working in a team of developers, it's important to share what you attended to achieve with your code and why you did it that way. It can be done using clear variable names, comments, ... but also via Git commit messages.

Commit messages are useful for:

Code review: it helps the reviewer to follow your chain of thoughts, understand what you solved in your PR.
git blame: it brings context to the line/block of code.
git log, git rebase, git revert or git bisect: it helps you to grasp what the changes are about without having to dig into each line of code contained in the commit.

The structure of a commit message

I follow the rules detailed in the famous article from Chris Beams. They are the most common I encountered at work or in open source projects.

I like to follow his methodology to write the subject line. When writing the message, I think about the following sentence:

If applied, this commit will [your subject line]

I strongly recommend you to read the full article How to Write a Git Commit Message, it has a lot of great insights and guidance.

When things don't go according to plan

git commit -am "Bunch of stuff"

It's a good practice to commit as often as possible, since it simplifies the work when writing the commit message, hence a cleaner Git history. But, sometimes things don't go as planned and we do too many changes without committing. Hopefully, it is possible to stage and commit code lines separately using git add --path. You can read more about it in The Git Add Patch Command article in which the author describes how to achieve it using the command line or in VSCode. I prefer to use a GUI to do that since I have a better overview at what I want to stage instead of going chunk by chunk using the CLI. It's actually the only reason I open a GUI for Git.

git commit -am "Oops forgot a semicolon."

For some reason<sup>*</sup>, an error passed through the linter and had been committed. We realise later when the CI is failing, and the PR rejected that we've forgotten a semicolon. Bummer. Committing that alone won't be any value to the reviewer, and we might have to redo the fix if we need to revert to a previous state. Luckily the PR is still open so that we can add the missing semicolon in the right commit.

If the error occurred in the last commit, we could write the fix, stage and commit using the --amend flag. That way the change is part of the previous commit, incognito.

git add -A
git commit --amend --no-edit
# Push the fix to the PR branch
git push origin --force-with-lease

You can read more about why you should use --force-with-lease instead of --force.

Otherwise, if the issue happened earlier in Git history, we need to go back in time using the powerful git rebase. First, we need to find where it happened and we have several options:

Check the history of the given line where the issue is, using git blame.
Check the log to read through the changes, using git log --oneline or git log -p (or using your favourite GUI).
And if none of it worked, we can use git bisect.

In my experience, since it's related to one of my commits, I can find it using the log.

We have now found the commit, we can use its SHA hash and rebase on it:

git rebase -i e39a40e39bc325cde31b71402a79afb7be7e31ef^

e38a... is the SHA hash
The ^ at the end of the SHA hash is to specify that we want to start the rebase from this commit. Without it, it will begin at the next commit.

Git opens a new window<sup>**</sup> where we specify the commands to run for each commit. Here, we replace pick with edit (or e for short) on the first line:

edit e39a40e The commit we want to update
pick 84da00a Another commit message

# Rebase e39a40e..84da00a onto e39a40e (2 commands)
#
# Commands:
# p, pick <commit> = use commit
# r, reword <commit> = use commit, but edit the commit message
# e, edit <commit> = use commit, but stop for amending
# s, squash <commit> = use commit, but meld into previous commit
# f, fixup <commit> = like "squash", but discard this commit's log message
# x, exec <command> = run command (the rest of the line) using shell
# d, drop <commit> = remove commit

Save the file, and Git brings us back at the commit.

Now, all we have to do is to add the missing semicolon, stage the change, continue the rebase and finally push the change to the remote branch.

git add -A
git rebase --continue
git push origin --force-with-lease

<a name="footnote1">*</a> I heard you like to commit using -n? 👀

<a name="footnote2">**</a> it's possible to configure Git to use your favourite editor.

VSCode as a Vim editor

Sat, 08 Sep 2018 00:00:00 GMT

In 2013 I started to use Vim as my primary editor, the journey hasn't been without frustration, but in general, I really enjoyed using it. It took me sometimes, but I found a setup that worked well for me from autocompletion to code navigation. What I love the most is Vim motions, I would not trade that feature for something else.

So, if everything was fine why did you start using VSCode?

I got mainly interested by VSCode for its debugging and refactoring features. I got used to debugging JavaScript or CSS in the browser's dev tools, but I never found the right spot for debugging Node apps. With VSCode it is possible to debug directly in the editor, to add breakpoints or investigate the stack trace.

But, as usual, the first thing I do when I start to use a new code editor to install the Vim plugin.

VSCode Vim plugin

In a nutshell, VSCodeVim is really good. It is by far the best Vim integration I have tried outside Vim (or NeoVim) itself. It's fast, includes plugins I love (easymotion, sneak, surround), and supports all motions and most shortcuts I used to use.

To get there I had to tweak the settings to be able to remap commands, but the great thing with this plugin is that we can remap loads of it!

For instance, I use jk to switch between insert and normal mode.

{
  "vim.insertModeKeyBindings": [
    {
      "before": ["j", "k"],
      "after": ["<Esc>"]
    }
  ]
}

You need to define that in User Settings. (Search for Preferences: Open User Settings. in the command palette (⇧⌘P).)

It is pretty straightforward, you define what mapping you want to use in before and what output you want to get into after.

I rely a lot on EasyMotion to move around (jump to a different line or a character) but I found the default setting quite annoying: I have a double press the leader key, instead of once in Vim, and then the action (for instance j to go to a line below). But, it is possible to remap it!

{
  "vim.normalModeKeyBindingsNonRecursive": [
    {
      "before": ["<leader>", "j"],
      "after": ["<leader>", "<leader>", "j"]
    }
  ]
}

You can remap not only key bindings but also execute commands. For instance to toggle a bookmark using ma:

{
  "vim.normalModeKeyBindingsNonRecursive": [
    {
      "before": ["m", "a"],
      "after": [],
      "commands": [
        {
          "command": "bookmarks.toggle",
          "args": []
        }
      ]
    }
  ]
}

I have been able to remap bindings to match my Vim memory muscles. I felt at home when starting to use VSCode.

You can find my VSCodeVim settings on this Gist.

Refactoring

VSCode has made some refactoring tasks easier than what I used to in Vim. One of my favourites is renaming a variable by pressing f2. All occurence will be updated in the project. The same happens when you rename a file or move it to another folder, its path is updated where it is used.

More recently I discovered that we could easily transform arrow function with implicit return:

const add = (a, b) => a + b;

Put the cursor on (, then press ctrl+shift+r -> add braces to arrow function. It will convert it to:

const add = (a, b) => {
  return a + b;
};

Super convenient when you need to debug a function.

In general, I find it more comfortable to refactor in VSCode, the multiple cursors works better than on Vim, and I can still use visual block mode when I need it.

Debugging

So far, I have only used the "attach to process" debug mode. When you run node (or nodemon) with the —inspect flag you can attach the process in VSCode to debug the application.

In launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "attach",
      "name": "dev:server inspect",
      "port": 5858,
      "restart": true,
      "protocol": "inspector"
    }
  ]
}

It's an excellent way of debugging Node.js apps, so you don't need to open a Chrome dev tools to add breakpoints and put debugger statement in your code.

Navigation

After some tuning, navigating in VSCode looks familiar to Vim:

Search a file using the fuzzy finder à la CtrlP.
Use the command palette to run commands when I don't think it is necessary to memorise a key binding. For instance, I use Open In GitHub plugin to open the GitHub page in the browser to open a pull request. Instead of mapping it on a crazy multi-combo binding, I find it easier to use the command palette and search for the command.
Jump between windows using ctrl + hjkl. (More about it in "What I miss from Vim" section.)
Go to definition using gf. (In Vim I used Ternjs to have this feature, "60% of the time, it works every time".)
Use the code outline to jump between symbols in a file using cmd+shift+o. I'm in love with this feature.
Switch between tabs using gt (next tab) or gT (previous tab). ctrl + tab comes handy when I have too many files open, which happen more often to me because of the poor window management support on VSCode.
Jump to the next occurrence of the variable under the cursor using *.
Jump to the next change using <leader>n (next change) or <leader>p (previous change).
And of course, my beloved Vim motions.

Language support

The VSCode community is active, so I haven't encountered a language that wasn't supported: JavaScript (+JSX), TypeScript, Sass, Elm, Elixir/Phoenix, or Haskell.

Autocompletion is right most of the time, except for CSS or Sass files where it struggles to suggest class names defined in a template file. It also has some issues to autocomplete snippets. If I type too fast, I will need to close and reopen the suggestion box to be able to run a snippet.

What I miss from Vim

Obviously, everything is not perfect. The main thing I miss from Vim is the window management, in VSCode the current support is really basic.

In Vim, it is possible to open several files under the same tab, so it is straightforward to create different spaces with related files and terminal open. For instance, you can open a tab containing all files related to a component.

| TAB A |
----------------------------------------------------------------------
Module.js     | Module.test.js     | Terminal that runs
              |                    | Module.test.js
              |--------------------|
              | Module.style.scss  |
              |                    |

In VSCode, tabs are all independent, so even if I can split the screen in two, I can't switch tabs to change both files at the same time. So, I need to jump back and forth between the files to switch the tabs accordingly. Annoying.

| TAB Module.js | TAB Module.test.js | TAB Terminal
---------------------------------------------------------------------------

It creates some frustration when I try to jump quickly between files and terminals since I need to remember where are the related files are and keep things in sync manually.

What's next?

I will keep using VSCode and haven't planned to go back to my previous setup iTerm + NeoVim. It has (almost) everything I'm looking for: it is fast, it has good language, and autocompletion support, a built-in terminal, and I can still use Vim in it. A nice thing is that most of my colleagues use it as well, so we can share settings in a project or do remote pair programming in VSCode directly, which is fantastic.

How to create declaration files for JavaScript dependencies in TypeScript

Wed, 15 Aug 2018 00:00:00 GMT

In this article, I used TypeScript v3.

In TypeScript, declaration files (.d.ts) are used to describe the shape of a JavaScript module. By default, TypeScript can't infer types, so you need to define these files to help the type checker, but also to get better autocompletion in your code editor. When importing a dependency into a TypeScript code base, you might get this error.

error TS7016: Could not find a declaration file for module 'my-dependency'.

The first solution that could be used in case you are starting to use TypeScript in an existing JavaScript project is to set noImplicitAny in your tsconfig.json.

{
  "compilerOptions": {
    "noImplicitAny": false
  }
}

TypeScript will assume that non annotated properties have the type any. This is helpful to update the codebase gradually, but you lose TypeScript safety.

The second option is to check if your dependency has a declaration file already created in the DefinitelyTyped repository. You can search it on TypeSearch website. If you are lucky, you will find it, and you need to install it as a dependency.

npm install --save-dev @types/my-dependency

But sometimes you won't find it, and that leads us to the third solution, writing your own declaration file.

Writing you own declaration file

You can find different declaration file templates in the official documentation, but let's go through an example.

You have imported koa-static-server module, and it doesn't have a declaration file in DefinitelyTyped. So, as you've seen earlier in the article, you need to write one locally.

First, you need to update typeRoots in tsconfig.json to let the compiler know where to find the local declaration files.

{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types/", "./src/@types"]
  }
}

Here, you can write the local declaration file in src/@types.

And finally, you can create the declaration file for koa-static-server

mkdir src/@types/koa-static-server/index.d.ts

In this example I haven't put the entire type declaration for this module.

declare module 'koa-static-server' {
  import Koa from 'koa';

  interface Options {
    rootDir: string;
    rootPath: string;
    gzip: boolean;
  }

  export default function staticServer(options: Options): Koa.Middleware;
}

declare statement declares the module on a global level, so we don't need to import it in our code. TypeScript does it automatically via the typeRoots flag. The code inside the module declaration is similar to a TypeScript module: you expose the functions with their types that are defined in the JavaScript module.

I recommend you to check the official documentation to have more examples, but keep in mind that some of them use an older TypeScript's syntax such as export = staticServer instead of export default.

Refactoring a Redux application using redux-actions

Wed, 04 Jul 2018 00:00:00 GMT

Redux is widely used and a great way to manage your data flow in a React app, but a common complaint is that Redux requires a lot of boilerplate code. I was looking for a way to reduce the boilerplate while keeping code expressiveness. In the official Redux documentation, they mention different solutions, but my attention got drawn by redux-actions. It follows Flux Standard Action convention and has a small API that covers the creation and handling of actions.

In this example, we have a duck module that manages to fetch and store articles. We use redux-thunk for handling asynchronous actions.

import * as api from '../api/articles';

// Types
export const BEGIN_REQUEST = 'ARTICLES/BEGIN_REQUEST';
export const GET_ARTICLES = 'ARTICLES/GET_ARTICLES';
export const GET_ARTICLES_COMPLETE = 'ARTICLES/GET_ARTICLES_COMPLETE';

export const status = {
  LOADING: 'LOADING',
  ERROR: 'ERROR',
  COMPLETE: 'COMPLETE',
};

// Actions
export const beginRequest = () => ({
  type: BEGIN_REQUEST,
});

export const getArticlesComplete = (result) => {
  if (result instanceof Error) {
    return {
      type: GET_ARTICLES_COMPLETE,
      payload: result,
      error: true,
    };
  }

  return {
    type: GET_ARTICLES_COMPLETE,
    payload: result,
  };
};

export const getArticles = () => (dispatch) => {
  dispatch(beginRequest());

  return api.getArticles().then(
    (entities) => {
      dispatch(getArticlesComplete(entities));
    },
    (error) => {
      dispatch(getArticlesComplete(error));
    }
  );
};

// Reducer
const initialState = {
  status: null,
  error: null,
  entities: null,
};

export default (state = initialState, { type, payload, error }) => {
  switch (type) {
    case BEGIN_REQUEST:
      return {
        ...state,
        status: status.LOADING,
      };

    case GET_ARTICLES_COMPLETE:
      if (error) {
        return {
          ...state,
          status: status.COMPLETE,
          error: payload,
        };
      }

      return {
        ...state,
        status: status.COMPLETE,
        entities: [...state.entities, ...payload],
        error: null,
      };

    default:
      return state;
  }
};

This example is a "classic" way of defining action creators and a reducer. Where I think we can reduce boilerplate is when we need to handle different payloads’ states, depending on if it is an error or the entities. Every time we need to create a "complete" action creator, like getArticlesComplete, we have to check the type of the payload to know if it is a failure or a success. This code is redundant and doesn't bring valuable information, and thereby it can be extracted into a helper function.

Refactoring using redux-actions

Actions

import { createAction } from 'redux-actions';

// ...

export const beginRequest = createAction(BEGIN_REQUEST);
export const getArticlesComplete = createAction(GET_ARTICLES_COMPLETE);

// ...

redux-actions has a helper createAction that does the work for us to handle the different payloads’ states. Moreover, by using this helper, we know that these actions can have success and failure states.

Note: We haven't yet refactored getArticles since it is an async action and has a different logic.

Reducer

import { handleActions } from 'redux-actions';

// ...

export default handleActions(
  {
    [BEGIN_REQUEST]: (state) => ({
      ...state,
      status: status.LOADING,
    }),

    [GET_ARTICLES_COMPLETE]: {
      next: (state, { payload }) => ({
        ...state,
        status: status.COMPLETE,
        entities: [...state.entities, ...payload],
        error: null,
      }),

      throw: (state, { payload }) => ({
        ...state,
        status: status.COMPLETE,
        error: payload,
      }),
    },
  },
  initialState
);

handleActions let us define our reducer. The big change is that we handle the success and failure states using next (success) and throw (failure) instead of using the if statement. The positive part is that now each reducer is defined into separated functions, so it prevents data leaking between action types. Other than that, the handleActions solution is close to the switch statement in terms of readability.

Moving forward using reduce-reducers

import { createAction, handleAction } from 'redux-actions';
import reduceReducers from 'reduce-reducers';

// ...

const initialState = {
  status: null,
  error: null,
  entities: null,
};

// BEGIN_REQUEST

export const beginRequest = createAction(BEGIN_REQUEST);

const beginRequestReducer = handleAction(
  BEGIN_REQUEST,
  (state) => ({
    ...state,
    status: status.LOADING,
  }),
  initialState
);

// GET_ARTICLES

export const getArticlesComplete = createAction(GET_ARTICLES_COMPLETE);

export const getArticles = () => (dispatch) => {
  dispatch(beginRequest());

  return api.getArticles().then(
    (entities) => {
      dispatch(getArticlesComplete(entities));
    },
    (error) => {
      dispatch(getArticlesComplete(error));
    }
  );
};

const getArticlesReducer = handleAction(
  GET_ARTICLES_COMPLETE,
  {
    next: (state, { payload }) => ({
      ...state,
      status: status.COMPLETE,
      entities: [...state.entities, ...payload],
      error: null,
    }),

    throw: (state, { payload }) => ({
      ...state,
      status: status.COMPLETE,
      error: payload,
    }),
  },
  initialState
);

export default reduceReducers(beginRequestReducer, getArticlesReducer);

reduce-reducers allows us to reduce multiple reducers into a single reducer. So, what it means is that we can define each reducer (BEGIN_REQUEST, and GET_ARTICLES_COMPLETE) into their own handleAction. What I like about this solution is that we can gather related code from the action type to the action creator and the reducer and put it in the same part of the ducks file.

ESLint and Prettier for a better team collaboration

Tue, 29 May 2018 00:00:00 GMT

When we work in a team of developers we all have our way of programming which may end up with an archaeology type of codebase, where we can guess who has written which part just by the way the code is formatted. You get distracted when you read the code due to a stylistic difference, and you lose time in PRs for nitpicking feedback. The code is also harder to maintain since you may end up with Git diffs related only to formatting. For these reasons, it's important to share the same coding style.

Luckily the process of making sure that all code follows the same style is easily automated. Linting and formatting before committing the code ensure that it looks the same, no matter who writes it.

At Acast, we have decided to use ESLint coupled with Prettier. ESLint is a JavaScript linting and style checking tool that warns you when your code is not following given rules, but it doesn't reformat your code. That's where Prettier comes into play. Prettier is a fantastic tool that entirely takes the responsibility to format your code. It's opinionated which means it has only a few settings you can customize. Moreover, it is well integrated with ESLint, so it's possible to run Prettier via eslint --fix command, which reduces the number of commands that you have to run to lint and format the codebase. Additionally, we chose to use the ESLint config from Airbnb because it's popular amongst the JavaScript community and to avoid lengthy discussions around what rules we should define in our config. We want to override as few rules as possible to avoid entering lengthy debates loop for little reward.

How to use it.

To include it into your project, you can check the README file in the eslint-config-acast project or do these two steps:

Install the needed packages:

npm install --save-dev eslint-config-acast eslint prettier

Create a .eslintrc file and add the following to it:

{
  "extends": "acast"
}

And you are good to go!

Automate all the things!

To be able to lint your changes before committing I recommend to use lint-staged and husky. They allow you to run npm tasks on Git hooks events, in our case in precommit hook.

npm install --save-dev husky lint-staged

In your package.json:

{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "*.js": ["eslint --fix", "git add", "eslint --max-warnings=0"]
  }
}

Now, every time you commit a change, lint-staged runs eslint against files that have been staged to fix formatting changes. Then, it stages them back and runs eslint again to detect other errors. The commit is aborted if there is an error.

How to test promises with Mocha

Mon, 18 Apr 2016 00:00:00 GMT

Promises are convenient to deal with asynchronous code in JavaScript, but at first glance it can feels tedious when it comes to unit test them.

The first approach might be to unit test promises in the same way as we do with callbacks: by calling the done() function, passed by Mocha, when the promise is completed.

it('should do something async', function (done) {
  asyncCall().then(function (result) {
    expect(result).to.be('foo');
    done();
  });
});

It works fine if the test passes but if it fails, then we don't get any error report from mocha, at best a timeout error. This is because we don't handle the case when the promise is rejected. This is where it gets tedious and adds more boilerplate: every time we test a promise, we end up having several done() calls in our test. (which bothers me.)

it('should do something async', function (done) {
  asyncCall()
    .then(function (result) {
      expect(result).to.be('foo');
      done();
    })
    .catch(done);
});

Built in Promises support

Hopefully, Mocha comes with a nice built in support. Instead of having to handle manually failing tests, we can directly return the promise.

it('should do something async', function () {
  return asyncCall().then(function (result) {
    expect(result).to.be('foo');
  });
});

And voilà! Now we don't need to think about where we need to put the done() calls.

If you want to directly assert your promises, I recommend you to look over Chai promises plugin.

Tools to keep a consistent coding style in JavaScript

Mon, 09 Mar 2015 00:00:00 GMT

"Code formatting is important. It is too important to ignore and it is important to treat religiously. Code formatting is about communication, and communication is the professional developer's first order of business."

-- Robert C. Martin. Clean code: A handbook of Agile software craftmanship

Update: I now use ESLint and Prettier to keep a consistent coding style. You can find more information in this article.

EditorConfig is the first tool I used to make sure people in the team used the same basic settings, such as trailing whitespace & indent style/size, mainly to simplify git merging. Nevertheless, I was looking for tools more focused on JavaScript, in addition to EditorConfig, in order to share the same coding style.

In JavaScript there are plenty of tools to help you to keep your code clean. Like JSHint, JSCS, fixmyjs, JS Beautifier, and other that I haven't tested yet.

I chose to use ESLint to lint my JavaScript code and esformatter to format it. The main reason I chose these ones is the customisability: they are pluggable and they have a large range of settings to really fit my coding style.

ESLint

ESLint detects errors or problems in your code, as well as JSHint. For instance it raises an error if a variable in not declared. Moreover it also checks the coding style based on rules. It will warm you in case you missed a space after if for example.

You specify the rules in a configuration file .eslinrc. It could be globally, saved in your $HOME, or locally at the root of your project. Here is my .eslintrc as an example, and you can find more information about the configuration in the project documentation.

You can use it in different way, either with the command line, or your favourite tasks runner or directly in your text editor. (See the official plugins list.) I prefer to use it in my code editor (in Vim through syntastic), thereby I get direct feedback and it helps me to avoid errors while coding.

So far I really like it, it's in between JSHint and JSCS (which is only focused on the coding style). The list of rules cover almost everything. So if you like JSHint, I definitively recommend you to give a try to ESLint.

esformatter

esformatter beautifies your code based on a set of rules. As ESLint, you define the rules in a .esformatter file, which could be global ($HOME) or local (project's root). I recommend you to try out esformatter-visualize that will help you out to configure your settings.

You can use esformatter through command line interface, tasks runner (Gulp, Grunt and Brunch) and text editor (Vim, Sublime Text and Atom).

Like ESLint, I prefer to use esformatter inside Vim. It lets me code quickly without worrying too much about code formatting and I trigger the command (<leader>es) to beautify it.

It is still "work in progress" but it does a pretty great job so far. It starts to have more and more plugins to fit specific needs, like using one var or multiple var statement. I look forward to be able to use one configuration file for both ESLint and esformatter as they are almost using the same rules.

If you are interested, here is my .esformatter file.

ES6 & JSX

If you are using ES6 and/or JSX, ESLint already supports JSX and partially ES6. The team of esformatter is working to support ES6 features and there are plugins that fill the gap for JSX. I use esformatter-jsx-ignore that "ignore JSX blocks so the rest of the javascript code could be formatted".

Feel free to share your experience or tools you like to use to maintain your coding style.

npm as a front-end package manager

Mon, 19 May 2014 00:00:00 GMT

Vous pouvez lire la version française de cet article.

npm has played an important role in Node.js success. It facilitates the creation, sharing and installation of packages and allows developers to follow the Unix philosophy where each module "do one thing well". (Avoids complexity, facilitates code reusability and testing.)

However, npm isn't limited to JavaScript modules. It's possible to publish any type of file and this is where it gets interesting for our front-end modules, which can be CSS, HTML, fonts, etc..

JavaScript module

If you are not used to creating packages, I recommend you run the command npm init which helps you to generate the package.json (this file contains all the information used by npm).

{
  "name": "my-javascript-module",
  "version": "0.0.1",
  "main": "index.js"
}

If you want to write a module that work everywhere: AMD (RequireJS) , CommonJS (Browserify) or directly with the window object, you should take a look to UMD patterns repository. There are different types of wrapper to export your API. For instance:

(function (root, name, definition) {
  if (typeof define === 'function' && define.amd) {
    define([], definition);
  } else if (typeof module === 'object' && module.exports) {
    module.exports = definition();
  } else {
    root[name] = definition();
  }
})(this, 'ModuleName', function () {
  // Here, you define the API of your module.

  // You can return a value, a function or like
  // in this example, an object.
  return {};
});

Module for other file types

In the [files](https://docs.npmjs.com/files/package.json#files) field, we can define the list of files we want to publish (CSS, fonts, SVG, etc.). For instance, a package.json for a CSS grid module.

{
  "name": "grid-system",
  "version": "0.0.1",
  "files": [
    "grid.css"
  ]
}

Once you have published and installed (npm install grid-system --save) the package, the grid.css file will be located in node_modules/grid-system/grid.css. Therefore you can include it in your HTML files or @import it inside your Sass files. (The Sass option --load-path is really useful if you don't want to have to specify the path to node_modules each time you import a module.)

<link href="node_modules/grid-system/grid.css" rel="stylesheet" type="text/css" />

Also, if you need to publish different versions of your JavaScript module (dev, prod, minified) you can add them to the "files" field as well.

How to install a module without a package.json

Sometimes you find the perfect module that fits your needs, unfortunately it doesn't have a package.json. Therefore you can't install it with npm. You have two options that can solve this:

Solution 1: Fork the repository

The first solution is to fork the repository, add the missing package.json and submit a pull request. In the meantime you can install the package using the Github namespace: npm install yourUsername/the-perfect-module --save. But sometimes people don't want to "pollute" their repository with a bunch of configuration files and reject your PR.

Solution 2: Napa

Napa is "a helper for installing repos without a package.json with npm". Once you have installed it, you are able to add the perfect module as a dependency of your project. Napa will download the entire repository in node_modules directory. Napa's readme file is well detailed, I don't think it's necessary to c/c everything here.

For instance, a project using Three.js:

{
  "name": "my-project",
  "version": "0.0.1",
  "scripts": {
    "install": "napa"
  },
  "napa": {
    "threejs": "mrdoob/three.js#r67"
  },
  "devDependencies": {
    "napa": "^0.4.1"
  }
}

Why npm rather than another package manager:

It has already proved its worth with Node.js.
No need to install new tools, you just need a package.json.
You can manage all your dependencies with npm: tasks runner (Gulp, Grunt, etc.), JavaScript modules, tests, CSS, assets... everything!

I think it's important to keep things simple, starting with using only one package manager. Especially when you just need to download packages. (Some, like Component, have a build system in addition to the dependency manager.)

So, why do you need Bower?

Build a Web app with component(1)

Mon, 17 Feb 2014 00:00:00 GMT

Component(1) is a front-end package manager created by TJ Holowaychuk. It embraces the philosophy of creating small and reusable modules. It is not restricted to JavaScript, indeed we are able to create components that also contain CSS, HTML, JSON, images, fonts, ... Therefore we can create JavaScript libraries, UI component or reusable CSS utility classes. It allows us to organize applications around multiple components.

All in one place

Currently, the common architecture is to split files into different directories. For instance, this is how the files tree may look like for a menu:

├── assets
│   └── images
│       └── menu
│           └── background.jpg
├── scripts
│   └── views
│       └── menu.js
├── styles
│   └── modules
│       └── menu.css
└── templates
    └── menu.html

With component(1), we can regroup the logic and UI that define the menu component.

├── app
│   └── menu
│       ├── background.jpg
│       ├── demo.html
│       ├── index.js
│       ├── menu.css
│       ├── template.html
│       └── test
│           └── menu.js

We find all information about this component in one place. We should also add tests to be sure the component is bug free, before integrating it to the rest of the application. A readme file or demo page could help our colleagues, other developers or the future "me" to understand easily what the component does and how it works. Nothing really new, but in my opinion it simplifies the process a lot.

Registry system

There are a few things to know about component(1) registry system. It is based on GitHub style namespacing username/repository. It avoids name conflict, therefore you can choose the one you desire. To share a component with the community, you need to push it on GitHub, then add the repository link into the wiki page to register it. The component will be accessible on component.io or via the command component search.

However you don't need to register a component to be able to install it.

Installation

To install component(1), Node.js is required.

$ npm install -g component

component(1) cli commands

Component(1) comes with multiple commands. You can printout the list with component --help.

Here is those I use often:

search [query]: search registered component.
wiki: open the components list page. Another way to find components.
create [dir]: create a component skeleton.
install [name ...]: install one or more components.
build: build the component. I will talk about it later.

Create a component

In this example we will create a progress bar component. First of all, we have to create a component.json file in which we add all the information about the component.

{
  "name": "progress-bar",
  "repo": "kewah/progress-bar",
  "description": "Visual indicator of progress",
  "version": "0.0.1",
  "keywords": ["progress", "bar"],
  "scripts": [
    "index.js"
  ],
  "styles": [
    "progress-bar.css"
  ],
  "templates": [
    "template.html"
  ]
}

We can also use the command component create progress-bar to create the component's structure.

Install dependencies

We will need two dependencies:

component/domify: to turn the HTML template into DOM elements.
nk-components/dom-transform: to update the scaleX property value of the bar.

$ component install component/domify nk-components/dom-transform

Build the component

Component(1) module definition is based on CommonJS spec, like Node.js. You can find more information about CommonJS module in this article.

We need to define the logic and the UI of the component. Let's create index.js, progress-bar.css and template.html as we specified in component.json.

index.js:

// require installed dependencies.
var domify = require('domify');
var transform = require('dom-transform');

// require local template.
// component-build(1) converts HTML template to string.
var template = require('./template.html');

// ProgressBar function will be accessible to others components.
module.exports = ProgressBar;

function ProgressBar() {
  // Convert string to DOM element
  this.el = domify(template);
  this.percentBar = this.el.querySelector('.js-percentBar');

  transform(this.percentBar, {
    scaleX: 0,
  });
}

ProgressBar.prototype.percent = function (value) {
  transform(this.percentBar, {
    scaleX: value,
  });
};

progress-bar.css:

.progressBar {
  position: relative;
  width: 100%;
  height: 10px;
}

.progressBar-percent {
  width: 100%;
  height: 100%;
  background: red;
  -webkit-transform-origin: 0 0;
  transform-origin: 0 0;
}

template.html:

<div class="progressBar">
  <div class="progressBar-percent js-percentBar"></div>
</div>

To be able to test the component we need to build it:

$ component build --dev

--dev option adds source map which is really helpful for debugging. You can find more options with component build --help.

Component-build(1) converts HTML files to strings and JSON files to objects. You can require them directly inside a JavaScript module: require('./template.html') and require('./data.json').

While developing a small component like this, I use rewatch to execute the build command every time I save a file. There is no point in using Grunt or Gulp in that case.

$ rewatch *.js *.css *.html -c "component build --dev"

Finally, we add a demo page to see how it looks.

demo.html:

<!DOCTYPE html>
<html lang="en">
  <head>
    <link rel="stylesheet" type="text/css" href="build/build.css" />
  </head>
  <body>
    <script src="build/build.js"></script>
    <script>
      var ProgressBar = require('progress-bar');

      var bar = new ProgressBar();
      document.body.appendChild(bar.el);

      var percent = 0;
      var intervalId = setInterval(function () {
        bar.percent(percent);
        percent += 0.2;

        if (percent > 1) {
          clearInterval(intervalId);
        }
      }, 300);
    </script>
  </body>
</html>

Test your component

There are different possibilities to test a component: Mocha, Zuul, component-test, ... And certainly others I don't know yet. I currently use component-test. It is simple to use and doesn't need configuration. You can run the test in the browser, PhantomJS or Sauce Labs. If you want more information, the readme is well documented.

Whatever solution you prefer to use, don't forget to test your code.

We can now push the code to GitHub and add the link to Component's wiki. Don't forget to add a tag (git tag) for each version you release. Otherwise you won't be able to specify a version number when you use it as a dependency. Which is really dangerous, if one day you decide to change the component's API, it will break applications that use it. If you are lazy, you can still use mversion.

Structuring an application

Let's pretend we want to develop an application which contains:

Two pages: home and about.
A script to load images.

├── component.json
├── app
│   ├── boot
│   │   └── component.json
│   ├── lib
│   │   └── image-loader
│   │       └── component.json
│   └── pages
│       ├── about
│       │   └── component.json
│       └── home
│           └── component.json

The file at the root of the project is the main component.json of the application. This is where we will run the command to build the application.

{
  "name": "appName",
  "paths": [
    "app"
  ],
  "local": [
    "boot"
  ]
}

The paths property is used by the builder to know where it has to look at to find local dependencies. Here we specify boot, the entry point of the application, located in app/ path.

Each components define their own dependencies, local or published, therefore we don't need to add more information in this component.json.

Local components

Boot

The boot component will be the first script executed in the application. It manages routing (visionmedia/page.js) and transitions between each pages. It also defines the base of the interface, using normalize.css, global.css and fonts.css. We add the pages components, home and about, as local dependencies.

{
  "name": "boot",
  "dependencies": {
    "necolas/normalize.css": "*",
    "visionmedia/page.js": "*"
  },
  "paths": [
    "../pages"
  ],
  "local": [
    "home",
    "about"
  ],
  "scripts": [
    "index.js"
  ],
  "styles": [
    "fonts.css",
    "global.css"
  ],
  "fonts": [
    "fonts/open-sans.eot",
    "fonts/open-sans.svg",
    "fonts/open-sans.ttf",
    "fonts/open-sans.woff"
  ],
  "images": [
    "images/background.jpg"
  ]
}

To use a static assets, like the background image, you just need to use relative file path. component build symlinks those files to the build folder and replace the url() values (except if you specify an absolute path).

body {
  background-image: url('images/background.jpg');
}

Pages

The pages use the local component to load images and emitter to communicate with boot.

{
  "name": "home",
  "dependencies": {
    "component/emitter": "*"
  },
  "paths": [
    "../../lib"
  ],
  "local": [
    "image-loader"
  ],
  "scripts": [
    "index.js"
  ],
  "styles": [
    "home.css"
  ],
  "template": [
    "template.html"
  ]
}

I pushed an example on GitHub to show how an application could be organized. I also used Sass for the demo.

Sometimes you may wonder if you need to move a component to its own repository. Personally, when I'm working on a project, I only creates local components. When the project ends, I extract components that can be useful for a new project. At North Kingdom we started to do that after the launch of The Hobbit project. We share our components in nk-components.

Custom builds

When it comes to build larger applications, you may want to use CSS preprocessor or template engines. Component-build(1) has --use option, where you define the list of plugins it has to execute.

$ component build --use component-scss

If you don't want to use component-build(1) but prefer tasks runner like Grunt or Gulp, I suggest you to use grunt-component-build or gulp-component. It is possible to create your own build script using builder.js.

Building the application

To build the application you need to be at the root of the project (where the main component.json is located) and run:

component install: installs the dependencies defined by local components.
component build: build the files that will be included into the index.html.

The final step is to create the index.html that will be served to the user. Don't forget to require boot, otherwise the application will never start.

<!DOCTYPE html>
<html lang="en">
  <head>
    <link rel="stylesheet" type="text/css" href="build/build.css" />
  </head>
  <body>
    <script src="build/build.js"></script>
    <script>
      require('boot');
    </script>
  </body>
</html>

My thoughts

I really like the way we organize applications with component(1), where each component is developed and lives separately in the project.

At North Kingdom, we don't use a specific framework like Backbone or Angular. Each project has different constraints, some need to be connected to a database, some need to handle deep links... component(1) lets us to be flexible and just use what we really need. We find a lot of good resources published by the community and the number of shared components is still growing.

Component(1) has some drawback like the file size. Aliases, at the bottom of build.js, could take >10% of the file size. Which is a lot compared to other solution like browserify. Also, it may seem tedious to have to reference each of the dependencies and modules for each of the components. This is a design choice, but this could be simplified with a generator like Yeoman.

I see it as a preview of the future of Web development. Web Components will be available in modern browsers in a few years with even more powerful features. The team behind component(1) plans to support Web Components and this is a great news.

From Sublime Text to Vim

Wed, 05 Feb 2014 00:00:00 GMT

Sublime Text has been the first text editor I really enjoyed to use. Fast, simple to customize and lots of great plugins.

Progressively, my habits have changed. At first, for instance, I used to rely on the UI to find a file and double click to open it. Then I discovered the fuzzy finder (cmd + t) which helped me to switch quickly between files. A simple thing that improved my workflow a lot.

Throughout my use of Sublime Text, I wanted to have a more comfortable experience, especially during code editing (selection, navigation, etc.), by reducing the back and forth between the keyboard and the mouse.

I first looked into Sublime Text settings to try out some options:

Expand selection to {quote, white space, brackets, indentation} that lets you select a portion of your code, inside quotes for example.
Jump to next/previous empty line which is useful when jumping from one block of code to another.

And of course there are several plugins that helped me. I particularly enjoy Easy Motion "that allows you to move the cursor to any character in your current view". It lets you navigate quickly inside your code, and for me, it is as important as the fuzzy finder. In fact, when I started to use this plugin, I wanted to do everything in that way. Being able to delete a text, starting from the position of the cursor to a defined character somewhere on my screen, would have been awesome.

Unfortunately I did not find a plugin to fulfil my need.

The discovery of Vim

After some research, I decided to give Vim a try. In order to facilitate the transition, I started to use Vim as I did with Sublime Text, following Yehuda Katz advice. I installed MacVim and searched an equivalent for each of my favourite plugins:

Vim-Plug: One of the Vim's "package manager".
EasyMotion: I already talked about it.
CTRL-P: Fuzzy finder.
UltiSnips: Snippets for Vim
Emmet: Well, you know...
Ale: Syntax checker.
Multiple cursor: The little brother of the "multiple cursors" on Sublime Text.
NERD Tree: In case I need a file explorer.

In parallel, I read the book Practical Vim, which allowed me to familiarize myself with the Vim commands and discover the range of possibilities they offer.

Everyday, I set out a goal to focus on a specific command. It allows me not to overload my memory with a lot of new commands and not spend too much time looking for the right way to do it. With the intention of remaining productive in my work.

Step by step I reduced my use of the mouse, disabled the arrow keys and finally started to use more and more word wise motions to navigate inside my code.

Magic motions

In Vim, when you execute an operator command (copy, change, delete, select, etc.), you use motions to tell where you want the cursor to move.

Motions are pretty simple to remember. For example i mean "inner", so if you want to delete the text inside the braces: di}. This is very powerful and can be applied in different context, such as search keys (f and t). There is a really interesting article about text objects by Jared Carroll. Efficient editing in Vim is a matter of learning how to speak proper Vim.

The use of motions is the first thing I truly enjoyed with Vim and that was exactly what I was looking for. That made me switch definitively to Vim.

6 months later

I've mostly found everything I used to use in Sublime Text. However, I had to spend some hours to configure Vim. It is annoying to start with an empty shell but I've found lots of .vimrc on GitHub to used as an example.

It might be sometimes difficult to achieve tasks that were relatively simple in Sublime Text. I had to learn new tools like The Silver Searcher, to be able to search and replace strings in my project.

It is nevertheless really pleasant to edit my code in Vim. I still have a lot to learn but this is also something I like, I am always thrilled to discover new things and I never get bored.

Some links that might be useful:

Practical Vim: My Vim's bible.
Vimcasts: Screencasts by the same author of Practical Vim.
A good vimrc: Lot of informations to set up your vimrc.
Mastering Vim in Vim
VimGolf: Inspiring use of motions.
Vim Adventures: Learning Vim while playing a game.