I know, it sounds cliché at this point, but you can just build things.

What do I mean by just build things? I mean, don't obsess over the right language, framework, tools, or approach to use.

Just build something, and ship it.

In the absolute worst case, you get it wrong. Guess what? you can just fix it.

I'm writing this article after realizing it has been four and a half years that I've been working on a product folks told me "won't work at scale", and "can't be viable". They were mostly wrong, and the things they were right about? I fixed.

The right programming language to use

A painfully common question I see is "what programming language should I use in $INSERT_YEAR_HERE to build my side project?"

The correct answer is: the one you already know. If you already know PHP, just use PHP. Same goes for jQuery, Java, Node, etc.

(Of course there are caveats. If all you know is VB6, and you want to build modern web apps, you might want an egghead.io subscription first.)

I'm a strong believer that getting things done quickly and well is the only thing that matters. If you're spending half of your project's time learning the language, or figuring out if how you use it is the "language-way" of doing things, when you could be building, you're wasting your time. If your goal is to learn the new programming language, do it intentionally. Trying to build a business at the same time will only distract you.

I'm speaking from experience here.

I've known since about 2016 that I wanted to build a business on the Internet (for context, I started my professional career building with AngularJS 1.5 and Django, and shortly afterwards pivoted to React and Node.js). My first month or so of trying to build an Internet business was just to figure out which language/framework to use. I ended up using what I used at work (React + Node.js), but that was a frustrating month of indecision.

Building it "correctly"

I'm writing this for folks with little-to-no users. Obviously, at web scale, getting it wrong hurts. Like, "a multiple-year project to handle the rewrite, migration, and user messaging" levels of pain.

The great thing about wanting to carve out a small portion of the Internet to run a bootstrapped business on, is that our projects aren't that hard to fix if we screw things up.

I'd argue at small scale, there's rarely a "right" way to build things. Just get things out there, and see if people will use them.

I started off OnlineOrNot on AWS Lambda because I knew it would cost me nothing if I got no users. I got users, enough to keep my AWS Lambda functions active 100% of the time. It started to cost me a shit ton of money more than if I just used a VPS. If I used a VPS from the start, I doubt I'd have shipped.

So I rewrote to use a VPS. It took about 10 hours. It didn't work for my use case. I undid the change, and eventually moved to Cloudflare Workers.

More recently, I noticed OnlineOrNot's main dashboard was taking longer several seconds to load (almost at one billion uptime checks complete at time of writing). After spending a bit of time optimizing the query and indexes, I got the query down to 500ms.

Was using postgres for clearly analytical (OLAP) workloads right? Clearly not, but it did the job until things started to get slow, and since moving to Clickhouse, that query now runs in 50ms.

In short

Your technical approach doesn't have to be perfect the first go.

Just make sure it works, and iterate.

When I played around with the technology that would eventually become OnlineOrNot back in 2021, a quick search showed me that there were 200 listed alternatives to the tool I wanted to replace. I thought most of them sucked.

There are even more today.

Over the years, many more started and shut down a few months later (it turns out running a business in a highly competitive space doesn't make you rich overnight). Others raised VC money or were acquired by a private equity firm, and started their descent into enshittification.

I started work on OnlineOrNot because I wanted to build software that didn't have to get worse for its users in order to maximize shareholder value. In short, it's a self-funded, sustainable business that I intend to run for decades.

It's default-alive, as I keep a full time job so that I can build the business the way I want.

I've published one of these articles every year since starting, and there were things that I "learned" in the first year, that turned out to be total bullshit by the third year. So this article doesn't just look at the last 12 months, but across the entire lifetime of this business.

Table of contents:

• Principles that haven't changed
  • Two hours a day, every workday.
  • No other side projects.
  • Solve customer pain.
  • Be ruthlessly iterative.
• Lessons
  • Read a few books, and start building
  • Solve pain, don't try to sell a subscription
  • Ship small, ship often
  • Ship first, worry about scale later
  • Have an early-access program
  • Build a free trial as soon as possible
  • Docs are the product
  • Build for mobile
  • Ask people how they found you
  • I don't use invasive analytics
  • Talk to potential customers, even if you think you have nothing for them
  • You don't get to spend as much time solving the problem as you think
  • Pricing is hard to get right
  • Don't tunnel-vision your MRR
  • Never give away "unlimited" anything
  • Rate limit your paid resources
  • Stop trying to explain everything on one page
  • It's hard to bring in more traffic, easy to change what your current traffic does
  • Competitors don't really matter

Principles that haven't changed

While I've learned a lot about running a business over the years, there are some unchanging principles:

Two hours a day, every workday.

Years before I even started OnlineOrNot, I started hacking on my own projects in the two hours I have before starting my workday. Having a consistent block of time for myself has let me publish hundreds of articles, a book, dozens of software projects, and more.

Since starting, I worked out that the amount of time per day isn't as important as putting any effort in, every day, for years.

But how do you find time before your workday?

I started waking up two hours earlier, and adjusted the rest of my day accordingly.

No other side projects.

the person who chases two rabbits catches neither

Of course, there are exceptional folks out there chasing a dozen rabbits and managing to catch some of them - I know myself well enough to realize that I'm not that person.

Building out the marketing and sales processes to take a business from $0 to $500 MRR is challenging enough. I don't see a point in repeating the hardest part of starting a business over and over again, instead of doubling down on what's already working (this is also a lesson for picking a marketing approach, more on that later).

Solve customer pain.

When a user signs up for OnlineOrNot, I have an automated email going out asking what brought them to sign up today. I explicitly tell them I read and reply to every email. This is the main source of my insight for building product.

I ask my customers what isn't working, and I make it work.

Be ruthlessly iterative.

If I can't get a piece of work released in two hours, I cut the scope down to something achievable, and iterate on that.

It's worth noting that this is the ideal, and I don't always succeed at cutting down scope to exactly two hours. Over time I've realised that with how my brain works, I enjoy shipping early versions as quickly as possible, and building out the functionality once it's deployed (behind a feature flag).

Waiting until the entire feature is built before deploying completely saps my motivation in comparison, and I find myself easily distracted when building this way.

Lessons

Read a few books, and start building

I read dozens of business books when I wanted to get started, mainly from not wanting to repeat mistakes that others have made.

Sometimes though, you need to make mistakes for yourself.

As an example, it took me getting on the front page of Hacker News, having 6000 people visit my landing page, a few hundred people attempt to sign-up, and only single-digits making it through to the app for me to realise something might be wrong.

I had something like a 75% drop-off rate on my sign-up form alone. I got it down to 50% just by adding an extra OAuth login provider.

If I had to do it all again, I'd start with only three books:

• The Mom Test by Rob Fitzpatrick
• Deploy Empathy by Michele Hansen
• Badass: Making Users Awesome by Kathy Sierra

and if you need specific detail on building and running a SaaS, The SaaS Playbook by Rob Walling.

Solve pain, don't try to sell a subscription

The product's goal is to solve your customer's pain, rather than sell subscriptions to your SaaS.

This is a mindset shift from "I'm just going to keep building features, they'll come eventually!" to "I should be helping my users solve this annoying problem in their job"

Building a SaaS is just one of the ways you could be solving their problem. There are other ways you could help, like recording screencasts, writing docs, articles, books, running workshops, providing code samples, etc.

Ship small, ship often

People will suggest you should build particular features to improve your product.

They'll never use those features.

They're probably just trying to be helpful, and saw a similar feature in another product. Because you're new to running a SaaS, you'll be excited that people are actually talking to you, and rush out to build that feature for them.

I'm not going to tell you not to build the feature (that's the advice I was given, and I built unused features anyway). You should ask how they would use the feature, ask other customers how they deal with the problem, build the smallest possible version of that feature, and see how the rest of your customers use it. You don't want to be building snowflake features only one person uses.

It stings a lot less to remove a feature no one wanted after spending a few hours on it, rather than a few months.

Ship first, worry about scale later

In the first iteration of OnlineOrNot, I didn't optimise the architecture at all.

There was actually a bug that limited the total number of uptime checks the system could handle to around 100. I also didn't have proper error screens, so when users ran into that issue, all they saw on the screen was:

Error!

Not a great look.

At the same time, I prefer being embarrassed by incomplete UI than building things people don't need. There was never a guarantee that OnlineOrNot would attract thousands of users, it could have ended up as another SaaS I built only for myself.

My immediate solution was to upgrade my database to a higher tier, increasing the number of uptime checks that could connect to the database, and in the meanwhile I got to work on rearchitecting the product.

A few hours later, I had a solution in place that could handle millions of checks per week on the smallest AWS database, and made that error screen look a bit more professional.

Have an early-access program

Shipping early is incredibly useful. Early on in your product's development, almost all users that sign up are expecting rough edges (especially if they've seen your unpolished landing page).

As time goes on, you're going to get folks expecting a mature product, so you can't just keep shipping imperfect features to your entire userbase.

My solution for this was to add a checkbox in each user's account with the label "Join the Early Access Program". Folks that opt in get to see OnlineOrNot's latest features before they're ready, in exchange for patience and feedback.

Build a free trial as soon as possible

The common wisdom these days is to not even bother with a free tier - it's too difficult to get right. When I started though, a free tier was a great way to attract people and get them talking about your product.

The thing is, you still need a way to let them sample "the good stuff", especially if the free tier is significantly less useful than your paid tiers.

It took me 11 months to realise I should build an onboarding flow that ended with asking if folks wanted a free trial. Particularly, it asked:

Do you want to start a free trial?

What it was actually saying was:

Do you want to experience OnlineOrNot's best features for 14 days before deciding if it's worth your time, or spend months with a product that has the good stuff disabled, unsure if it'll actually solve your problems?

I eventually decided to experiment with defaulting all users to a free trial first, so that everyone could experience the entire product first. This one experiment more than doubled OnlineOrNot's monthly growth rate.

It turned out that starting the business relationship with "this is a paid service, you'll need to add payment details to continue getting the good stuff" helps the business significantly more than "this is a free service, if you use it a lot, you might have to pay for it".

Docs are the product

Back when I started, folks used to say that "developers don't read documentation".

This turned out to be bullshit.

Some of the early customers in my ideal customer profile (ICP) came in praising OnlineOrNot's documentation, and I doubled down on it since. I even went as far as building my API docs from scratch to have full control over the user experience.

Back when I had product analytics, I noticed people would struggle to do something in OnlineOrNot's UI, get frustrated, check the docs, and one of two things would happen:

1. They would find the exact feature they're looking for in the sidebar, and keep using the product for a long time
2. They would not find what they were looking for, not create any checks, and just churn

In short, successful use of the docs drove retention.

Build for mobile

Contrary to popular belief (for B2B SaaS), folks actually work from their phones, and I think the rate is increasing.

Something like 50% of users start their journey to my product on mobile. They would quickly create an account, add a few pages to monitor, then eventually get on their laptop/desktop to review their checks from time to time.

For the first 6 months I didn't support mobile well, and folks that signed up on their phone churned rapidly. I eventually took the time to build responsive views for mobile, and new mobile users stuck around.

Ask people how they found you

One of the most valuable code changes I made halfway through the first year was asking people as they signed up: "How did you find out about OnlineOrNot?"

You need to know where your users are finding you.

There are dozens of marketing channels you could be using to attract potential customers. You only have a fixed amount of attention, so if you find a channel that's working more than others, you need to focus that attention on that channel until you notice diminishing returns.

I don't use invasive analytics

When I started, I integrated with standard SaaS product analytics software that most big SaaS products use. They tend to have features like session recording, where you can see exactly where their mouse moves in your product, and funnel tracking for working out how many users make it the whole way through from landing page to using your product.

This turns out to be useful in bigger companies. You have stakeholders to align with your vision of how the product should be built, it's easy to point to some data and show that version A resulted in sign-up uplift over version B.

The thing is, most products don't get enough users through the funnel to prove that the result you see is actually because something is better, rather than random chance.

As a solo founder with only two hours to spare every morning, I just didn't have the time to go through all that data and try to convince myself something. Instead I have an "inner-circle" of users that I DM for a vibe-check on features and problems in the product, and build things by taste.

Talk to potential customers, even if you think you have nothing for them

I was contacted by a CTO early on, asking if OnlineOrNot supported some particular feature.

My normal reaction would've been to just say "sorry, no" and leave it at that. Out of curiosity I started asking what pain they're trying to solve, I also asked the inner-circle users if they ran into this pain too, and what they'd like to achieve with the feature, and I told this CTO how I figured I would build it.

They signed up to a paid plan the next day, they've been customers ever since, and the feature gets used by other customers too.

You don't get to spend as much time solving the problem as you think

Of all the time I spent programming in the last four years, significantly less than half went to actually solving the problem I wanted to solve (knowing if a site is down, and alerting folks when that happens). The majority went to building a SaaS platform around that problem.

SaaS platform things you didn't even realise you'd need, like multiple types of authentication and user management, trials, onboarding, recurring database jobs, team management and invoice management, lifecycle emails, and more.

A lot of folks outsource this type of work (and I do! If Stripe didn't exist, I probably wouldn't be selling a service nor using subscription-based billing), but there's always stuff you don't feel comfortable outsourcing, or that you handle differently, so you need to build it yourself.

Pricing is hard to get right

Price too high, and you'll either have churn from folks who expect your app does everything or completely kill your sign-up rate. Too low, and you'll have customers that demand you rewrite your app just because they gave you $9.

Refund the difficult customers, raise your prices, and move on. Be prepared to experiment a lot with pricing, especially early on and as you build functionality.

Don't tunnel-vision your MRR

Tracking your MRR is a crap way to measure how you're doing as a business.

Things you did weeks (if not months) ago will affect your MRR today, so you won't really know if pricing changes work until you've already got a decent number of customers going through different stages of their customer journey.

Depending on your product, it could take up to 60 days for a user to go from signing up for the first time, to entering their credit card details.

Find another success metric to figure out if people are actually using your product, and whether it's bringing them value. Things like number of images generated, or number of form completions, for example.

Never give away "unlimited" anything

There will always, always be a whale customer for whom an unlimited amount of your value metric for $250/mo will be the deal of a lifetime. Generally speaking, never offer unlimited anything, especially if it costs you additional money for each thing created.

Lifetime deals fall under this advice too.

You aren't "finding users" for your product, you're finding people that expect you to build exactly the feature they want from you, years down the line, for that $100 they gave you once. Of which you likely only saw 30%, if you used a third-party to run the lifetime deal on their marketplace.

Rate limit your paid resources

If you call any sort of paid API (whether it's AI, sending SMS/email etc) as part of your service, you're going to want to rate limit calls to that service.

But my users are paying me for this service, shouldn't they be able to use it as much as they want?

Of course there are exceptions (and it depends on your Terms of Service), such as if an extremely large company starts using your service, but generally speaking, this will save you from a large unexpected bill at the end of the month, or being labelled a spammer by your vendors.

If someone genuinely needs to use your service at an extremely high rate, they'll get in touch.

This particular insight comes from the time OnlineOrNot sent thousands of SMSes to a web agency when the one server holding hundreds of their WordPress websites started running out of RAM.

Stop trying to explain everything on one page

If you try to be everything to everyone, you'll end up being nothing to no one

I think this applies particularly well to copywriting for landing pages.

As I built additional features into OnlineOrNot, I would try add additional sections to my main landing page, and it ended up an incoherent mess, diluting the overall message. I would have folks emailing me to ask if I supported sending alerts to Slack, when it was the second feature I built for OnlineOrNot.

Instead, by breaking up each feature into its own landing page:

• main landing page
• uptime monitoring
• api monitoring
• status pages
• cron job monitoring

I can take the space to explain each feature, without diluting the message.

It's hard to bring in more traffic, easy to change what your current traffic does

Getting noticed on the internet is a long, slow game.

Eventually over months (if not years), if you're consistent at quality content marketing, the number of readers on your articles will grow from 1-2 a day, to a few hundred per day.

Increasing the number of people landing on your site isn't particularly easy.

On the other hand, what people do once they land on your site is entirely within your influence, and something you can change today (such as adding an additional OAuth login provider to your sign-up form, that I mentioned earlier).

Competitors don't really matter

You might have noticed I haven't mentioned anything about competitors here, despite operating in a highly competitive market.

The truth is I don't think they change much.

Sure, there are more "table-stakes" features that customers need before they'll even consider using you, but the real competitor is a lack of awareness of your product, more than anything.

It's Friday morning, the days are getting longer, and the weather better here in Toulouse. Let's go into some thoughts from the past few weeks.

About last year

I wrote up my product-focused 2024 wrap up for OnlineOrNot a few weeks back and I'm still planning on writing a more business-focused "what I learned from four years of running a SaaS" to mark OnlineOrNot's fourth birthday.

A good summary of 2024 for me is: I spent way too much time worrying about feature gaps in the product (the status page product had many), and not enough time marketing.

For example, I built out ten changelog-worthy features, and took the time to add none of them to my landing page. Useful for existing customers (since they become aware of these features through the changelog + product update newsletter), but from the perspective of interested prospects visiting the landing page, the feature gap is still there.

So the goal of 2025 is to take a more balanced approach between marketing and coding. Instead of rushing off to the next feature, take the time to update the landing page as well as the docs, changelog, and product newsletter.

First incident of the year

Last week OnlineOrNot had its first incident of the year: uptime checks were moving slower through the pipeline than usual, meaning checks that should run every 30 seconds were running every 5 minutes or so. I spent the end of last year tweaking the system to ensure this would never happen, but I missed a spot.

The postmortem probably says it best:

The root cause was a loss of connectivity between our Cloudflare Workers service, and the AWS database that stores metadata about uptime checks. There was a replica system ready to run in AWS, however due to a misconfiguration it could not start automatically.

The misconfiguration has been fixed, and OnlineOrNot will run regular (monthly) drills to ensure the fallback system functions as expected.

I was also more than an hour away from my laptop when my PagerDuty alert fired, so that'll also teach me to bring my laptop with me. That's something folks don't realize about starting a SaaS that other businesses rely on - you're always on-call (until you hire folks to help):

Developers will literally spend weeks designing and building a perfect system instead of just solving for the problem they have today.

Normally I would say: it is me, I am developers.

But then I wrote out the problem to a friend on Whatsapp and realized I was just procrastinating.

I built for the problem I have today

An extremely common pattern for me (that even after almost four years, is hard to recognize and stop): building overly complex systems as a means of procrastination.

For example:

I recently had a problem where I wanted to display the limits a user is subject to (for example, if they're on a free trial, don't give folks as many SMSes as a paid account, to avoid abuse).

I started planning to build a complicated entitlements system based on a key-value store, that I could update at any time, for any user. Why? Because I've worked on systems with tens of thousands of daily active users as part of my day job for years now, and that's the first thing that comes to mind.

That's wasn't the problem I had to solve today though.

I already had functioning means of limiting what types of users could do what. The problem I had to solve today was to display that limit to the user.

I was chatting through the complicated system I planned on building with a mate over WhatsApp when I realized I was just procrastinating. I didn't need a fancy entitlements system (yet).

A single variable in a shared package would do the job.

Will it scale? No.

Will updating it be a pain in the ass? You bet.

Is it enough for the problem I have right now? Yes.

So I'm pretty thankful I have folks to brain-dump this type of thing to - it's difficult to notice when you're making the problem harder than it needs to be (even when you only have two hours a day to focus on the problem).

Only three months since the last diary. Slightly better than last time.

Here's how running a SaaS has been going over the last three months.

Table of contents

• I fixed four-year-old code
• I realized AWS Lambda is too expensive.

I fixed four-year-old code

Some code issues only show up when you operate at scale (another reason to just ship). In my case, OnlineOrNot's dashboard is full of N+1 queries thanks to my liberal use of GraphQL without thinking about it too much.

There's enough data in the system now that inefficient queries and poor architecture decisions make for a worse user experience, so I've been taking the time to fix things.

For example: it got to a point where my own personal view of OnlineOrNot was taking 10 seconds to load 10 uptime checks (this screen):

The fix was remarkably simple: instead of using sub-resolvers (and individual query per field with a squiggly bracket) for queries like:

checks {
  id
  name
  url
  data {
    timestamp
    result
    ...
  }
}

I started fetching all of the data for checks in the root resolver, and it now takes 300ms instead of 10+ seconds.

Makes me wish I just wrote the whole thing using REST APIs to begin with (likely something I'll migrate to over time).

I realized AWS Lambda is too expensive.

OnlineOrNot is in the enviable position of being default-alive - the minimum cost of operating the business if usage goes to zero is about $30/mo (a small but reliable Postgres DB running in AWS RDS).

As a result, I've never really worried about the business's profitability - as long as more money came in than I spent per month, it was fine. Then I started paying attention to folks on social media bragging that they were running their extremely large businesses on a $5/mo VPS (nevermind the cost of the DevOps person on 24/7 on-call in the background ensuring it never catches fire).

I realised I was paying way too much for serverless compute, because 99.99% of my AWS Lambda execution time was spent waiting for IO (loading websites to see if they're online, running SQL queries).

On Cloudflare Workers, that's free.

So long story short, I rewrote OnlineOrNot to run on Cloudflare Workers, and suddenly I have breathing room for a marketing budget, or even employing folks.

I can't believe it's been more than four months since my last diary. For once, it wasn't because I fell down a rabbit hole of building a huge feature.

Truth is, I've been meaning to write sooner, and actually drafted several versions, but couldn't find the energy to hit "Publish". I had to prioritise myself and my family before OnlineOrNot for a bit, but I'm bouncing back.

Table of contents

• Targeting Enterprise
  • The Status Page MVP, wasn't viable
  • Sometimes you just need to ship
• At the same time, you need to market
• Solving problems is SEO

Targeting Enterprise

Last time I wrote to you, I was working on enterprise deals for OnlineOrNot. They fell through.

I did learn things along the way, which was the main reason that I bothered in the first place.

The Status Page MVP, wasn't viable

It wasn't viable for OnlineOrNot's ideal customer profile.

They expected more features, that did more things. I wrote about this at the end of last year, so it wasn't a total surprise. I am currently building those features, so we'll get there.

Sometimes you just need to ship

I used to be a devoted follower of marketing week, coding week. It's cool and all, but sometimes you just need to focus on shipping. It's easier to keep building a feature continuously than to take a break after each week for marketing.

Not in total isolation of course - as you release, you announce each feature to your mailing list/Discord and get feedback along the way.

At the same time, you need to market

Sometimes you learn the same lesson that you already wrote about, but in a different way. It feels strange to write the same things over and over, and I imagine it's not amazing to read them over and over either.

That being said, I'm beginning to realise that starting a business of any sort, is a search for marketing channels that work, first and foremost.

You might be in the business of "building good ships, at a loss if we must, but always good ships", but unless someone somehow finds out about your good ships, your business is dead.

The reason I can ignore marketing OnlineOrNot for a few months is because I didn't ignore it in the past, and that content still brings in users consistently.

Solving problems is SEO

So, long ago, before OnlineOrNot, I wrote a blog about React as a side project.

It kicked ass in SEO, because people were searching for how to solve their problems, and my articles would fix their problems. That's the gist of how to succeed at SEO.

Somewhere along the way, I convinced myself that if I went really really wide and blogged about barely irrelevant topics like Ten Ways to Improve WordPress Page Speed, I'd catch folks early in their business, and they'd consider using OnlineOrNot. After a few articles that failed to bring in consistent traffic, I gave up and told myself "content doesn't work".

It turns out content does work.

I've started investing in content that makes sense for OnlineOrNot (like how to check if a website is online), and it's been leading to new customers. Not an "I can retire tomorrow" number of customers, but I get as many monthly trials (even during the summer holidays!) that I did during months where I would be actively trying to insert OnlineOrNot into as many online conversations as I could. I've since stopped doing that, and am focusing purely on building features, and we're still growing.

I still don't do nearly enough content marketing. It's bought me some time to build features, but I should be writing at least one article per week on top of features, so that the usefulness compounds.

When it works, like on MaxRozen.com, it really feels like you're building trust at scale.

It's finally sunny, and a Friday morning here in Toulouse, time to discuss what I've been doing over the last 4 weeks or so.

I started by taking more demo calls for OnlineOrNot's enterprise plan, reflected on why I didn't do that sooner, and ranted about optimizing for engagement.

Table of contents

• Dipping my toe into enterprise sales
• I should've done that years ago
• How giving up "sugar-surge marketing" is going
  • A quick rant on engagement games

Dipping my toe into enterprise sales

A few diaries ago, I updated my pricing page to have an enterprise plan. I had no idea what people would want, so the copywriting was pretty simple:

I added a card to my pricing page with the content: "Have needs that don't neatly fit into our plans? I can help.", with a call-to-action of "Let's talk".

A few people have reached out, I had a quick chat with some folks to learn what they were looking for in an enterprise version of OnlineOrNot (nothing salesy on my end - I just wanted to learn), and I got absolutely slapped down by their requirements. OnlineOrNot fulfilled maybe half of what was being asked.

One particularly helpful person (that I'm eternally grateful for) walked me through their procurement spreadsheet, as well as letting me know what similar solutions are charging, along with the "must-have", "should-have", "nice-to-have" status of each feature, so I now have more information about what customers expect from OnlineOrNot than ever before. I'm particularly excited for the roadmap.

I should've done that years ago

I left those quick demo meetings feeling amazing, like I knew exactly what customers expected, and I'd be able to build those features pretty quickly too. At the same time, I was wondering "why on earth didn't I do that sooner?!" - the answer is simple:

I wasn't ready.

For those of you that don't know me in real life, I'm a massive introvert. Unless we've already talked in real life, I'll probably have a notebook of things to talk about if we end up doing a phone call together.

These demo calls were nothing like that. I just showed up to the call, and asked "Hey, how can I make the next 20 minutes useful?", and chatted about what their business does, what kind of monitoring needs they have, and how they want to display their uptime to their customers.

Frankly, I'm surprised I pulled it off, but I guess when you think about uptime monitoring for at least two hours a day for three years like I have, it starts to become natural, and you don't need a notebook of questions to keep the conversation going.

How giving up "sugar-surge marketing" is going

As I wrote in the previous diary, I'm no longer playing engagement games on Twitter, and writing articles solely so they rank on Hacker News.

It's not like I'm not good at it - I've written articles that reached #1 on Hacker News several times now. I'm not going to lie, it feels AMAZING when it happens. 40k+ people on your site, discussing your product, potentially sending business your way.

The trouble is, most of that traffic is irrelevant at best, distracting and a waste of time at worst. Hacker News are not your customers. Maybe 0.01% of them kinda-sorta fit your Ideal Customer Profile, but you now have to work out if a helpful-looking comment fits the profile of the type of customer you want to serve.

So instead, I've been writing helpful content for software teams. Traffic is down, way down. Sign-ups are surprisingly stable, and conversions from trial-to-paid are increasing.

Now, customer feedback comes directly to me via email, and I can immediately see in their email signature that they're title X at software company Y, and that the thing they're asking for will likely make OnlineOrNot better for folks like them.

A quick rant on engagement games

Somewhat related to sugar-surge marketing: asking extremely basic questions for the sake of generating engagement does not do anything for your business, unless you're in the business of selling "how to quit your job and make 500k!" courses for $500 a pop.

You might get some new followers out of it, but these are not the people that'll stay on your mailing list for years. Folks that stick around, get value from what you're building, and give you feedback as you build do not come from engagement games.

It's a rainy Friday morning here in Toulouse, and I had thoughts about the last few weeks.

Table of contents

• Sugar-surge marketing
• Am I just screwing around?
• Refactoring the business entity

Sugar-surge marketing

It's been a while since I wrote a diary, hopefully the article describing my third year of running OnlineOrNot kept you entertained in the meanwhile.

I'm not going to lie, articles like that are a successful part of my marketing. Between reddit, Hacker News, and various newsletters that syndicated the content (much love!), tens of thousands of people have read that article, a few thousand searched OnlineOrNot, a few hundred tried it out, some have even become paying customers.

It's a complete sugar surge, in that the folks coming in aren't my ideal customer (members of software teams) so my conversion rates are less than half what they normally are, but it is nice to have folks go through the funnel at scale, as it lets me see what works on my landing pages, and what doesn't.

What I actually should be doing, and have started doing, is working out what "jobs" folks hire OnlineOrNot to do, and create consistent content (as in, one article per week) for that.

What's been stopping me until now is that getting tens of thousands of random people reading your content feels good. My more-relevant (for my target audience) content gets maybe a few hundred reads in comparison, but converts at a much higher rate.

Side note: founder psychology is fun!

Am I just screwing around?

Looking back on last year, I wasted a shit ton of time. I spent months on a monolith rewrite that didn't pan out, I spent weeks writing and testing ads for a product that didn't meet the bar for "viable" in "minimally viable product", and more.

Apart from promising to complete MVPs (and asking customers where the gaps are) before marketing them, my new tactic for this year is asking myself "am I just screwing around here?" when picking up a new task off my backlog.

Things that don't immediately fix a customer pain, help folks find OnlineOrNot, or explain a feature to users go to the bottom of the backlog now. It's been working out, customers have been noticing:

Refactoring the business entity

Since writing the third year of OnlineOrNot article, I've even had inbound interest from folks to learn more about our enterprise plan for the first time in a very long time. Filling out vendor risk assessment forms made me realize running OnlineOrNot as a micro-entrepreneur here in France wasn’t going to cut it in the long term (the equivalent of a sole trader in UK/Australia).

The benefits of doing so are huge, and I'm kind of annoyed with myself for not doing it sooner. One of those afraid of success things I guess.

How huge, you ask? I currently pay around 44% tax on revenue for OnlineOrNot. As a business, it goes down to 25% tax on profit. I don't plan on paying myself, and I intend to re-invest 100% of everything it makes back into the business, so it'll be a nice boost to the marketing budget.

It all started three years ago when I shipped a minimum viable product (MVP) in a week, at least, I thought it was minimally viable.

OnlineOrNot started as a toy - I had just learned how to use Next.js, and was wondering if it would be possible to build a SaaS app into my marketing website (it was, and honestly the benefit wasn't that huge compared to having them separate).

It wasn't until a few dozen releases later that folks started paying me for the product. That gave me the motivation to keep shipping. Feature after feature (released after 2 hours of work and iterated upon afterwards), the product became minimally-viable for more and more people.

Fast forward to now, I have customers, and have been growing at a steady rate while building the features customers ask for, but the product is no-where near complete, but I'm getting there.

Previous editions of this article:

• What I learned running a SaaS for a second year
• What I learned running a SaaS for a year

Table of contents:

• I stopped being afraid of success.
• I ripped out my product analytics
  • How it works
• I experimented with onboarding, and it massively paid off
• I stopped trying to explain everything on one page
• I came crawling back to AWS.
• I started to understand my product philosophy
• To wrap this all up...

I stopped being afraid of success.

I originally doubted that being afraid of success is even a thing. I'd tell my self "of course I'm doing the best I can", while self-sabotaging my business in a dozen little ways that would compound into enormous effects.

Before this year, I would ignore and avoid:

• building tiny "table stakes" SaaS features (team management, on-call integrations, audit logs, etc)
• writing landing pages to explain the product
• making business decisions in general

At some point this year I had a realization that I was burning a lot of first impressions on incomplete software. My article writing was attracting curious people to try out OnlineOrNot, but I was losing them on missing features (and in a segment as competitive as mine, folks aren't often patient for incomplete software).

So I've calmed down a bit on the content marketing and immediately releasing software too early. I still release fixes and product improvements in 2 hour increments before work each day, but for completely new things, I wait until they're "ready" before promising something and under-delivering. I read somewhere that this is how 37signals built HEY Calendar - while they do 6-week cycles for improvements, for new products they run as many cycles as it takes.

I ripped out my product analytics

It turns out that as a small independent business I spend a good deal of my time actually talking to customers to figure out how it's going, learning what they expected when they signed up and what features are missing, rather than digging through analytics.

While I had analytics in the product, I wasn't using the data. So I ripped it out.

Me and other small business owners around me call it vibes-driven product management. It's not for everyone, but in my (obviously biased) opinion, I think I have good enough taste to pull this off.

That isn't to say I have no data. I still have anonymous cookie-less analytics of how many pageviews I get.

How it works

For the last three years, I've asked every single person that signed up to OnlineOrNot:

What's the one thing you were hoping OnlineOrNot could do for you?

Some folks respond, and those conversations have driven almost every feature and improvement that I've built since. While I have my own ideas and backlog, some of these conversations will make me realize I was thinking the wrong way about a feature, and that a drastically simpler implementation is possible.

I experimented with onboarding, and it massively paid off

OnlineOrNot's onboarding used to present users with a crucial question at the end:

Do you want to start a free trial?

Phrased like that it probably doesn't sound very crucial. What it really meant was:

Do you want to play around with OnlineOrNot's best features for 14 days before deciding if it's worth your time, or spend months with a product that has the good stuff disabled?

People did end up upgrading their subscription eventually from using the free tier exclusively, but it took significantly longer than folks that use the free trial version (it's a lot harder to see the value with half the features disabled).

So around May 2023 I decided to experiment with defaulting all users to a free trial first. This one experiment more than doubled OnlineOrNot's monthly growth rate.

It turns out starting the business relationship with "this is a paid service, you'll need to add payment details to continue getting the good stuff" helps the business significantly more than "this is a free service, if you use it a lot, you might have to pay for it".

I stopped trying to explain everything on one page

There's a saying that goes something like:

if you try to be everything to everyone, you'll end up being nothing to no one

I think it applies well to copywriting for landing pages.

As I built additional features into OnlineOrNot, I would try add additional sections to my main landing page, and it ended up an incoherent mess, diluting the overall message. I would have folks emailing me to ask if I supported sending alerts to Slack, when it was the second feature I built for OnlineOrNot.

Instead, by breaking up each feature into its own landing page (main landing page, uptime monitoring, api monitoring, status pages, cron job monitoring), I can take the space to explain each feature, without diluting the message.

I came crawling back to AWS.

I started OnlineOrNot on AWS Lambda, because I was never sure I would ever attract a customer. So if it had zero usage, it would cost me almost nothing per month to run.

I began evaluating other solutions after a particularly viral article sent hundreds of users to OnlineOrNot. My user base spiked, and so my AWS bill also spiked. I started by looking at fly.io, and moved my workload over. I liked it so much I even wrote about it.

Fly.io was an amazing user experience and a joy to use (especially the us-east region) and I still run a non-critical service there, but trying to run an uptime monitoring service on a platform that would regularly have network connection issues was a non-starter, and was beginning to hurt OnlineOrNot's reputation. It might make sense for running a web service, where a region's requests can failover to replicas, but it just didn't work for me.

I found myself needing to run each check several times in my VM, as well as backup checks on AWS AND Cloudflare to actually be sure my user's URL is actually down, rather than it being an issue with the VM I'm checking from. At that point I questioned why I even used fly.

I also tried running regular, boring VMs from Hetzner and DigitalOcean by refactoring my Lambda functions into a monolith (side note: vendor lock-in is a myth).

As a result of running OnlineOrNot in a single, ridiculously over-provisioned (yet significantly cheaper than AWS) server, uptime checks were randomly timing out, overall latency increased significantly, and made the overall system less reliable. Adding additional monitoring especially for VPSes would cost roughly how much I'd save by moving off AWS Lambda.

I spent a week tweaking code, increasing VPS size several times, trying different VPS providers, before eventually giving up, and deciding that paying a premium for AWS Lambda is worth it for the type of lifestyle business I want to run. Trade-offs and all that.

I started to understand my product philosophy

I read a quote this year from Justin Duke's mood board for his software business that resonated well with me and what I'm trying to do with OnlineOrNot:

We shall build good ships here at a profit if we can at a loss if we must but always good ships

The business is bootstrapped and sustainable (it's default-alive), so I'm not too worried about profit. I'll still be here doing this in 10 years time. This year I realized there's nothing left to focus on except quality.

This year:

• I optimized my most frequently run SQL query, going from running for 5000ms every 15 seconds to 500ms
• I handrolled my own API documentation so that I could have full control of the product
• I fixed bugs that took 15 months to surface - a fun part of operating at scale is "one-in-a-million" bugs happen several times a day, though sometimes it takes a bit longer
• I finished two separate MVPs (status pages and cron job monitoring) that I started, so that I have a solid foundation to build a business on top of
• I started shipping JavaScript, and no one noticed - I started by not shipping JavaScript in the Status Page product as a mark of differentiation, but in the end it was just getting in the way of releasing features customers wanted

To wrap this all up...

Thanks for reading this, it's time to get back to shipping.

It's a rainy Monday morning here in Toulouse, time for another diary.

Table of contents

• 2023, what a year
• A fresh start, more shop cleaning
• What's next?

2023, what a year

Over the Christmas/New Year break I wrote a year-in-review article for how all of my projects went in 2023. The gist of it was: I focused on only OnlineOrNot for a whole year, and the business grew twice as fast as I expected, and the article seemed to resonate with a lot of people, getting about 20k unique views.

In that article I promised a proper year in review article for just OnlineOrNot on its birthday (February 25). I'm pretty thankful I've been writing these diaries on a regular basis since OnlineOrNot's last birthday, here's hoping it makes it easier to remember just what I did over a whole year.

A fresh start, more shop cleaning

As I mention in my last diary, I ended the year feeling inspired for 2024, ready to improve OnlineOrNot and the Status Pages feature to a point where bigger tech companies (I'm thinking a few hundred employees) feel more comfortable using it.

A big part of that is cleaning up the API and the tooling around it, and building new API endpoints. I originally shipped OnlineOrNot's API solely as a means of building a CLI. The docs were hand-written, and lovingly placed alongside my other hand-written docs. Side note: I'm starting to notice this is a recurring theme - I'll build something quickly, and have to come back to clean it up later. That's probably preferable to taking months to ship anything.

Unfortunately, this made updating the API a bit of a pain in the ass. Updating the API meant first writing code, and remembering to context-switch into "content-mode" and deciding where the new API endpoint docs should live, actually writing docs from scratch, and deploying the content.

To start the year, I've been cleaning up my mess, and automating this process away:

• I migrated the API to HonoJS, used Zod for API validation, and a neat middleware for converting that validation into an OpenAPI spec
• I built a pipeline to convert that OpenAPI spec to markdown, and that markdown to HTML (effectively building my own OpenAPI to Docs generator from scratch), so that OnlineOrNot's API documentation gets generated as I write my code
• I wrote about the process

I could have used a third-party to handle generating my HTTP API docs, but one of my strong convictions is that docs are as much a part of your product as the rest of your UI, and I want to be able to easily respond to feedback and change anything as needed.

What's next?

In the coming weeks, I'll be:

• automatically publishing OnlineOrNot's OpenAPI schema to GitHub
  • so that it's easier to generate tooling off a specific version of the API without having to worry about it spontaneously updating
• building API endpoints for status pages
  • starting with status pages themselves, followed by creating incidents for status pages

In short, I'm trying to make OnlineOrNot fully compatible with being managed via an Infrastructure-as-Code (IaC) solution like Terraform, and I figure Status Pages are good place to start.

At the end of each year I summarize how the year went, reflecting on how I progressed towards my goal of being self-sufficient as a web developer, here are the previous editions of this article:

• (2022) Just keep shipping
• (2021) Strangers from the internet paid for my MacBook Air
• (2020) Indiehacking: a review of my 3rd year
• (2019) Further reflections on trying to start an internet business
• (2018) Reflections on trying to start an internet business

ROZENMD (my business here in France that runs OnlineOrNot, and sells my products) continued to grow in 2023, approximately twice as fast as I expected at the start of the year.

I have two theories as to how this happened:

1. On the OnlineOrNot side, what I learn about running the business compounds. Fixing something that wasn't working results in a slight increase in adoption, improving that fix increases adoption even more, and so on.
2. My book about useEffect seems to make even more money the longer it exists. This is likely partly lindy effect, and partly from more and more folks entering web development and using React.

As I approach the point where my business could feasibly pay my salary (still a few years away), I don't think I see myself quitting full-time work - I work better knowing I have two hours to ship something each morning.

Table of Contents

• One big bet
  • Running the business long-term starts paying off
  • Dear diary
• I changed teams at work
• I built the boring enterprise laptop of my dreams

One big bet

At the start of 2023, it was trendy to make many "small bets" when starting an internet business.

Popularized by folks like Pieter Levels and Jon Yongfook, and then turned into a paid product/community itself by others, the idea is to keep throwing products at the wall, until you see what sticks.

Folks will point to investment portfolio management theory, saying if 5 or so investments is enough diversification to smooth out risk/reward, surely the same idea follows for building products.

The trouble I find with that argument is the amount of effort to get from $0 -> $500 MRR is significantly greater than $500 -> $1000 and above. Having to repeat the most difficult part of starting a project, where you need to figure out the means of attracting the right type of users (and figure out who they are), and the features they need to solve a problem several times (and you're going for diversification, so the products can't be related) sounds a bit suboptimal to me, compared to doubling down on what works.

I also don't buy the idea that individual makers need diversification. Avoid platform risk (where you build on top of someone else's platform, like Twitter), don't work on things you're not personally interested in, and you're well on your way to reducing the greatest risks to your business running long term.

Running the business long-term starts paying off

This year I started having wins that were only possible from sticking around long enough:

• I had folks that rejected my pitch for OnlineOrNot pre-launch (back when OnlineOrNot was literally just a single input form that sent only email alerts) sign up and become customers of OnlineOrNot. Turns out they got fed up with their existing service, remembered my pitch, and checked out what I built since.
• I also had some of the earliest free-tier users of OnlineOrNot subscribe and becoming paying customers.
  • This one is kind of my fault though, as early users of OnlineOrNot never got a free trial of the high-value features, it's a lot harder to win them over compared to folks that started on a free trial.
• I fixed bugs this year that took 15 months to start impacting people

A lot more happened this year, though I'm saving that for an article I'm publishing in February 2024, in celebration of OnlineOrNot's 3rd anniversary since launching publicly on Twitter. You can get the article directly in your email by subscribing below, if you haven't already.

Dear diary

I've always had folks interested in how I build OnlineOrNot (particularly on the business/marketing side), though I felt that running a newsletter when you only make yearly updates didn't make a lot of sense.

So I started writing more frequently, and dedicated part of this blog to diary articles. They don't get tons of views, but I write them primarily as a means of reflecting on what I said I'd do, what I did, and what I learned along the way.

I changed teams at work

It'd be weird (to me) to do a year-in-review post without discussing my full-time job at Cloudflare: without it, I would simply not have the ability to pursue a slow-yet-steady growth project that requires patience like OnlineOrNot.

At the start of the year, a partner team started integrating their early-alpha product into wrangler (the command-line tool for building Cloudflare Workers), I helped out by fixing bugs and contributing ideas for a better user experience, and long story short, I ended up being one of the founding engineers of D1.

Considering my product and writing skills (see the last five years in review), I reckon it's a pretty good fit!

I built the boring enterprise laptop of my dreams

So I didn't just work on software this year, I also had a couple of cute hardware projects like this where I upgraded a laptop over a few hours, or put together an AirGradient sensor.

I'm actually writing this article from that same laptop - at the start of the year, I grew a bit fed-up with Apple, and wanted to build a cheap enterprise-looking laptop no one would want to steal when traveling (it's one asset tag sticker away from looking like my wife's old work laptop).

So I bought a cheap Lenovo T480 off a refurbisher, bought a bunch of parts to upgrade it, put it all together, and wrote about the project:

• On replacing my MacBook Air M1 with a Thinkpad T480
• Getting your own good enough laptop for under $500

The first article ended up getting translated and posted to golem.de, which was pretty cool, and I had a stray mention to running OnlineOrNot's dev server in the article, so that accidentally drew thousands of people to Google what OnlineOrNot is.

The first article also drew quite a bit of anger from random strangers online, and I found it pretty funny. As though I was telling people they had to go throw out their Apple laptops immediately because you can get a good-enough laptop for under $500.

While tooling for web development is getting more and more complex, with CLIs for your CLIs becoming a thing, sometimes it's worth taking a step back, and realizing that doing things from scratch isn't so hard.

In this article, we're going to create and deploy a Cloudflare Worker without a CLI.

Table of contents

• Steps to "Hello World"
• Summary

Steps to "Hello World"

1. Make a new directory, and cd into it

mkdir my-worker/
cd my-worker/

2. Initialize the npm project

npm init -y

3. Install some packages

npm install -D typescript wrangler @cloudflare/workers-types

4. Create a tsconfig.json file

touch tsconfig.json

After running the above command, paste the following into tsconfig.json:

//tsconfig.json
{
  "compilerOptions": {
    "noEmit": true,
    "module": "esnext",
    "target": "esnext",
    "lib": ["esnext"],
    "strict": true,
    "moduleResolution": "node",
    "types": ["@cloudflare/workers-types"]
  }
}

5. Make a src/ directory, create an index.ts file inside

mkdir src/
touch src/index.ts

After running the above command, paste the following into index.ts:

// index.ts
export default {
  fetch: () => {
    return new Response('Hello World!');
  },
};

6. Create a wrangler.toml file

touch wrangler.toml

After running the above command, paste the following into wrangler.toml:

# wrangler.toml
name = "my-worker"
main = "src/index.ts"
compatibility_date = "2023-12-22"

7. Login to wrangler

npx wrangler login

8. Deploy your Worker

npx wrangler deploy

You can now visit the URL that wrangler outputs, and you should see "Hello World" in your browser.

9. (optionally) Install vitest, add a test script

npm install vitest -D
touch src/index.test.ts

After running the above commands, paste the following into src/index.test.ts:

import { unstable_dev } from 'wrangler';
import type { UnstableDevWorker } from 'wrangler';
import { describe, expect, it, beforeAll, afterAll } from 'vitest';

describe('Worker', () => {
  let worker: UnstableDevWorker;

  beforeAll(async () => {
    worker = await unstable_dev('src/index.ts', {
      experimental: { disableExperimentalWarning: true },
    });
  });

  afterAll(async () => {
    await worker.stop();
  });

  it('should return Hello World', async () => {
    const resp = await worker.fetch();
    if (resp) {
      const text = await resp.text();
      expect(text).toMatchInlineSnapshot(`"Hello World!"`);
    }
  });
});

Finally, in package.json replace the test script with:

"test": "vitest"

Summary

There you have it, a Cloudflare Worker from scratch.

While it's not strictly better than just running

npx wrangler@2 init my-worker2 -y

(which is the exact CLI command you'd run to get the project above)

At least this way you understand what's happening before reaching for tooling to automate it.

It's a foggy Sunday morning here in Toulouse, time to close out the year.

In the last two weeks I:

• Learned screencasting
• Cleaned up tech-debt and realized I have a long way to go
• Had thoughts on focus

Learned screencasting

As I mentioned in the last diary, I started a YouTube channel for OnlineOrNot, and I'm still learning. In fact, in the last two weeks I learned enough from the egghead instructor guide that I felt the need to re-record some of the original videos I released.

To start off with, I was having issues with:

• un-normalized audio (one video would be significantly quieter than another)
• weird output size (I think I was recording in 4k)
• my pronunciation was off

Though there are some meta-skills that only apply to YouTube that I refuse to adopt:

I'm treating YouTube like I treat other social media: it's just a place to distribute my content, not the source/single means of hearing from me.

This is why I try get folks to subscribe to my email newsletters instead.

Cleaned up tech-debt and realized I have a long way to go

I continued the theme of finishing my MVPs:

• Since Status Pages now use JavaScript, I was able to finally make the graphs interactive (you can mouse-over the data, and inspect each individual data point)
• The emails that Status Page subscribers get now actually tell subscribers what went wrong (before it would just say there was a new incident), without having to visit the status page
• I took a few shortcuts while building the UI for creating status pages, incidents/components/subscribers, and in certain cases it would take ages to load, so I cleaned up those shortcuts

With Status Pages more-or-less at a point where I'm satisfied with what I've built, I took the time to research how folks buy status page software, and actually got really lucky in finding a public procurement report where a CTO outlined every decision they took to pick a vendor.

It made me realize OnlineOrNot's Status Pages have a really long way to go to support big software teams that already use other software as part of their ops stack.

The OnlineOrNot Status Pages MVP is in-fact, minimal. You can't customize the look-and-feel, there's no API for it, so no terraform support, and almost no integrations. Despite this, I somehow have paying customers that use just status pages.

So in short, I'm feeling inspired for 2024. OnlineOrNot's Status Pages will meet folks where they already are, and integrate with software that customers already use.

Had thoughts on focus

In last year's review post, I wrote about how OnlineOrNot's success comes from showing up, doing the work and releasing it. Particularly having a single-minded focus on OnlineOrNot, rather than a portfolio of several distracting small bets.

The neat "hack" keeping me focused on "just" OnlineOrNot is that it's now 3 separate products with a variety of interesting tech powering it, so I never get bored:

• All parts of the product involve a Next.js web app and a Node.js API server talking to a plain old Postgres DB
• Uptime monitoring involves various microservices in a Highly Available configuration on AWS
• Status Pages involves using the latest frontend tech with Remix
• Heartbeat monitoring involves mixing microservices with my API

Going too long between these diaries is a sure sign I've fallen down a rabbit-hole (this is when a developer is so focused on solving a problem, they keep digging without thinking to look back and evaluate whether the problem is worth fixing in the first place).

So it's a Wednesday morning here in Toulouse, and it's the first time in two months where I'm not thinking "oh man, I just need to fix this one thing and it'll be good", time to go over what's new.

To be fair to myself, I did get a lot done:

• Wrote cron-jobs: the guide
• Started a YouTube channel
• Focused on improving Status Pages
  • I started sending JavaScript, and no one noticed
  • Completely on Cloudflare Workers
  • Dedicated staging environment

Wrote cron-jobs: the guide

I wrote the last diary totally sure I would spend the following weeks writing article after article for OnlineOrNot's cron job monitoring feature. I wrote a couple of small articles and realized "this should really just be a single guide", and so I combined them into Cron Jobs: the guide, and built a visual editor for cron jobs (for example: run cron every five minutes).

This hasn't taken off like I imagined it would (content marketing in the devops space is ridiculously competitive), but if it helps folks that do find it, I'm happy.

Started a YouTube channel

When I first started OnlineOrNot, I made a couple of YouTube videos showing how to use it. The videos had a few hundred views and were popular with new customers, but got out of date relatively quickly as I continued to build OnlineOrNot over the years.

Now that the interface has more-or-less stabilized, I started making YouTube videos again, essentially turning OnlineOrNot's documentation into a YouTube channel: @OnlineOrNot.

Some folks tend to prefer videos over written documentation, so my prediction is that this will help onboard folks (and act as a kind of "demo" for folks that are reluctant to meet with me to see what the product can do).

Focused on improving Status Pages

Speaking of OnlineOrNot's Cron Job Monitoring and my mission to actually finish my MVPs from the last diary, I wasn't particularly proud of OnlineOrNot's Status Pages until recently.

I built the feature in a rush a year ago, and was so sure it would start bringing in additional customers for OnlineOrNot.

It kind of did, but folks tended to use features as things to check off in a checklist when evaluating OnlineOrNot (in other words "Oh, you don't have feature X? You must not be as good as OTHER_PRODUCT that does have feature X...").

This kind of demotivated me at the time, and made it difficult to actually invest time in improving the feature when what most folks cared about was:

• Can you monitor our service?
• Can you stay online while the rest of the Internet is crumbling?
• Will your business stick around for 5-10 years?

In the last year I've focused on addressing these points, and the answers are: "yes", "yes, OnlineOrNot is highly available", and "I plan on doing this for at least the next 10 years, if not longer".

So in the last two months, I worked on improving Status Pages, and making it easier to add new features:

I started sending JavaScript, and no one noticed

Status Pages used to be small (around 13KB), but they weren't necessarily fast. It still took a few hundred milliseconds to query a database, and convert that result into HTML.

I managed this by completely disabling JavaScript in our React framework (Remix). While a fun thing to brag about, this actually slowed down my ability to release new features at a high quality. Charting libraries that support being server-side rendered are surprisingly rare (and buggy). Tooltips required a workaround that added hundreds of DOM nodes to the page, slowing down the app.

Recently I snapped, and started sending JavaScript to users. This means users download approximately 265KB when they first load an OnlineOrNot Status Page (a 20x increase). No customers have complained, instead, folks are happy about new features being shipped.

Completely on Cloudflare Workers

OnlineOrNot's Status Pages are built on Cloudflare Pages, but the API was a highly available service running in several nodes across the USA.

I recently moved the API entirely into a Cloudflare Worker using a mix of Hyperdrive, and Hono.

This has let me enable caching, is a significantly better developer experience (I can build and deploy the API in 1.9 seconds now, instead of 5+ minutes), and lets me dogfood products from my day job.

Dedicated staging environment

Status Pages work by having a Cloudflare Worker intercept all requests coming in, and routing them (with a special header encoding which status page to load) to a web app. Testing changes end-to-end locally with this setup was extremely difficult, the best I could do was unit test my Worker, and a few integration tests for the web app loading status pages.

I managed to get around this recently by building a copy of OnlineOrNot Status Pages' production environment: I now have a separate dedicated domain which has a Worker routing to a Cloudflare Pages app, and that talks to its own API.

Long time no diary! Between late July to early September, I took the longest break from regularly working on OnlineOrNot since starting the project in February 2021.

In that time I visited:

• Paris
• Florence
• Rome
• Biarritz
• San Sebastian
• Toulon

I came back pretty eager to get back to regularly shipping features and marketing projects for OnlineOrNot, so here we are.

While I was away I read Yvon Chouinard's Let My People Go Surfing, and it reminded me of why I started building OnlineOrNot in the first place: to build higher quality software than the established products.

In short, with OnlineOrNot, I want to build high-quality software. At a loss if I must (I have a full-time job after all), but always high-quality software.

On de-emphasising the free-tier

OnlineOrNot has a free tier. It's for personal, non-commercial projects (like monitoring your personal blog), but I've always wondered if that drove the wrong type of folks (as in, not product teams building software) into trying OnlineOrNot.

So while I was away, I ran an (ultimately flawed) experiment to remove all mentions of OnlineOrNot's free tier from the marketing website (without actually removing it from the app), to see what would happen. My expectation was that sign-ups would take a small hit, while increasing the overall paid conversion rate.

I'm not going to sugar-coat it, sign-ups halved.

It being the month of August during my experiment (Europe/North America on holidays), me being away (spending zero time on marketing) likely influenced sign-ups more than removing the free tier.

I still need to wait a couple of weeks to see the impact on overall paid conversion rate, so I'll likely try running the experiment again once I've settled into a regular coding week/marketing week schedule again.

On actually "finishing" MVPs

I've mentioned it a few times in previous diaries: OnlineOrNot is built in two-hour increments, before I start work every morning. To avoid never releasing, my release cycle is quite different to regular software companies - instead of a "big bang" release once a feature is ready, or an agile/sprint fortnightly release, I try to release every single morning.

This works pretty well in practice for marketing, fixing bugs, and smaller features, but for large features (like introducing heartbeat monitoring), I found myself releasing far too early, before the feature was ready for customers: a bit too "minimal", and not enough "viable" product.

The fix is simple of course: the Early Access Program. My mistake was promoting the heartbeats feature from Early Access to public beta too quickly, and ending up with customers using low quality software.

As a result, I've spent my first week back rapidly iterating on Heartbeat Monitoring to make sure it's actually viable as a product. I've made the following changes:

• I've fixed a few bugs preventing heartbeat checks from alerting properly
• I've integrated heartbeat checks into status pages, so customers can track their cron jobs on a status page
• The heartbeat check graph now correctly shows incidents, not just successful runs
• I've moved heartbeat checks into their own infrastructure
  • I didn't know if anyone would use it, so I built it inside OnlineOrNot's existing uptime check system. While convenient, it made the code far more complicated than necessary (split across several microservices).
  • With this change, the heartbeat check system can be monitored and deployed independently, it can fit inside a single serverless function AND it can accurately monitor OnlineOrNot's uptime check system

Next up, I'll be adding email, SMS, webhook, and on-call integrations to heartbeats, so that they match OnlineOrNot's regular uptime check alerts.

Back into content marketing

Even though I know in the short-term that content marketing doesn't really work for attracting customers, I like writing too much to give it up. For coming up with content ideas, I tend to watch forums (like hacker news) to see what folks are complaining about, and write articles that fix their issues.

So now that I'm back, I'll be writing more of my classic "fixing a problem"-style articles.

I'm writing this from a train between Florence and Rome, in Italy - I had a bit of time to kill, and wanted to reflect on the last two weeks.

In case you missed it, last diary I wrote about how I wasted a fortnight yet again trying to use a distributed monolith to monitor my users websites instead of serverless. It turned out ensuring that one customer's checks don't influence another's is a difficult problem to solve, and I'd rather pay the ~100% premium to not need to worry about that on AWS Lambda.

Features people actually want

So I started this fortnight eager to ship things my customers actually asked for. Someone on twitter suggested adding on-call integrations to OnlineOrNot. I had been meaning to do so since March 2021, a whole 26 days after I released the first public version of OnlineOrNot, and have had several requests to add on-call integrations (albeit as "nice to haves" than "blockers").

The reason I never got around to it is really dumb: the docs for the incumbents were god awful, and I couldn't bring myself to figure out the mapping between "services", "teams", and OnlineOrNot's checks.

It took seeing new players in the on-call market (shout-out to spike.sh) with really clear docs before I realized it wasn't actually that difficult - I could start with a webhook URL to POST messages from OnlineOrNot to the on-call service.

So over two mornings I integrated four on-call services into OnlineOrNot: PagerDuty, Opsgenie, Grafana OnCall, and Spike (and wrote docs on my side for how to configure each integration).

Landing pages, again

I added even more information to my main landing page this week.

We'll see if this is a good idea, but for the longest time my main selling point was "modern uptime monitoring" (what does that even mean?!) - I eventually changed that to something people actually care about (ease of use), and gave my conversion rate a noticeable boost. Now that I have on-call integrations, I realized the main selling point is alerts, and the business processes that go into action when an alert is fired.

So now OnlineOrNot's landing page follows a sort of chronology by business processes: alerting your team -> status pages for keeping customers updated

What feels extremely natural to follow those features is a sort of incident management system, but I'm drawing the line at monitoring and status pages - it already feels like a sufficiently large feature set to maintain and iterate on as a solo-founder.

Giving away free tools

This week I also challenged myself to build another free tool in under 60 minutes.

I originally launched OnlineOrNot as a public webpage that could check your webpage from around the world: you enter a URL, I run the check, and tell you what OnlineOrNot saw in us-east-1, us-west-1, eu-central-1, ap-southeast-2, and ap-northeast-1.

Having built Do I need a CDN? a few weeks back, and having a decent number of folks signed up for OnlineOrNot off that page, I wanted to bring the original tool back.

I present you: Website Down Checker.

The name is terrible, but it's visually a lot more appealing than the original OnlineOrNot tool!

It's Bastille Day here in France, and before I break out the BBQ and beers (I'm still Aussie, after all), I wanted to reflect on the last two weeks of OnlineOrNot.

If I summarized it in one word it'd be: distracting.

You see, this week was a marketing week, and I had 11 ideas for awesome things to do to keep bringing folks in, following up on the success "Do I need a CDN?" had. Instead, I got baited by the prospect of cheaper compute and being able to build features like ping monitoring, so instead of marketing, I spent the week building OnlineOrNot into a monolith app and using MRSK to deploy to my servers.

I succeeded, by the way, at building the monolith app: it's actually pretty neat to be able to run OnlineOrNot end to end on a single machine (if you remember from a few months ago, OnlineOrNot is a pipeline of AWS Lambda functions stuck together with SQS and SNS). It works great for monitoring a single user's checks, but once you load up 1600 users checks, cracks start to appear.

As a result of running OnlineOrNot in a monolith, uptime checks were randomly timing out, overall latency increased significantly, and made the overall system less reliable. Adding additional monitoring especially for VPSes would cost roughly how much I'd save by moving off AWS Lambda. I spent a week tweaking code, increasing VPS size several times, trying different VPS providers, before eventually giving up, and deciding the AWS Lambda premium is worth paying for the type of business I want to run.

Thankfully, OnlineOrNot runs really well on AWS Lambda, so it's not all doom and gloom.

On a more positive note, this week Abhi wrote in to ask: How do I come up with ideas for what to build?

I started OnlineOrNot as a pretty basic project to meet my needs, all it could do when I launched it was visit a webpage over HTTP, and send an email if OnlineOrNot couldn't reach your page.

My secret for coming up with new ideas to build into OnlineOrNot comes from asking my customers as they sign up: "What's the one thing you were hoping OnlineOrNot could do for you?"

From those basic beginnings, folks have emailed in to ask OnlineOrNot to support their use case, and if it matches my vision for what I want OnlineOrNot to be, I typically build it.

Another Friday morning here in Toulouse, let's go into how OnlineOrNot went this month (?!?).

I totally dropped the ball there, sorry friends. Trying to get back to a fortnightly cadence.

In this issue of OnlineOrNot Diaries, I talk about what I shipped, failing customers during an AWS outage, trying to ship a new type of uptime check and failing, learning more about the world of direct sales, and giving up on Google ads.

On Shipping

I started June by continuing my "build basic SaaS features people ask for all the time" trend by making it possible to add multiple Slack integrations to OnlineOrNot, and making it possible to pick which Slack channels uptime checks and heartbeat checks send messages to.

I also ran into an embarrassing bug (to me, my users didn't seem to care) that has been hassling my paid users for the past 15 months: if you upgraded to a paid account while on a trial, my trial emails would keep sending, pestering you to upgrade!

I also realised I had been writing these diaries since February without writing a single product update to my users, so I'm doing that monthly now. While it feels good to ship all the time, shipping the right thing matters.

The AWS Outage

OnlineOrNot went down with the AWS us-east-1 outage on June 13, so I wrote about it, and how I'm going to stop it from happening again. I have no idea why, but nearly twelve thousand people read that article. Google decided it was news, and shared it on the Google Discover tab.

The gist of it is, I thought I was operating entirely in a single region (us-east-2), I wasn't, and I let my customers down. In immediate aftermath I moved the component that failed into us-east-2, and added a feature to make it possible for me to failover OnlineOrNot between regions, so the entire OnlineOrNot stack can jump between us-east-1 and us-east-2 without customers being impacted.

This doesn't feel like it's enough though, so I'm building a second OnlineOrNot stack that runs entirely on VMs (think DigitalOcean, or Hetzner).

Trying to ship a new type of check, and failing

For a very long time now, customers have been asking to be able to ping their servers. Not every server exposes HTTP, so regular uptime checks weren't a good fit for them. While heartbeat checks make it better, it still requires logging into the server, and setting up a regular task to ping OnlineOrNot.

So I started by building the UI and backend for adding ping monitoring into OnlineOrNot, tested it in production, and realized AWS Lambda doesn't actually support running the ping command, on the operating system level. Even if you used Docker, it doesn't work. It's explicitly turned off by AWS, actually.

Lesson learned: build a dumb proof of concept showing off the raw feature (in this case, running a ping check on AWS Lambda) before you go off and build the frontend and backend to make the whole thing work.

All is not lost, however. Once I operate OnlineOrNot on a second stack with constantly running VMs, I'll be able to offer ping checks.

Leaning into Direct Sales

I recently read about how Nathan Barry leaned on direct sales to bootstrap ConvertKit in this article, and it made me realise that "direct sales" is effectively just customer research with a few extra steps.

I already do a bit of customer research (I ask everyone that signs up to chat about what they were hoping OnlineOrNot could do), so I realised calling people to discuss uptime monitoring is a good next step for better customer research data.

So I build a page to let folks schedule a demo with me. In two and a half years I've never actually demoed OnlineOrNot to a person live, so I'm a bit worried I'll screw up somehow. Though for the most part, I'm more interested in learning about my customer's businesses and how OnlineOrNot can help them, so I don't think I'll be doing much talking in these calls.

Giving up on ads

Yesterday, I read a comment on a forum arguing that you don't actually need a CDN, because some internet providers are faster than others (or something dumb like that). Rather than argue, I decided to build a free tool to show them why CDNs are useful. I called it "Do I need a CDN?", and in 24 hours folks have checked 1500 websites, and it has driven 10 new sign-ups to OnlineOrNot in that time.

For how little effort I put into this free tool, it has driven significantly more traffic per dollar spent than my ongoing ad campaign. So I'm deciding to give up on Google Ads, and lean more into building free tools like this (and maybe sponsor things my customers use, instead).

Another Saturday morning here in Toulouse, let's go into how OnlineOrNot went this fortnight.

I'll be honest, a decent part of the last two weeks looked like this for me:

Despite my time in the sun, quite a bit happened over the past two weeks, without needing to write too much code, or actively market the product.

• My default-to-trial period experiment continued running
• I listened to some customer feedback and built table-stakes features

My default to trial experiment

In case you missed it, in the last diary I mentioned I started an experiment in my onboarding flow, where I would require every new user to try the best of OnlineOrNot before letting them use the free tier.

I'm not going to bury the lede here, it's going very well:

The above is a graph of OnlineOrNot's MRR. I don't like to talk much about MRR as it's a lagging metric - things I did weeks ago affect it today. Though, without increasing the number of people creating OnlineOrNot accounts, just about every metric in the business shot up this month: average revenue per user (ARPU), customer lifetime value (CLTV), cash flow, etc.

One month of course does not "break a plateau", but things are looking a lot better than this time last month. I also replicated the experiment on an app I built in a weekend last year, and went further by removing the number of screens in that app's onboarding flow. The app's MRR is up 48.4% this month.

It turns out starting the business relationship with "this is a paid service, you'll need to add payment details to continue getting the good stuff" helps you get paid!

On building table-stakes features

There are two types of features I build for OnlineOrNot:

• Features that help customers monitor their application and manage their incidents
• SaaS features that everyone expects a SaaS to have

The secret is, as long as you build features that your customers actually want and give them value, you can get extremely far without building SaaS features like handling teams/invites/deleting accounts/etc.

For example, I released the ability to invite teams on March 19, 2021 - it wasn't until this week, May 25 2023, that I made it possible to remove people from your team. This whole time, folks have been emailing me whenever they needed to remove someone from their team. No one has ever told me "no, I won't pay for this, I can't remove people from my team". You get to spend that time building features that bring in customers instead.

Although this week someone asked for the ability to remove folks from their team, I decided it was time to just build the damn feature.

Another Saturday morning here in Toulouse, let's go into how OnlineOrNot went this fortnight.

In the last two weeks I:

• optimized a query that OnlineOrNot runs every 15 seconds, to run 90% faster
• decided to release a landing page for heartbeat checks before it was ready
• started an experiment with my onboarding flow
• refactored my AWS architecture for an 87.5% cost saving

Optimizing an expensive query

For OnlineOrNot I've opted to use RDS for simplicity, but as part of that simplicity, I don't get fancy lists of my most run queries with how long they take to run (a popular Heroku postgres feature) - unless you know something I don't? Let me know!

As a result, after two years of development, there are still unoptimized queries like this in my code:

// this isn't my actual code, but is a rough approximation of what it does
const checks = await sql`SELECT * FROM uptime_checks WHERE ready_to_run = TRUE`
// queue up the checks to run, then mark them as currently_checking
await Promise.all(checks.map((check)=>{
    await sql`UPDATE uptime_checks SET currently_checking = TRUE WHERE id = ${check.id};`
}));

There's nothing fundamentally wrong with this approach, but each time you send a query to the database, there's a bit of overhead. Running over thousands of records in my case, this added up to spending 5 seconds updating records every 15 seconds.

The fix was to only send a single query to update the database:

// this isn't my actual code, but is a rough approximation of what it does
const checks = await sql`SELECT * FROM uptime_checks WHERE ready_to_run = TRUE`;
// queue up the checks to run, then mark them as currently_checking
await sql`UPDATE uptime_checks AS t SET "val"=v."val","msg"=v."msg" 
            FROM (VALUES${checks
              .map((check) => `(${check.id}, TRUE)`)
              .join(',')})
            AS v("id","currently_checking") 
            WHERE v.id = t.id;`;

As a result, we now only spend 500ms updating the database, instead of 5000ms.

My incomplete landing page

I'm still working on heartbeat monitoring, and making it ready for general consumption. The thing is, starting marketing only when the feature is complete would be a mistake (this is what Coding Week, Marketing Week solves).

So as part of my marketing week this fortnight, I shipped an incomplete landing page with the intention of iterating on it, as I add features:

Experimenting with my onboarding

As I wrote about a month ago, I started running ads for OnlineOrNot. It's still unclear if it's paying off, so I'm keeping the ads running for now.

It was hard to figure out if ads were working, because folks were signing up, and immediately using the free tier, instead of starting a free trial. People do end up upgrading their subscription on the free tier, but it takes significantly longer than folks that use the paid version (it's a lot harder to see the value with half the features disabled).

So for the month of May, I've decided to see what happens if every user starts with a free trial. They'll be able to downgrade to the free tier for personal projects at any time, but the idea is to let them play with the fully-featured version of OnlineOrNot first, so they know what they're missing out on.

I'll let you know how this went in future diaries.

Refactoring my AWS architecture

As I (also) wrote just over a month ago, I keep two versions of OnlineOrNot running for redundancy: one on fly.io, and another on AWS. Due to network reliability issues with fly.io, I moved the majority of the workload back onto AWS.

However, I never took the time to refactor how my AWS app was setup, so it more-or-less looked the same for 18 months or so:

In short, a scheduler Lambda function runs every 15 seconds to find uptime checks it needs to queue up, sends the data over SQS to a set of resultfwdr Lambda functions which batch requests to the uptime checkers around the world. Only resultfwdr knows how to talk to my database, so I don't need to maintain thousands of connections to my database.

It's probably not obvious what's wrong with this architecture from the diagram, but the resultfwdr Lambdas have to start hundreds of uptime checker Lambdas simultaneously, and wait for them to finish before writing results to the database. Since this isn't Cloudflare Workers, I pay for the time AWS Lambda does nothing while waiting for the results to come back.

The main goal of this re-architecture was to minimize database load, as well as unnecessary AWS costs. So I decided to flip the architecture:

With this new architecture, there's no more waiting around for Workers to finish (apart from inside the uptime checks themselves), it's 87.5% cheaper to run the resultfwdr Lambda, and thanks to SNS, the Workers run their checks within milliseconds of being queued.

Another Saturday morning here in Toulouse, let's go into how OnlineOrNot went this week.

It was a coding week (that makes it three in a row, for those counting at home), and I took the time to clean-up a ton of tech debt. This article gets a little bit technical.

For context, I launched OnlineOrNot approximately two years and two months ago, and I never really treated the code like it might stick around for a while. A lot of my git commit messages are just me swearing. These are things you can get away with when you know you'll be the only person reading your code.

I built OnlineOrNot as a "mono-repo", but the folder structure was pretty chaotic, and if I wanted to use packages, I had to publish them to npm. I had the main Next.js app in one folder, a folder for my terraform configuration, and every AWS Lambda function in another:

infrastructure/
lambdas/
|   |-- browser-checker/
|   |-- checker-scheduler/
|   |-- cron-tasks/
|   |-- uptime-checker/
|   |-- uptime-checker-runner/
|   |-- weekly-emails/
|   |-- ...more lambdas here
web/

For a long time that worked well. There were a couple of utility functions I copy pasted between lambda functions, and I had comments to remind me to update the code in multiple places (obviously not a great practice when you have a team), and never had any issues.

Adding fly.io complicated things

At some point last year, I duplicated OnlineOrNot's stack and made it run on fly.io. The resulting folder structure looked like this:

infrastructure/
fly/
|   |-- checker-scheduler/
|   |-- uptime-checker-runner/
|   |-- ...more apps here
lambdas/
|   |-- browser-checker/
|   |-- checker-scheduler/
|   |-- cron-tasks/
|   |-- uptime-checker/
|   |-- uptime-checker-runner/
|   |-- weekly-emails/
|   |-- ...more lambdas here
web/

The trouble with this is, a good 95% of the code between the fly.io and AWS versions of OnlineOrNot were the same, adding a significant amount of code duplication. I figured it wasn't such a big deal at the time, since I'd just delete the AWS code one day, but then I realized OnlineOrNot could survive a hosting provider outage by keeping both stacks online.

So the duplicated code had to stay, until I had time to clean it up properly.

Moving to a "real" mono-repo

Since OnlineOrNot is mainly written in Node.js, I actually had a relatively easy way to split up code into packages that can be shared between apps: npm workspaces.

The gist of the change was:

1. Run npm init -y in the root of my mono-repo, and add a workspace config to the package.json:

   "workspaces": [
       "apps/*"
       "packages/*",
   ],
   

2. Move all the apps into the apps/ folder, and cut common code out of apps, and move them into their own packages in the packages/ folder

In the end, it looks like this:

infrastructure/
apps/
|   |-- checker-scheduler-aws/
|   |-- checker-scheduler-fly/
|   |-- uptime-checker-aws/
|   |-- uptime-checker-fly/
|   |-- web/
|   |-- ...more apps here
packages/
|   |-- common-queries/
|   |-- time-utils/
|   |-- ...more packages here

With the old folder structure, things were starting to feel a bit risky: if I updated duplicated code in one place but not others, parts of OnlineOrNot could behave differently as I changed hosting providers.

With the new structure, I don't even need to publish packages to npm to use them in my apps - it Just Works quite nicely.

Another Saturday morning here in Toulouse, let's go into how OnlineOrNot went this week.

(I'm still working out the right tempo for these diaries)

It's been one coding week, and one marketing week since I last wrote in this diary, and I've built a few things. To be honest, I cheated a little bit, and used the marketing week to get heartbeat monitoring to a point where folks can use it.

Heartbeat monitoring

Heartbeat monitoring felt like the never-ending story for a couple of weeks. Every time I thought something would be obvious and easy, there would be another bug or edge case to solve. Not to mention decision after decision to be made about the product itself.

Things like: what to do if a heartbeat happens before we expect, how to integrate heartbeats into OnlineOrNot's existing systems, how to build graphs for the UI, should we allow assertions against incoming data, etc.

I decided to keep it simple in the end (and leave the door open for further features if folks ask for them): by default, OnlineOrNot heartbeat monitoring just gives you a URL that listens for GET, HEAD, or POST requests. Users pick how often the URL should expect a request, (with an optional grace period in case their process takes too long to run), and after OnlineOrNot receives the first request, it'll send an alert if any subsequent requests take too long to arrive.

I've released the feature to folks on the early access program, and it's far from finished (it still needs docs, email and SMS alerts, and the UI is a mess), but now I get to iterate and market it regularly!

A quick update on ads

So far it looks like it's working: the first week of ads lead to a decent sized cohort of users trying OnlineOrNot, and converted to a paying customer as expected, now they just need to stay a customer long enough to pay off the cost of acquiring them via ads.

I say "looks like" because I can't be 100% sure without integrating Google Ads conversion tracking into OnlineOrNot, which I don't want to do, since I would need to add cookie banners to the website. Thankfully folks tell me where they came from when they sign-up, so I don't need the tracking.

Another Friday evening here in Toulouse, let's go into how OnlineOrNot went this week.

It was a marketing week this week, and I felt like trying something different: Ads.

On top of that, I shared the story of my journey from aspiring indiehacker to running OnlineOrNot on Twitter, and about 30k people saw it.

I also cheated a little bit and got the head-start on next week's coding week by starting on OnlineOrNot's next feature: heartbeat monitoring.

Ads: was it worth it?

I wanted to test the changes I made to OnlineOrNot's landing and pricing pages without needing to wait around for traffic, so I paid for 105 people to check out OnlineOrNot via pay-per-click advertising.

Was it worth it? Let's run the numbers: 27 people signed up to OnlineOrNot this week. 17 people signed up the week prior, so let's say 105 clicks resulted in 10 additional sign-ups.

If 10% convert to paying customers, I can expect those sign-ups will result in one paying customer, on average. Assuming each click costs $1 (it doesn't, but the maths is easier), that's $105 to acquire one paying customer.

For my three plans ($19/mo, $49/mo and $149/mo as of today), the pay-off period is 5.5 months, 2.1 months, and 0.7 months respectively for that one customer.

In short, purely on a monetary basis, it might be worth it, but I'm not sure yet.

As OnlineOrNot gains more users, I've been learning more and more about what folks expect from their uptime monitoring. I've been using that to make an even better product, so even if it doesn't pay off financially in the short term, the product will get better as a result, and the pool of folks that OnlineOrNot meets the requirements for will increase.

The last time I ran ads...

The last time I tried this experiment (a few months into OnlineOrNot's existence, about two years ago), it went badly. I think I spent about $200 for 100 clicks, resulting in zero sign-ups.

So I gave up, and decided "ads don't work".

Since then, I've learned how to make landing pages that convert, and have built a feature-set that matches folk's expectations, and have gotten better at writing copy. This time around, I also iterated on my ads during the week, and managed to get better performance out of them.

In short, maybe ads can work for OnlineOrNot, it'll just take a bit of effort to learn how to write effective ads (like anything else).

My journey so far

If you're just joining now, here's a summary article for each of the last five years:

• year 1: https://maxrozen.com/2018-review-starting-an-internet-business
• year 2: https://maxrozen.com/2019-further-reflections-trying-to-start-an-internet-business
• year 3: https://maxrozen.com/indiehacking-3-year-review
• year 4: https://maxrozen.com/2021-strangers-paid-my-macbook
• year 5: https://maxrozen.com/2022-just-keep-shipping

I shared these links on Hacker News and Twitter this week, and quite a few folks checked them out, so I figured I may as well share them here too.

Heartbeat monitoring

As I mentioned last week, a couple of customers got in touch asking if they could hit an OnlineOrNot endpoint when a cronjob runs, and get notified when the job doesn't run.

The answer was "not yet", but as of today I'm currently testing heartbeat checks against OnlineOrNot itself:

This UI is actually live on OnlineOrNot, just hidden behind the Early Access Program feature flag - I figured I may as well deploy it in an incomplete state and get early feedback as I build it.

Another Friday evening here in Toulouse, let's go into how OnlineOrNot went this week.

I was very close to not writing this week's diary as I felt it's probably too boring for most folks, but lets see how it goes.

This week was a coding week, and I spent most of it planning a new monitoring service for OnlineOrNot, migrating uptime checks back to AWS, and learning new things from other founders on Twitter.

Our upcoming monitoring service

So, there are 2880 30-second increments in a day. Assuming you can check each website within 30 seconds, you should be able to easily reach 2880 uptime checks per day.

For some reason, OnlineOrNot falls short. Not by much, it's about 1% off for the URLs I care enough about to monitor, but I'm still curious as to why it happens.

To help investigate the issue, I started building a hacky thing just for myself, before realizing several users have asked for this feature.

So this week I started designing a new monitoring service for OnlineOrNot: Heartbeat checks (also known as reverse monitoring). Heartbeat checks are where your service sends a request to a URL OnlineOrNot exposes only for you, and sends you an alert if you haven't sent a request within a given time period (if you over-check, OnlineOrNot will ignore the extra requests). There's also an advanced use-case where you send OnlineOrNot a request containing data, and it sends you an alert if the data fails against certain criteria, but that'll come later.

and back to AWS

After a month of globally distributed uptime checks on fly.io, I'm cutting my losses and moving uptime checks back to AWS. The service itself is a joy to use (especially the iad region on the US east coast), but it's not stable enough to run uptime checks in each of their regions. It might make sense for running a web service, where a region's requests can failover to another region, but it just didn't work for me.

I found myself needing to run each check several times on fly.io, as well as backup checks on AWS AND Cloudflare to actually be sure an OnlineOrNot user's URL is actually down, rather than it being an issue with the VM I'm checking from.

Compare that to AWS, where 1 user out of 1305 has checks that consistently fail.

I'm not completely off fly.io though, my new architecture is a hybrid of fly.io and AWS, where a VM queues up checks to run in Redis every 15 seconds, another pulls checks from Redis, and runs the uptime check in a specific AWS region as needed.

Pricing Page Driven Development

I recently read Pricing Page Driven Development from Justin Duke, and it got me thinking about how I never really thought about expansion revenue. I was so excited about getting my first customers, that I was happy to keep the pricing page as-is.

Now that I have a decent number of paying customers, I'm beginning to notice patterns in the plans folks subscribe to, and realizing some changes need to be made to keep the business sustainable long-term. Of course, I don't plan on changing anything for my existing customers, but I'll be introducing a new "Freelancer" plan for solopreneurs to start with.

Another Friday evening here in Toulouse, let's go into how OnlineOrNot went this week.

This week was a marketing week, and I spent it ~~writing landing pages~~ focusing on telling folks what OnlineOrNot actually does.

There are two types of marketing I care about:

• Marketing that brings in more traffic (typically via blog posts)
• Marketing that improves the likelihood folks will try OnlineOrNot once they've landed on the website

The first type is extremely difficult to influence (but what I often spend my marketing week doing, because the dopamine rush of succeeding is so good, I guess). Think months of consistent output before you start to get the numbers building up, apart from the rare popular article making the front page of Hacker News.

The second type is a lot easier to influence: you already have their attention (however little it might be these days), all you need to do is tell them what you do in 0.1 seconds, easy.

Doubling my conversion rate without really trying

OnlineOrNot's funnel is pretty simple while I'm still trying to optimize my landing pages: from every landing page, every call to action (CTA) on that page takes you to the pricing page. From there, folks either bounce, or sign up.

By doing this, you get to test two things: how effective your landing page copy is, and how effective your pricing page is.

This week I tested a few changes (because I did them all at once, I have no idea which one made all the difference, but there was a lot to fix) which doubled the number of people that ended up on my pricing page.

Just above the fold, here's what I changed:

• Updated tagline from "We detect incidents before your customers do" to "Uptime monitoring in 30 seconds"
  • Before this week, you couldn't tell what OnlineOrNot actually did from the main landing page, the tagline was trying to be too clever. This resulted in a large number of bounces.
• Updated every CTA to say "See Pricing ->" instead of "See Plans and Pricing ->"
• Updated the explainer text under the first CTA from "No time limit, and no credit card required." to "Get started on the free tier, no credit card required."
  • Folks regularly ask if OnlineOrNot has a free tier despite having one from the start, so here's hoping this helps
• Added a screenshot of the actual product

By the end of the week, twice as many people were visiting my pricing page having landed on my main landing page than a regular week.

Telling potential customers what we actually do

The trouble with having a single landing page, is that you dilute your message by trying to talk to too many people at the same time.

On the OnlineOrNot landing page, I was trying to tell folks that we support: API Monitoring, Browser Checks, Website Monitoring, Status Pages all in a single page, while being brief.

I'd have people emailing me to ask if I supported Slack alerts, when it was the second feature I built for OnlineOrNot.

To fix this I added a new dropdown menu in the header for desktop users, linking them to each individual landing page I built this week:

Each individual landing page then explains what we do (with a focus on the type of user that would use that part of the product). Going forward, I'll be writing individual pages for every feature OnlineOrNot has too.

Another Friday evening here in Toulouse, let's go into how OnlineOrNot went this week.

This week was a coding week, and I managed to release a feature folks have been asking for, as well as some businessy things that aren't quite marketing, and aren't quite coding:

• I finally added multi-region monitoring back into OnlineOrNot after migrating off of AWS Lambda
• I updated the pricing page, to let folks know we do indeed have a free tier
• I removed in-product analytics, and updated OnlineOrNot's welcome email to invite customers to tell me more about why they monitor their sites.

Finally, proper multi-region monitoring

First, some context.

I was never sure OnlineOrNot would attract any users. As a result, early on OnlineOrNot ran uptime checks entirely on AWS Lambda (with serverless products like AWS Lambda, you only pay for what you use, so if no one uses your product, you pay nothing).

Another benefit of using AWS Lambda is that running an uptime check in Tokyo, Paris, and LA simultaneously is effortless after you deploy - all you have to do is specify where your code should run.

After enough folks started using OnlineOrNot, it made sense to move off AWS Lambda in favour of a server that runs 24/7, and in doing so, OnlineOrNot lost the ability to easily pick where to run. This week, after a bit of work, I now have constantly running servers in:

• LA, USA
• Virginia, USA
• Tokyo, Japan
• Sydney, Australia
• Amsterdam, The Netherlands

Refreshing the pricing page

After talking to a few customers, I realized my pricing page isn't clear.

In the original design, I wanted to keep it short so folks could skim the page, as well as get an understanding of what each plan lets you do. In reality, I made a page too long to glance at, and too short to properly sell all of OnlineOrNot's features.

Basically, in trying to make the page good on average for two use-cases, I made it suck for both.

To fix this, I split the page into two parts: an above-the-fold table highlighting the most popular features, and the original table I used to have, but with more detail.

A new post sign-up email

After reflecting a bit on what I use to decide whether I'll build a feature, I realized: I haven't even logged into PostHog (the tool I used for in-product analytics) in months, why do I bother keeping it in my web app?

The reality is, as a small independent business I spend a good deal of my time actually talking to customers to figure out how it's going, and what features are missing, rather than digging through analytics.

Vibes-driven product management.

So I also figured, perhaps it's time to update my post sign-up email to learn new things.

For the last two years, I've asked every person (via email) that signs up to OnlineOrNot:

What's the one thing you were hoping OnlineOrNot could do for you?

It's driven quite a bit of feature development and helped shaped my understanding of what people expect OnlineOrNot to do.

Now I'm trying a new question to understand the broader context of what OnlineOrNot gets used for:

What led you to need uptime monitoring in the first place?

I recently bought a cheap, used Thinkpad T480, replaced a bunch of parts, then wrote about the experience. Some folks were asking exactly what parts they needed to do the same thing, so I figured I'd write about that too.

You don't actually need to replace anything if you want to use this laptop as-is (for around 250 USD), but you can, which is what attracted me.

The laptop

First of all, you're going to want a Lenovo Thinkpad T480, not a T480s, not a T470, and definitely not an L470/L480.

The specific laptop you're looking for has either an 8th Generation quad-core Intel i5-8250U or i5-8350U CPU. They did build versions of this laptop with an i7, but the i5 is significantly easier to find.

It's a 14 inch laptop, but in its base configuration came with a 1366x768 LCD screen with what feels like zero brightness and contrast, so if you want to save around 90 USD (the specific replacement I got was an Innolux N140HCE-EN1 Rev.C2), look for a model with a 1920x1080 IPS screen.

For a model in great condition with 16GB of RAM and a nice 1920x1080 screen, you're looking at around $250 USD on ebay, plus $125 USD for a new battery and trackpad. Over in the EU, it's around 350 euros, plus upgrades, plus potentially needing to swap out whichever keyboard you find for a US-international one (thankfully keyboards are $30 on AliExpress).

For a totally beaten up T480, I've seen them go as low as 150 USD and still look like they work, but you'll need to spend an hour or two swapping parts out.

The OS

This needs repeating: Pop!_OS 22.04 Just Works™ with this machine. I did not configure a single thing in arcane config files, not a single terminal command to run either.

Bluetooth, WiFi, the screen, the keyboard, the speakers, suspend/sleep, power management, Everything. Just. Works.

I installed the OS, installed my regular apps (Chrome, Firefox, Spotify, GitKraken, DataGrip, Slack, Discord, VS Code, Insomnia, 1Password), cloned my repos, and everything just worked.

What do you mean good enough?

I have OnlineOrNot's dev server (several node servers and a postgres server) running with zero perceptible lag as I write this article with the following apps open: two VS Code windows, Chrome with about 10 tabs, Discord, Signal, Slack, DataGrip, GitKraken.

You might notice I don't build or compile binaries as part of my workflow. If you need to compile binaries as fast as possible on your dev machine, this is not the laptop for you.

That being said, React hot reloading is pretty fast:

wait  - compiling /404 (client and server)...
event - compiled client and server successfully in 264 ms (556 modules)
wait  - compiling /articles...
event - compiled client and server successfully in 267 ms (563 modules)
wait  - compiling /[slug]...
event - compiled client and server successfully in 495 ms (896 modules)

Jumping to my MacBook Air, sure it feels higher quality, but it doesn't feel faster when running the same workload.

The upgrades

In its default configuration, booting Pop!_OS 22.04, I was getting around 6.5 hours battery life, on a 5 year old battery that only charged to 80% of its capacity.

For my purposes, the first upgrade worth getting was a new battery. I opted for a genuine Lenovo 72wh battery (part number 01AV427), and that set me back 90 euros. With the new battery, I get 15 hours in "battery life" mode, and about 30% screen brightness.

The second upgrade I recommend is a glass trackpad from the Thinkpad X1 Extreme (possible part numbers: 01LX660, 01LX661, 01LX662). It's not exactly as good as a MacBook's trackpad, but it's one of the best trackpads I've tried on a non-Mac.

RAM: it's replaceable too. The T480 takes two DDR4 2666 MHz SO-DIMM sticks, up to 32GB total, but runs them at 2400MHz. Either 2400 or 2666 will work, get whatever is cheapest.

Optionally: you can upgrade the WiFi chip to an Intel AX210 for Bluetooth 5.2 and WiFi 6 support, but it isn't noticeably faster than the default chip.

Another Friday evening here in Toulouse, I've poured myself a Delirium Tremens (I shit you not, that's what the beer is called), let's go into how OnlineOrNot went this week.

What even is a marketing week?

Jake recently replied to one of the OnlineOrNot diaries, asking:

Have you ever detailed what a 'marketing week' is?

To which I replied (paraphrasing here):

My marketing weeks are normally based on vibes, but I typically:

• update the changelog
• write blog posts/screencasts/guides that are missing
• tweet more
• participate more in forums (mainly hacker news and reddit)
• talk to existing and potential customers about how they monitor their URLs, alert their customers to incidents, and generally how they manage their incidents
• work on landing pages

Actually, time for a reliability week

This week was supposed to be a marketing week, and then over the weekend before this week started, fly.io had reliability issues.

At the same time, I was in the process of rolling out a change that would make OnlineOrNot check uptime globally by default (rather than from a single data center + verifying downtime globally), and ended up mistakenly sending 2500% more emails than usual on Saturday and Sunday, thanks to a bad deployment in Singapore, followed by a bad deployment in Sydney.

The idea was to allow significantly faster checks, and use several failing checks in a row as a signal that your URL is indeed globally unavailable, but I had to roll it back and start from scratch.

After fixing all the issues I managed to step back, breathe, and write about it in monitoring our monitoring (that counts as marketing, right?)

In short, I now have graphs that tell me if what I just merged caused false positives (or for the checks to stop entirely):

Side note: the spikyness in the graphs comes from previously only running checks at the start of each minute - as of this week, checks are run every 10 seconds, which will smooth out the graph eventually.

This week I:

• started running uptime checks every 10 seconds
• started logging each check in ClickHouse, and started monitoring our monitoring with Grafana
• quadrupled how many uptime checks individual VMs perform (after verifying it had no impact on false positives)
• tripled the default timeout of our uptime checks from 10 seconds to 30 seconds, and made it possible to choose how long is considered a timeout (some folks are okay with their users waiting 10-30 seconds for the page to respond, and don't consider that an outage - I'm not one to judge)
• tripled the number of retries each VM performs before checking on another hosting provider
• wrote about the reliability dramas
• pitched OnlineOrNot to some ex-Atlassian alumni

So in short, not much marketing, but in the end I think OnlineOrNot is better for it. Maybe I'll move towards a 3 week program of Coding Week -> Marketing Week -> Reliability Week in the future, who knows.

Got something you're curious about? Feel free to tweet at me, or subscribe to the mailing list below to get these every Friday.

Another Friday evening here in Toulouse, I've poured myself a Gallia West Coast IPA, let's go into how OnlineOrNot went this week.

It was a coding week according to CodingWeekMarketingWeek, so I spent my mornings mainly working on the new onlineornot CLI, and writing docs.

On Monday morning, I realized almost none of the API endpoints or CLI commands I built at the end of last week were documented, so I went through and documented everything:

• From installation,
• to login (it sucks that folks need an API token for this, I'll need to revisit login to piggy-back their OnlineOrNot app login in the future)
• to CLI commands
• and the API endpoints behind them.

I also implemented and released onlineornot checks create with exactly as many options as when I initially released OnlineOrNot two years ago: name and url.

I considered that enough functionality for a v1, so I cut the v1.0.0 release, and sent out a quick email and blog post for the release.

Folks don't seem that interested in the CLI, but then again it does lack the features the web app has, and it's only a week old.

Since next week is a marketing week, I'll probably record a few screencasts explaining how to login and use the CLI. I recently remembered that I had even built a page for screencasts on the OnlineOrNot marketing site - judging by the screenshot, I haven't touched it in about 18 months.

Apart from the CLI, I also found time to help out a customer by making it possible to check client-side rendered web apps locked behind authentication (both via making it possible to add custom HTTP headers to Browser Checks, and getting past Basic HTTP Authentication).

That's all for this week, looking forward to writing and recording the screencasts next week (I also have a spicy blog post about uptime monitoring brewing in the back of my mind, if I have time for it).

Alright, I've poured myself a beer, it's early Friday evening, let's quickly dig into how OnlineOrNot went this week.

Coding Week, Marketing Week tells me it's marketing week, I've spent at least half of this week building the onlineornot CLI, but it wasn't a total loss.

(I'm starting a thing where I write about OnlineOrNot regularly in a barely edited, diary-like format, let me know what you think.)

Actual marketing

Today is OnlineOrNot's second birthday (roughly - I published a tweet about it on the 25th of February 2020, but published the day before), and to celebrate, I wrote up what I learned running a SaaS for a second year.

Approximately 1.6k people read it this week, about 1/20th the number of readers for the article from last year, but whatever.

I published a second article about the thinkpad I built last weekend, which was read by 45k people this week, and drove 1.2k people to OnlineOrNot's home page, which is wild.

It led to a few folks to message me that the machine I built for myself doesn't work for them and their use case, which gave me a good chuckle.

OnlineOrNot CLI

The other day, I realized what annoys me most about OnlineOrNot is that I have to open a browser, type into the address bar, and navigate through the landing page and the app's home page before I can see how my checks are doing.

It got me thinking, it'd be cool if onlineornot checks list was just a command in your terminal.

In three days, I've made it possible. npm install -g onlineornot if you want a global command, or npx onlineornot@latest to just run the latest version every time (requires at least Node 16 LTS).

You can find the source code on GitHub.

This week I shipped commands to:

• Get a list of all uptime checks in an account, and their live status (with JSON output support too)
• Get a specific uptime check, and it's live status (with JSON output support too)
• Delete a specific uptime check
• Open a browser window to the docs
• Open a browser window to the billing settings
• Open a browser window to the developer settings

I'm pretty chuffed, the CLI menu looks like this at the moment:

// npx onlineornot@latest
onlineornot

Commands:
  onlineornot docs     📚 Open OnlineOrNot's docs in your browser
  onlineornot checks   ✅ Manage your uptime checks
  onlineornot billing  🧾 Open OnlineOrNot's billing in your browser
  onlineornot login    🔓 Opens your browser to OnlineOrNot's Developer settings
  onlineornot whoami   🕵️  Retrieve your user info and test your auth config

Flags:
  -h, --help     Show help  [boolean]
  -v, --version  Show version number  [boolean]

Over this weekend I'll make it possible to add uptime checks too, probably via onlineornot checks create, and release it as the v1.0 release.

I recently replaced my 2020 MacBook Air M1 with 8GB of RAM with a Lenovo Thinkpad T480.

It's not as insane of a downgrade as it sounds.

Want one for yourself? I wrote about what you'll need to buy here.

Specs

My Thinkpad T480's specs:

• Intel® Core™ i5-8350U CPU @ 1.70GHz × 8
• Internal 24wh battery + external 24wh battery (6 hours 15 minutes default battery life on linux, upgradeable to 92wh total)
• 16 GB RAM (upgradeable to 32GB officially, 64GB unofficially)
• 1366x768 LCD screen (upgradable to anything from a 1920x1080 screen to a 4k screen, more on that later)
• Windows 10 Pro installed w/ OEM key
• 256GB Samsung NVMe drive
• WiFi/Bluetooth module: Intel® Dual Band Wireless-AC 8265 (WiFi 5), again, upgradeable
• Ports:
  • Two USB-C ports
  • Two USB 3.1 ports, with one Always On
  • One HDMI 1.4b port
  • Ethernet port
  • 3.5mm headphone jack
  • SD card reader

I don't know if you noticed a theme in the specs, but everything in this laptop is upgradeable. Short of the CPU, which is a downer, but this isn't exactly an MNT Reform laptop.

Upgrades

The base model LCD screen that the T480 comes with is incredibly bad.

It hurt to look at, the resolution was too small for anything except using the terminal, and I couldn't use it sitting next to my window unless brightness was turned up to 100% (on a cloudy day!), and even then it wasn't great.

(one quick boot into Windows to check specs before blowing it all away)

So I ordered a replacement 1920x1080 IPS screen (Innolux N140HCE-EN1 Rev.C2), followed the ifixit guide, and had a decent screen after 30 minutes of tinkering.

Unfortunately upgrading the screen cut battery life to about 4 hours 15 minutes (with the screen set to high brightness), so I've ordered a 72wh battery, which should bring that back up to around 8 hours. Note that the battery that came with my T480 is not brand new: as it's a 5 year old enterprise laptop, it had about 80% max charge of its original design. I can also undervolt the CPU to cut power consumption further, but 8 hours is enough for me when traveling.

After a week of testing (using the machine as I normally would), the battery life on the new 1920x1080 screen ended up being around 6 hours, I must have just been slamming the CPU/RAM when I first tested it.

Update: After the brand new 72wh battery came in (for a total system capacity of around 90wh), my battery life is now 14-15 hours.

While upgrading the LCD screen, I noticed I had a spare 16GB RAM stick lying around my home office, so I also upgraded to 32GB RAM. Not that I need that much as a web developer/writer (VS Code, GitKraken and Chrome take up 8GB), but it's nice to have. (It takes two DDR4 2666 MHz SO-DIMM sticks)

The trackpad is good, compared to other Windows laptops, but terrible compared to the MacBook Air. I've ordered a glass trackpad that comes with the Thinkpad X1 Extreme (and is compatible with the T480), so I'll update this article once I've installed that.

Update: The new trackpad from the Thinkpad X1 Extreme is fantastic. Tap-to-click actually registers my clicks, unlike on the default T480 trackpad, and scrolling is extremely precise. Swiping to change workspaces feels just as nice as in macOS (though you'll need to learn new gestures).

I've also ordered an Intel® Wi-Fi 6 AX200 card for WiFi 6 and Bluetooth 5.2.

Update: The Intel AX200 card causes boot issues for Pop!_OS (at least for me), so I just installed the old one back in. I'm not here to dig through forums and run scripts to tell you "it just works!", so I'm keeping the default wifi card that does Just Work.

Update 2: I bought an Intel AX210 card which Just Works with Pop!_OS, supports WiFi 6, Bluetooth 5.2, so I'm using that now.

But... why?

You might be thinking, "wtf, isn't the M1 significantly faster?" - and it is!

I ran Geekbench:

• T480 scored 1136 on single core, and 2522 on multi core with default settings
• T480 with throttling removed scored 1229 on single core, and 4240 on multi core
• M1 scored 2355 on single core, and 8241 on multi core

But is it noticeably 2x slower than the M1? Nope.

It's enough.

Hot reloads of OnlineOrNot's development server take < 1 second, alt-tabbing doesn't lag (it did on my Intel-based MacBook Pro 2019), and booting up is as fast as my MacBook Air. So far, none of my development workflow is slower on the T480.

I installed Pop!_OS 22.04 LTS as I've had quite enough of Microsoft's constant nagging to upgrade to Windows 11, and honestly, I like it?

Everything works out of the box. I haven't had to screw around with anything. The user experience isn't as polished as macOS, but this is the first time I've installed a distro where it Just Works. For what it's worth, I've been trying to get a stable Linux development machine since at least 2010, and I always ended up back on a MacBook.

You can get a Thinkpad T480 for around $200 USD, and upgrades will cost you around $150 total on AliExpress. If any individual part fails, there's a freely available Hardware Maintenance Manual, complete with part numbers that you can look up and order from 3rd party suppliers.

Having experienced Apple's wrath through the 2011 15" MacBook Pro dGPU problem (the motherboard is an overheating time bomb, that will inevitably fail and require replacement - I had two motherboards fail on me after four years, asked for a refund, had to quote Australian Consumer Law at them to get a fair deal), I'm happy to have a way out.

No really, why?

• I can't tell the difference in performance or build times as a web developer, my dev server is just as fast on Pop!_OS 22.04 as macOS 13.2
• I once spilled an entire can of beer onto a Thinkpad X220. The fix involved a screwdriver, a sponge, a $50 replacement keyboard, and 15 minutes of my time (there are drainage holes on the bottom of Thinkpads).
  • for contrast, a little bit of dust can break an Apple butterfly keyboard
• I'm tired of Apple's ecosystem, Apple ID, not being able to change any individual part of my laptop, being charged $200 USD for 8GB of RAM, being charged $200 for 256 GB of SSD, and so on
• I wanted a cheap travel laptop I could replace without blinking an eye at the price. I live in Europe, Thinkpads are the most common enterprise laptops I see while traveling. I might even slap an asset tag sticker on the cover to make it even more inconspicuous.
• I felt like it? I'm not telling you what to do here, I'm just telling you my experience.

At the end of each year I summarize how the year went, reflecting on how I progressed towards my goal of being self-sufficient as a web developer, here are the previous editions of this article:

• (2021) Strangers from the internet paid for my MacBook Air: on my 4th year of indiehacking
• (2020) Indiehacking: a review of my 3rd year
• 2019: Further reflections on trying to start an internet business
• 2018: Reflections on trying to start an internet business

As of last year (2021), the business makes money. Not nearly enough to be self-sufficient as a web developer, but this year it continued growing enough at a steady pace that it makes me think one day it'll get there.

For most of the year, I kept working on OnlineOrNot, for roughly 2 hours every day before my workday started. Not that working on OnlineOrNot felt like work - I was doing everything from answering customer support emails, writing blog posts to build trust with potential and current customers, building landing pages, writing docs, shitposting on twitter, etc. No status updates, no standups, just building value.

Table of Contents

• On Success
• Working for Cloudflare
• Write more
• Pay attention to opportunity cost
• Register your damn business
• Black Friday can be 80% of yearly revenue

On Success

Much of OnlineOrNot's success boils down "show up regularly, do the work, over a long enough time period" - at some point I wrote my thoughts about this into an article: The unreasonable effectiveness of shipping every day.

Just show up, do the work, and ship, daily. How hard can it be?

I actually failed a few times this year, and quickly learned to just keep working on OnlineOrNot.

| | | :----------------------------------------------------------------------------------------------------: | | it was not different this time, dear reader. |

In late January, I spent a week to split out the feature flag service I use for OnlineOrNot into its own product, and realized "it runs entirely on Cloudflare's network so it's real fast" isn't as big of a selling point as "we've been around forever, have an adequate feature set, and won't randomly disappear" (part of why OnlineOrNot wins in a sea of uptime monitoring services), so I shut down the feature flag service.

Around April, I came dangerously close to splitting out my docs into another paid service before I remembered the reason my customers love my docs - they're deeply integrated into my app and website, they load ridiculously fast, and they're in the same mono-repo so I can update them while updating my code. An external service just can't compete.

In September, I used some shiny new tech from Cloudflare to build a real-time chat Trello power-up called Petit Chat. I built it over a couple of weekends, it gets users without marketing (the joy of being in an app marketplace). A fun distraction, but I'm keeping my focus on OnlineOrNot.

Working for Cloudflare

From reading what I write, hopefully you get the impression that I'm the type of engineer that enjoys shipping a tiny version of the end goal, and rapidly iterating while real customers use the product.

I don't enjoy work when my organization mandates a waterfall-like process, so at the start of the year after staring at the sea for a few days during my holidays, I realized I needed to change employers.

Building and releasing the feature flag service wasn't entirely a waste - I built it publicly on Twitter, got extremely lucky, and managed to score an interview at Cloudflare with the team building the tools I used. Long story short, now I get to work on Cloudflare Workers every day.

Since starting I've had the chance to improve Wrangler (our CLI for building on Workers) quite a bit, and now I'm working on D1's developer experience.

Write more

In 2021 I noticed the value of content marketing - I would write an article, a huge rush of attention would come in, and traffic would fall back to a slightly increased baseline. If I wrote nothing in a month, around 1.5k visitors would still come check OnlineOrNot out.

In 2022, this trend continued as I started following Coding Week, Marketing Week obsessively. I would work for one week on engineering for OnlineOrNot, then the following week I would write about what I did.

These days, if I write nothing, around 3.3k visitors still visit OnlineOrNot per month.

I noticed a similar effect with this blog - roughly 13k visitors come to MaxRozen.com on the months I write nothing, and that number steadily grows the more I write.

My favorite trick for writing more is turning comments/tweets into articles. I'll notice I've repeated the same information a couple of times in several forum comments, paste the comment directly into my IDE, add some context, and immediately release it as an article. You're going to write comments anyway, may as well turn your useful comments into articles.

Pay attention to opportunity cost

As a good example of this, I started OnlineOrNot as a bunch of AWS Lambda functions, knowing that if no one used the service, it would cost me nothing, but if I succeeded, it would cost me a premium over a continuously running server.

Around June this year, I noticed that my AWS bill had grown to around $100 USD per month just for AWS Lambda, for something that could fit entirely within a single $5/mo VM.

While as an engineer you'd be tempted to immediately move it over, I realized I could deliver much more value to my customers in the week of engineering time a rewrite would take, than saving $95/mo.

This all changed once I launched a trial plan and suddenly a rush of users could cost me serious money, so in the end I rewrote and moved off AWS Lambda to save me from anxiety: On moving over a million uptime checks per week onto fly.io.

Register your damn business

For a long time, I ran OnlineOrNot as a business using my Australian sole-trader tax registration, and mixed personal and business bank accounts.

This year I finally got my shit together and registered ROZENMD as a software development business here in France, and now there are business bank accounts and everything.

Being able to see all of your business expenses in one place, and not have to sift through credit card bills to figure out if something was a business expense is absolutely worth the bureaucracy.

Black Friday can be 80% of yearly revenue

Back in 2021, I wrote a book about a single function in React. I actually didn't try particularly hard to sell it - this blog has a few articles about useEffect, and they link to the book for folks that want a single resource to finally understand useEffect.

This year for Black Friday/Cyber Monday I sent out a couple of emails putting the book on sale for 50% off and was completely blown away at how many people bought the book.

Something like 80% of the year's revenue came from two emails I sent.

Ever get weird errors about unsupported features when running your React app's dev server? Chances are your codebase is written for a specific version of Node, and you don't have it installed.

Or perhaps you know which version of Node each project uses, and you manually install a specific version of Node before getting started.

There's a few tools we can use to manage this for us!

nvm - node version manager

Node version manager is one of the more popular ways to manage your local Node version when developing.

You install a new version of Node by running nvm install 18 in your Terminal, and swap Node versions by running nvm use 18 (or whichever version of Node you want to use).

You can also lock the version of Node your project uses by including an .nvmrc file in your project's root, containing the version of Node you want everyone to use.

The downside to using nvm is that you tend to forget which version of Node you're using, as it doesn't automatically change versions between projects. The fix is to setup up a script in your Terminal to automatically search for an .nvmrc file and change Node versions when you change directory, but other tools do this automatically, like volta.

Volta

Volta does things a little differently. Firstly, it's written in Rust, so changing versions should be very fast, and secondly, it's designed to get out of your way - so you don't even need to manually change Node versions when switching projects.

To do this, you need to run volta pin node@18 in each of your projects, and it'll update your package.json file to add config that volta uses to automatically switch versions.

I personally use this at work and it feels like magic. The only annoying thing I've noticed is how Volta handles global installs. You can run npm install -g wrangler for example, but if you want to update it afterwards, confusingly, you have to run volta install wrangler.

pnpm

You might know pnpm as a ridiculously fast package manager that supports monorepos, but it also manages your node version.

asdf

If you use more than one runtime, you might be interested in asdf as an all-in-one tool for managing your node, java, ruby (and more) runtime versions.

asdf also supports automatically updating Node versions via .nvmrc and .node-version files - described in asdf-nodejs.

I started my career having finished a double Bachelor's degree in Software Engineering and Commerce, thinking I could just get a finance job, and automate the boring parts with my Python skills.

Then reality hit. The European debt crisis was in full swing, and Sydney, Australia was a backwater for finance jobs (especially as an average student).

Roughly a year of job hunting later (including one call back, in which the recruiter asked me why I didn't go back to university and get a degree in accounting if I wanted to work in finance), I realised I should probably rewrite my resume to be more Software Engineering focused.

Eventually a friend from university suggested I pitch his hedge fund a dashboard built in D3.js - this cool new technology (at the time) that made their Excel dashboards look ancient.

So I started learning JavaScript

I spent a week learning just enough JavaScript to make a convincing dashboard of all stocks trading on the ASX 200, with data fetching from Yahoo Finance. I didn't get the gig, but I ended up getting the attention of the agency that worked for the hedge fund.

I ended up working for the agency, building data pipelines, learning more Python, building sites in Django and picking up more JavaScript via angular.js. After about a year, I started longing for more, so I started interviewing with the Big Four Consulting Firms (EY, PwC, Deloitte, KPMG), and found myself with an offer for a role at Ernst and Young (EY).

I was so keen for a "big name" on my resume, I was willing to take a 10% pay cut to work there.

So I became a consultant

The consulting job didn't quite turn out as planned.

You had to wear a suit, most clients already hated you before meeting you (I assume due to the cost of hiring the firm). To top it off, it felt weird being told to perform manual tasks in ancient drag-and-drop software with your team after having spent a year writing Python to automate that sort of work.

I'm told since then, the latest advancement is that they're using a sort of scripting language (they're selling it as Robotic Process Automation or RPA to clients) to automate away the manual work. I'm still glad I didn't stick around.

I started hatching a plan to escape after a few months. I wanted to go back to being a software engineer, but jobs in Python were rare in Sydney.

So I started learning React

I had written enough JavaScript to know React was probably going to be a big deal, so I hit the tutorials. I found the official documentation at the time to be quite dense, it almost felt like you needed to already know React to be able to finish the tutorial.

A couple of tutorials really stood out, (and are amazingly still online):

• React From Zero
• The Road to React - I used the pre-hooks version (since they didn't exist at the time)

After the tutorials, I started building side projects in React and GraphQL while hunting for a React job.

It took about four months to find a job, but what I found almost doubled my salary.

So I became an entrepreneur

I never really stopped building side projects while employed, mainly out of imposter syndrome, as I felt I needed to catch up to my colleagues to be a useful member of the team. I wrote about how that's going for me here.

I personally wouldn't recommend it, unless you're really good at managing your own psychology, particularly around burn-out, self-talk, and managing your own expectations. I eventually learned those skills, but it was a bit of a rollercoaster along the way.

Over the years, I've built:

• a job board
• an appointment scheduler
• a room booking system
• a GraphQL snapshot monitoring service
• a REST API monitoring service
• a frontend performance monitoring service
• an uptime monitoring service (OnlineOrNot - I'm currently working on this one)

After a few years of being a React developer I finally got a frontend job at Atlassian, followed by a software engineering job at Cloudflare.

What's next?

I still think React (or something like it) is going to remain, and simultaneously be, the next big thing. The numbers tend to agree with me, React was #1 for hiring on Hacker News in 2016, 2017, 2018, 2019, 2020, and 2021.

Learning React has greatly improved my quality of life and my job prospects, so I want to help others do what I did. I tend to write about common pain points that folks experience while using React (most recently that has been useEffect), and how to overcome them.

I use my newsletter to share what I'm working on, so you can follow me there if you'd like to see it first.

Do you sometimes worry that your tests don't make sense? Struggling to get what people mean by "test from the user's perspective" and the classic piece of advice "test functionality, not implementation details"?

You're not alone!

I felt the same thing when I started using React Testing Library. I used to think of testing as just checks you had to do on individual components, directly asserting against props and state, and would struggle to think about how to test the integration of several components together.

What does "integration test" even mean?

It helps to think of integration testing like a bigger unit test, except the unit you're testing is the combination of several smaller components.

More concretely, instead of just testing a Button component, or a TextField component in isolation, we're going to test that they work when placed together into a form.

Let's get started!

We're going to be testing a form almost every public web app you're going to build has: a Login form. It's probably one of the most important parts of your app (in terms of business value), so let's be confident it actually works!

Setup

We're going to be using create-react-app, because it comes bundled with @testing-library/react. I'm also using react-hook-form to build our form, because it's the fastest way I know to build a form in React apps.

Steps

1. Clone the repo

2. Run:

   yarn start
   

   You should see something like this:

3. At this point, if you ran yarn test, you would see the following:

 PASS  src/pages/Login.test.js
  ✓ integration test (177ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        4.134s
Ran all test suites.

Watch Usage: Press w to show more.

So how do we get here?

First off, here's the code from our integration test:

import React from 'react';
import { render, fireEvent, screen } from '@testing-library/react';
import user from '@testing-library/user-event';
import Login from './Login';

test('integration test', async () => {
  const USER = 'some-username';
  const PASS = 'some-pass';

  render(<Login />);

  const userInput = screen.getByLabelText(/username/i);
  user.type(userInput, USER);
  const passwordInput = screen.getByLabelText(/password/i);
  user.type(passwordInput, PASS);
  const submitButton = screen.getByText(/submit/i);

  fireEvent.click(submitButton);
  expect(await screen.findByText(/your username/i)).toBeInTheDocument();
  expect(await screen.findByText(/your password/i)).toBeInTheDocument();
});

It might look like we're doing a few complicated things above, but essentially, we've taken the steps a user takes when logging in, and turned it into a test:

1. Load the Login screen
2. Click on the username input, and type the username
3. Click on the password input, and type the password
4. Click the Submit button
5. Wait around for some sign that the Login worked

Some testing-library specific things worth calling out:

• We import '@testing-library/user-event' to let us to type into our inputs
• We import fireEvent from the '@testing-library/react' library to let us to click on our Button component
• We've marked the test async to enable us to use findByText()
  • We use findByTest() after performing an action that may be asynchronous - like filling out a form. (findByText returns a Promise, letting us await until it finds the text it's looking for before continuing)

We've built a test that can type into our TextField components, click on our Button component, and trigger the Form component's onSubmit function, without ever referring to implementation details!

If you're confused about findByText vs getByText, don't worry - that's normal. In general though, findBy functions are for use after async actions (like clicking the Submit button), and getBy functions are for general use.

React Testing Library also has a cheatsheet with tips to help you decide which one to use.

Conclusion

You've just started to understand integration testing, but you best believe there's a lot more to it than this article!

If you want a more advanced perspective of integration testing your forms, I highly recommend reading the testing section of React Hook Form's Advanced Usage guide.

At the end of each year I take the time to reflect on how I progressed towards my goal of being self-sufficient as a web developer, here are the previous editions of this article:

• (2020) Indiehacking: a review of my 3rd year
• 2019: Further reflections on trying to start an internet business
• 2018: Reflections on trying to start an internet business

I started 2021 knowing I was going to make money on the internet if I stuck to consistent technical writing. Thanks to 30x500 (a course on selling products), I learned the value of consistency, and the power of giving away free content as a means of building trust at scale.

At some point in February, a recruiter reached out to ask if I wanted to write articles full-time for their SaaS to help drive their content marketing growth engine.

I thought about their offer for a solid day or so before realising that I had built a SaaS before, why not just use my content marketing skills to drive traffic to one of my own products?

And so my end of year wrap-up post is yet again about how I built a SaaS (my 7th attempt at building a bootstrapped SaaS for those of you counting at home).

Keen to see what happened? Read on, dear reader.

Table of contents

• Will write technical content for cash
  • Book 1
  • Book 2
• So I wrote another SaaS
  • Picking a name
  • The approach
  • How it went
• Total Internet Revenue for the year
• Advice for fellow makers

Will write technical content for cash

Book 1

At the start of the year, I had just finished writing an ebook on React's useEffect hook, and I was ready to launch.

On January 6, I launched to about 500 email subscribers, and uhh other things happened that day to distract people from some guy on the internet selling a single resource to learn useEffect.

I ended up making 27 total sales, and $301.84 USD.

I was actually pretty satisfied - in 2020 I made around $100 USD over the entire year from publishing my React articles on Medium, and this only took a few weeks to do.

Throughout the rest of the year, without trying particularly too hard to market/sell the book, I ended up making $721.94 USD, after fees.

Book 2

In mid-February, I decided I would give away an ebook on React testing for beginners.

I was still writing and releasing articles about React almost every two weeks. I noticed I was getting decent traffic on some of my articles about React testing, and realised React could use a resource for beginners to get started.

Over one particularly caffeinated weekend I combined all of my React testing articles into a single book, polished it up, made a bunch of codesandboxes for people to play with, and put it up on Gumroad with "pay what you want pricing", and ended up having 1353 people download it, and I made $143.99 USD in donations after fees.

As I wrap up the year, I made $865.93 USD from technical writing alone.

So I wrote another SaaS

As I mentioned earlier, I decided to write another SaaS after realising consistent content marketing could be valuable for driving traffic.

As well as that, I found my technical writing business to be incredibly manual and repetitive - I would write articles to get email subscribers, write more articles to send them to email subscribers, and eventually write an info product to sell to my most interested subscribers while continuing to write new articles for my email subscribers.

My thinking at the time was that at least with a SaaS the product could continue to exist and maybe even pay for the content marketing with recurring revenue.

Picking a name

Over the years I've built several SaaS products, and kept their marketing sites online even after I shut down the SaaS behind them.

Only OnlineOrNot (my GraphQL API checker I built and killed in 2019) continued to slowly get enquiries after I shut it down (and not just from folks looking for GraphQL API monitoring, but web monitoring in general).

It didn't take me long to realise that:

• There was a problem to be solved here
• I had personally experienced the problem
• I had leads for potential customers from my professional network
• I could probably find people willing to pay for uptime monitoring, even if it was the 200th alternative to Pingdom

Side note - on doing something other people are doing: I was not the first person to write about React, and yet people were still interested in what I had to say. Similarly, I am not the first developer to try to solve uptime monitoring, but my bet is that my take on the problem is unique enough that others will find it valuable.

The approach

I gave myself one week to ship.

It took me a few hours to have a simple webpage where people could enter their URL, and check if it was online from 12 cities around the world.

I shipped that simple webpage, and showed the internet. A few people followed me on Twitter out of curiosity, and I had a twitter thread going to keep track of my progress, and I still use that same twitter thread today for progress updates.

By the end of the week, I had:

• email-only authentication and Google login via OAuth2.0:

• a form to add URLs:

• a dashboard to see your URLs being monitored:

By the end of the second week, I added:

• a Stripe integration to accept payments

After about five weeks of development, I had my first paying customer:

I kept shipping, and I kept updating that Twitter thread, and I kept writing about my approach to product development, while also writing useful articles for my audience.

How it went

I'll save you the excessive details, as I've already written about it here:

• Building a SaaS in one week: How I built OnlineOrNot
• What I learned running a SaaS for a year

The gist of my approach is shipping the absolute minimal viable feature as soon as possible, using content marketing to drive traffic to my site, and working approximately two hours a day before work.

I'm ending the year with OnlineOrNot earning an ARR of $3000 USD (having gained back some MRR I lost recently), and I've used some of that revenue to pay for a MacBook Air M1 (effectively bought thanks to strangers on the internet), which I'm using to ship things even faster.

Prior to buying the MacBook Air I was writing all my code and articles on a 2011 13" MacBook Pro, and while I appreciated the heat in winter, it was SLOW.

Total Internet Revenue for the year

Technical writing brought in $865.93 USD, and Stripe tells me that OnlineOrNot brought in $1989 USD between April and the day I wrote this article, so about $2854 USD for the year in total, entirely from strangers on the internet.

Now you might be thinking, "if you put in three months of writing effort for $865.93, if you kept going for the whole year you'd have almost $3500", which is a fair point, but writing revenue isn't necessarily recurring.

I managed to have a burnout, not work on OnlineOrNot for nearly two months while I got married and moved my entire life from Sydney, Australia to France during a pandemic, and OnlineOrNot just kept monitoring my customers' sites, and bringing in revenue. Of course the business didn't grow while I was away, but it didn't fall to pieces either.

Advice for fellow makers

Don't try to do a SaaS, especially not for your first paid product.

Actually writing code is perhaps 10% of the total work of running your own SaaS. If you just want to write code, consider selling a code solution to a common problem instead (see Tailwind UI or Divjoy as an example).

Selling people an info product once is significantly easier than trying to sell them a subscription.

Once you understand how to sell someone a thing once, it becomes significantly easier to understand how to sell someone a subscription.

Once you do start building a SaaS, make sure it's a problem you actually care about, because you'll be thinking about the problem space for years to come.

Similarly, make sure you're solving the problem for a group of people you actually care about, because you'll be working with the same group of people for years to come.

The Problem

So you're working on a Custom UI Forge App, thinking it'd be cool to use the storage API.

You import storage like so: import { storage } from "@forge/api";, try to use it, similar to this:

// some-forge-app/static/hello-world/src/App.js
import { storage } from "@forge/api";
// more imports here...

const App () => {
    useEffect(()=>{
        const fetchData = async () => {
            await storage.set('test','someValue');
            const data = await storage.get('test);

            console.log('data: ', data);
        }

        fetchData();
    }, []);

    return <div>test</div>
}

You build your app, run forge deploy, and get this scary runtime error:

The Fix

You can't actually import from @forge/api directly in Custom UI apps.

Instead you need to define a resolver function (in Forge template apps, a basic one is provided in src/index.js), like so:

// src/index.js
import Resolver from '@forge/resolver';
import { storage } from '@forge/api';

const resolver = new Resolver();

resolver.define('get', async ({ payload, context }) => {
  const data = await storage.get(payload.key);
  console.log('data fetched: ', data);
  return data;
});

Then in your Custom UI app, you add an import for @forge/bridge's invoke function and call it in your component like so:

// some-forge-app/static/hello-world/src/App.js
import { invoke } from '@forge/bridge';
// ... the rest of your React component here
const data = await invoke('get', { key: saveKey });

It's no secret React has a library discoverability problem.

While the number of stars in GitHub and weekly downloads in npm might be a good starting point for finding quality libraries, normally you have to wade through a lot of reddit, hacker news, dev.to and individual blog posts to find the best ones.

In this (continually updated) article, I'll be adding libraries (excluding component libraries, I track those here) worth talking about on a single page.

Table of Contents

• Table of Contents
  • 3D
  • Accessibility
  • Animation
  • Browser Features
  • Data Fetching Libraries
  • Data Visualisation
  • Forms
  • Mocking APIs
  • State Management
  • Testing
  • Videos

3D

react-three-fiber is a React renderer for threejs on the web and react-native.

Chances are, if you've seen really cool 3D animations on a website, it was probably built in three.js - react-three-fiber gives you a way to tap into React while building your 3d scenes. There's also a Next.js + Tailwind starter worth looking into.

Accessibility

React Aria

React Aria provides you with Hooks that provide accessibility for your components, so all you need to worry about is design and styling. Particularly useful for those building design systems.

Example usage - useButton:

import { useButton } from '@react-aria/button';

function Button(props) {
  let ref = React.useRef();
  let { buttonProps } = useButton(props, ref);

  return (
    <button {...buttonProps} ref={ref}>
      {props.children}
    </button>
  );
}

<Button onPress={() => alert('Button pressed!')}>Press me</Button>;

Animation

Animation adds soul to otherwise boring things. These libraries let you build the web app equivalent of Pixar's Intro Animation, but in React.

Both libraries have similar APIs and support spring physics over time-based animation, though Framer Motion seems to be used more often on GitHub.

Framer Motion

Framer Motion is an animation and gesture library built by Framer. The added benefit of Framer Motion is that your designers can build animations in Framer, then hand-off designs to be accurately implemented using Framer's own library.

React Spring

React Spring uses spring physics rather than time-based animation to animate your components. Relative to Framer Motion, React Spring has been under development for longer, with a greater number of open-source contributors.

Browser Features

Ever been asked to implement random features that someone on the product team saw on another website and thought was cool? These libraries save you time on building those features.

useClippy

useClippy is a React hook that lets you read and write to your user's clipboard. Particularly useful for improving UX, letting you save your users from double clicking on your data fields, by providing them a button to copy values.

ReactPlayer

ReactPlayer is an awesome library that lets you embed video from major sources (YouTube, Facebook, Twitch, SoundCloud, and more), and define your own controls to the video.

React Toastify

React Toastify allows you to add fancy in-app notifications (like the "Message Sent" notification in Gmail) to your React app with only four additional lines of code.

Data Fetching Libraries

You might be wondering why you'd even need a data fetching library, when you could use useEffect and fetch(). The short answer is that these libraries also handle caching, loading and error states, avoiding redundant network requests, and much more.

You could spend hundreds of hours implementing these features in a Redux-like state manager, or just install one of these libraries.

React Query

React Query lets you request data from the same API endpoint (for example api/users/1) across multiple components, without resulting in multiple network requests.

SWR

Similar to React Query (in fact, based on the same premise, see this issue for more info), SWR is another data fetching library worth checking out. SWR has the added security of being used by Vercel in production as part of their platform.

Data Visualisation

Everyone wants to have beautiful charts, but nobody wants to learn no complicated-ass D3

• Ronnie Coleman, probably

visx

If you've ever used a popular charting library such as Recharts or Charts.js, you'll know it's surprisingly easy to reach the limits of what a charting library can do for you.

visx is different, in that it provides you with lower-level React components that are much closer to D3 than other charting libraries. This makes it easier to build your own re-usable charting library, or hyper-customised charts.

Forms

Forms suck. Take it from someone who once had to build a "smart" form with 26 possible fields to fill out - you want to pass off as much as possible to your form library, leaving you with only quick field names to enter.

React Hook Form

React Hook Form is different to other form libraries, in that by default, you're not building controlled components and watching their state. This means your app's performance won't get slower as you add more fields to your form.

On top of that, it's probably one of the best documented libraries out there - every example has a CodeSandbox, making it easy to fork and try out your particular use case.

Mocking APIs

You could probably argue mocking libraries belong more under testing utilities, but they have added benefits during development too. While not specifically tied to React, they can be extremely useful when you want dynamic responses from your mocked endpoints.

Mock Service Worker

MSW is a library that lets you mock both REST and GraphQL APIs, that uses service workers to generate actual network requests.

Why is that cool?

You can actually use MSW as part of your development workflow regardless of technology choice, not only while testing! It's so cool that Kent C. Dodds wrote a whole article about it.

In short, you can use MSW to experiment with building frontend features before the backend is ready AND mock your backend for tests.

State Management

There's been a fair bit of innovation in state management since the early days of Redux, it's worth taking a look again if you're interested in using global state.

Jotai

Jotai describes itself as a primitive state management solution for React, and a competitor to Recoil. It's quite minimalist, meaning less API to learn, and if you understand React's useState hook, you'll probably understand Jotai's useAtom hook.

Mobx

Mobx is a global state management library that requires a bit of a mental model shift to get used to. Once you get it though, Mobx provides a solution to state management and change propagation without the boilerplate.

Recoil

Recoil is a state management library - think Redux meets React Hooks, minus the boilerplate.

Redux Toolkit

Redux Toolkit (or RTK), is the official, opinionated way to manage your state using Redux.

RTK greatly reduces the amount of boilerplate necessary for using Redux, provides sensible defaults, and keeps the same immutable update logic that we know and love.

xstate

XState is a library that lets you formalise your React app as a finite state machine.

State machines aren't a particularly new concept, but developers have only recently started to realise that maybe our apps could be less buggy if we explicitly define the states they can be in, and the inputs required to transition between states.

XState also generates charts for you based on your app's xstate configuration, meaning your documentation will stay up to date as you code.

Zustand

Zustand is another state management library, that aims to be simple and un-opinionated. The main difference is that you use hooks as the main way to fetch state, and doesn't require peppering your app with context providers.

Testing

React Testing Library

React Testing Library (RTL) has become kind of a big deal for testing in React (and other libraries/frameworks). It's now the default testing library that comes with create-react-app.

RTL replaces Enzyme in your testing stack. While both libraries provide methods for rendering React components in tests, RTL exposes functions that nudge developers away from testing implementation details, and towards testing functionality.

Videos

Videos?! You ask? Why yes, dear reader. There are now libraries for making videos in React.

Remotion

Remotion lets you make videos of your React components rendering - whether that involves fetching data from an API and displaying it, or showing cool animations.

When you're starting to write React hooks, it can be hard to understand what's going on with useEffect, particularly if you're trying to translate Hooks to lifecycle methods in class components.

You read everywhere that you shouldn't compare useEffect to lifecycle methods, but then where do you start?

Thankfully, not knowing how useEffect's clean-up function works isn't as bad as getting the dependency array wrong, or passing constantly redeclared functions into useEffect.

That being said though, there are some nifty uses of the clean-up function that you should know about.

useEffect's clean-up function doesn't just run once

If you take nothing else away from this article, remember this: useEffect's clean-up function doesn't just run on unmount (assuming your dependency array isn't empty).

See this often overlooked sentence in the React Hooks API reference:

Additionally, if a component renders multiple times (as they typically do), the previous effect is cleaned up before executing the next effect

So when does clean-up run?

useEffect's clean-up runs after the next render, before the next useEffect.

This might mess with your brain a little bit, but check out this example:

import React, { useEffect, useState } from 'react';

export default function App() {
  const [state, setState] = useState(null);

  useEffect(() => {
    console.log('I am the effect');
    return () => {
      console.log('I run after re-render, but before the next useEffect');
    };
  });

  console.log('I am just part of render');
  return (
    <>
      <button
        onClick={() => {
          setState('Some v. important state.');
        }}
      >
        Click me
      </button>
      <p>state: {state}</p>
    </>
  );
}

| | | :-----------------------------------------------------------------------------------------------------------------------------: | | This example is also available as a CodeSandbox. |

When the above component first renders, in the console you see:

> I am just part of render
> I am the effect

If you then click the button (triggering a re-render), the following lines are printed underneath:

> I am just part of render
> I run after re-render, but before the next useEffect
> I am the effect

Even though the clean-up function is running in the new render, it still has the old prop values since it was declared in the previous render.

More concretely:

useEffect(() => {
  console.log('id: ', id);
  return () => {
    console.log('id: ', id);
  };
}, [props.id]);

• id starts as 1.
• Component renders, displaying id as 1 in the UI
• useEffect runs, calling console.log and prints id: 1
• Props change, setting id to 2
• Component re-renders, displaying id as 2 in the UI
• useEffect clean-up function fires, calling console.log and prints id: 1
• useEffect runs, calling console.log and prints id: 2

What to actually use useEffect's clean-up functions for

Honestly, it's pretty rare that I find a use for useEffect's clean-up function in my day-to-day work as I don't use subscriptions at work (so I never need to unsubscribe from connections in the clean-up function).

You can use it to avoid race conditions in async requests, which is pretty nifty.

From Fixing Race Conditions in React with useEffect:

useEffect(() => {
  // highlight-next-line
  let active = true;

  const fetchData = async () => {
    const response = await fetch(`https://swapi.dev/api/people/${props.id}/`);
    const newData = await response.json();
    // highlight-next-line
    if (active) {
      setFetchedId(props.id);
      setData(newData);
    }
  };

  fetchData();
  // highlight-next-line
  return () => {
    // highlight-next-line
    active = false;
    // highlight-next-line
  };
}, [props.id]);

You can also use an AbortController to cancel your requests instead of a boolean flag, see the example here.

Dedicated unmount hook

While React doesn't have a dedicated unmount hook, you can always use useEffect's clean-up function with an empty dependency array:

import React, { useEffect } from 'react';

const SomeComponent => () => {
     useEffect(() => {
        return () => {
             // This code runs when the component unmounts
         }
     }, [])
     // The rest of your component goes here.
 }

I'm not sure why you'd want this (nor have I needed this), but it's worth knowing that it's possible.

I've been super keen on Gatsby.js since about 2017. Back then, I re-wrote this blog from a clunky old Django site that required an AWS EC2 instance running 24/7 to Gatsby, and it was amazing.

Over time, I've come to notice that Gatsby's core doesn't actually do much, and each project needs a different set of plugins to do what you want, and every new project with Gatsby has completely different headaches, so you never actually get better at using it (as a casual user).

Table of contents

• Background info
  • Content Folder Structure
  • Plugins
• Migrating to Next
  • First steps with Next.js
  • Folder structure and file naming
  • Deleting (almost) everything, and copying my pages across
  • Gatsby Link vs Next.js Link
  • //highlight-next-line: I just want good code snippets in Next.js
  • Autolinking headers in MDX
  • Scrolling to an id
  • Sitemap
  • RSS Feed in Next.js

Background info

So for some background information, MaxRozen.com is where I write weekly articles about React, and occasionally launch products (my most recent being useEffectByExample.com).

Content Folder Structure

When I used Gatsby, all of my content lived in a content/ folder, with a folder named after the date for each post, and the folder containing the markdown and images for the post.

Basically, something like this:

content/
|-- 2021-01-01/
|   |-- index.md
|   |-- cool-image.jpg
|-- 2021-01-08/
|   |-- index.md
|   |-- some-other-image.jpg

Besides that, my site was thankfully pretty straightforward, I had:

• A single template for my articles
• A few pages (home, articles/, newsletter/, uses/)

For styling, I just used Emotion (CSS in JS) with Tailwind via twin.macro (you can read more about that here)

Plugins

I eventually settled on the following core Gatsby plugins for any of my content sites:

• gatsby-plugin-canonical-urls
• gatsby-plugin-emotion
• gatsby-transformer-remark
  • gatsby-remark-autolink-headers
    • gatsby-remark-prismjs
• gatsby-plugin-feed
• gatsby-plugin-react-helmet
• gatsby-plugin-no-javascript
• gatsby-plugin-no-javascript-utils

Since I've come to rely heavily on these plugins in Gatsby, I wanted to figure out how to get the same functionality in Next.js.

If you're keen to find out how I did it, read on.

Migrating to Next

Since I was already using React, very little in my site actually needed to change.

Most of my development effort was in replicating the plugins I loved from Gatsby, and in having to figure out what assumptions code examples in Next.js had (a few, it turns out).

First steps with Next.js

To get started with Next.js, I headed over to their repo, and dove into the examples folder. I searched for "blog", and to my surprise found exactly the example I wanted: "blog-starter-typescript".

From there, I ran create-next-app:

npx create-next-app --example blog-starter-typescript blog-starter-typescript-app
# or
yarn create next-app --example blog-starter-typescript blog-starter-typescript-app

The example came with Tailwind already, so all I had to do was install Emotion, and follow the Next.js + Emotion guide provided by twin.macro to get the same CSS-in-JS + Tailwind setup I was using with Gatsby.

Folder structure and file naming

The examples in Next.js' repo assume you keep your content like this:

content/
|-- your-articles-title.md
|-- some-other-title.md

Whereas I used to keep my content like this:

content/
|-- 2021-01-01/
|   |-- index.md
|   |-- cool-image.jpg
|-- 2021-01-08/
|   |-- index.md
|   |-- some-other-image.jpg

Since Gatsby had a plugin that could recursively dive through your content folder to find all markdown files, my preferred setup worked.

Unfortunately not the case (out of the box) with Next.js, so I had to go through and rename some files.

Deleting (almost) everything, and copying my pages across

With Tailwind and CSS in JS set up, all I had to do was copy over my pages and templates, and delete all of Gatsby's GraphQL.

Whereas in Gatsby I had a templates/article.js file to control how my articles looked, in Next.js if I didn't want my articles in a folder, I had to create a Dynamic route: pages/[slug].tsx.

Dynamic routes get their content via getStaticProps and getStaticPaths (described further here and here).

After digging through how some of the examples used these two functions, it clicked, and I figured out how to make it work for my blog:

• getStaticPaths can be as simple as looping through a directory, and making an array of slugs
• getStaticProps then takes the slug passed in via the URL (for this article, the slug is walkthrough-migrating-maxrozen-com-gatsby-to-nextjs), and fetches the content (and transforming MDX to HTML)

Gatsby Link vs Next.js Link

One weird thing I noticed is a slight implementation difference between Gatsby's Link and Next's Link: while Gatsby would effectively spread props, and pass every prop you provide Link down, Next had a stricter API.

So while in Gatsby this worked:

const StyledLink = tw(Link)`
flex justify-center items-center text-gray-500 hover:text-gray-600
`

<StyledLink to={'/'}>
  Home
</StyledLink>

In Next.js, I had to do this:

const StyledLink = tw.a`
flex justify-center items-center text-gray-500 hover:text-gray-600
`;

<Link passHref href={'/'}>
  <StyledLink>Home</StyledLink>
</Link>;

//highlight-next-line: I just want good code snippets in Next.js

It turns out that the code formatter in Gatsby was extremely smart, and required very little actual setup. Funny how it takes giving something up to really appreciate it.

For example, if you added //highlight-next-line to your code snippet, it would make the line stand out. Like this:

useEffect(() => {
  const fetchData = async () => {
    // highlight-next-line
    const response = await fetch(`https://swapi.dev/api/people/${props.id}/`);
    const newData = await response.json();
    // highlight-next-line
    setData(newData);
  };

  fetchData();
  // highlight-next-line
}, [props.id]);

Because the markdown plugin could handle that for free, I never felt the urge to try out MDX (in case you're wondering what MDX is: check out the docs).

It turned out the "simplest" way to customise code formatting was to rename all of my content from .md to .mdx, and use mdx-remote (see example).

Here's how I managed to customise my code snippets in Next.js:

• First I installed prism-react-renderer. It's a React component that lets you customise what the Prism.js code snippet output looks like.

• Then I added a Code component using prism-react-renderer:

  //components/Code.js
  import React from 'react';
  import Highlight, { defaultProps } from 'prism-react-renderer';
  
  const isHighlightedLine = (line, mark = '// highlight-next-line') =>
    line?.some((prevLine) => {
      return prevLine?.content === mark;
    });
  
  const Code = ({ children, className }) => {
    const language = className?.replace(/language-/, '');
  
    return (
      <Highlight
        {...defaultProps}
        code={children}
        language={language}
        theme={undefined}
      >
        {({ className, style, tokens, getLineProps, getTokenProps }) => (
          <pre
            className={className}
            style={{ ...style }}
            data-language={language}
          >
            {tokens.map((line, i) => {
              const lineProps = getLineProps({ line, key: i });
              const classNameArr = [lineProps.className];
  
              if (isHighlightedLine(line)) {
                return null;
              }
  
              if (isHighlightedLine(tokens?.[i - 1])) {
                classNameArr.push('gatsby-highlight-code-line');
              }
  
              const finalLineProps = {
                ...lineProps,
                className: classNameArr.join(' '),
              };
  
              return (
                <div key={i} {...finalLineProps}>
                  {line.map((token, key) => (
                    <span key={key} {...getTokenProps({ token, key })} />
                  ))}
                </div>
              );
            })}
          </pre>
        )}
      </Highlight>
    );
  };
  
  export default Code;
  

  (My site contains custom CSS that targets gatsby-highlight-code-line, and I didn't want to change it for Next.js)

• Then in my article template ([slug].tsx), I could override the default code markup with my own:

  const components = {
    Head,
    pre: (props: any) => <div className="gatsby-highlight" {...props} />,
    code: Code,
    // ...
  };
  

Autolinking headers in MDX

What I really liked about my Gatsby site was how effortlessly plugins like gatsby-remark-autolink-headers worked. You installed it, and bam: all headings in your markdown content now let you grab the link to that heading.

To get the same behaviour in Next.js, I had to add the following:

• First, install remark-slug and remark-autolink-headings:

  yarn add remark-slug remark-autolink-headings
  

• Then add them to your article template:

  // `[slug].tsx`
  // ...imports etc up here
  
  //svgIcon shamelessly stolen from gatsby-remark-autolink-headers
  const svgIcon = `<svg aria-hidden="true" focusable="false" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg>`;
  
  //then when calling next-mdx-remote's renderToString:
  const mdxSource = await renderToString(content, {
    components,
    // Optionally pass remark/rehype plugins
    mdxOptions: {
      remarkPlugins: [
        // highlight-next-line
        require('remark-slug'),
        [
          // highlight-next-line
          require('remark-autolink-headings'),
          {
            behavior: 'prepend',
            linkProperties: {
              'aria-label': `permalink`, // this could be more useful
              class: 'anchor before',
            },
            content: {
              type: `raw`,
              value: svgIcon,
            },
          },
        ],
      ],
      rehypePlugins: [],
    },
    scope: data,
  });
  

• To get the anchor to actually appear, I added the following to my global CSS:

  .anchor.before {
    position: absolute;
    top: 0;
    left: 0;
    transform: translateX(-100%);
    padding-right: 4px;
  }
  .anchor.after {
    display: inline-block;
    padding-left: 4px;
  }
  h1 .anchor svg,
  h2 .anchor svg,
  h3 .anchor svg,
  h4 .anchor svg,
  h5 .anchor svg,
  h6 .anchor svg {
    visibility: hidden;
  }
  h1:hover .anchor svg,
  h2:hover .anchor svg,
  h3:hover .anchor svg,
  h4:hover .anchor svg,
  h5:hover .anchor svg,
  h6:hover .anchor svg,
  h1 .anchor:focus svg,
  h2 .anchor:focus svg,
  h3 .anchor:focus svg,
  h4 .anchor:focus svg,
  h5 .anchor:focus svg,
  h6 .anchor:focus svg {
    visibility: visible;
  }
  

Scrolling to an id

By default, Next.js doesn't provide anything to make scrolling to an id work (to see what I mean, click here) - that doesn't work by default.

To work around this, I could think of two options:

1. Use useEffect to scroll to the linked id
2. Do it the old school way and use an event listener on DOMContentLoaded

I chose the old fashioned way, so I added this to my _document.tsx:

<script
  dangerouslySetInnerHTML={{
    __html: `
    document.addEventListener("DOMContentLoaded", function(event) {
      var hash = window.decodeURI(location.hash.replace('#', ''))
      if (hash !== '') {
        var element = document.getElementById(hash)
        if (element) {
          var scrollTop = window.pageYOffset || document.documentElement.scrollTop || document.body.scrollTop
          var clientTop = document.documentElement.clientTop || document.body.clientTop || 0
          var offset = element.getBoundingClientRect().top + scrollTop - clientTop
          // Wait for the browser to finish rendering before scrolling.
          setTimeout((function() {
            window.scrollTo(0, offset - 0)
          }), 0)
        }
      }
    })`,
  }}
></script>

Sitemap

Creating a sitemap in Next.js can be done by iterating through your markdown files, the files in the pages/ directory, and wrapping some XML around them.

Here's how I did it:

• In your Next.js app's root folder, create a new folder called scripts, and create a file called generateSitemap.js

• Paste the following, and change the domain name as needed:

  // scripts/generateSitemap.js
  const fs = require('fs');
  
  const globby = require('globby');
  const prettier = require('prettier');
  
  (async () => {
    const prettierConfig = await prettier.resolveConfig('./.prettierrc');
    //exclude pages below by adding ! in front of the path
    const pages = await globby([
      'pages/*.tsx',
      '_content/articles/*.mdx',
      '!pages/404.tsx',
      '!pages/_*.tsx',
      '!pages/[*.tsx',
      '!pages/api',
    ]);
  
    const sitemap = `
          <?xml version="1.0" encoding="UTF-8"?>
          <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
              ${pages
                .map((page) => {
                  const path = page
                    .replace('pages', '')
                    .replace('_posts', '')
                    .replace('.tsx', '')
                    .replace('.mdx', '');
                  const route = path === '/index' ? '' : path;
                  return `
  

const formatted = prettier.format(sitemap, {
  ...prettierConfig,
  parser: 'html',
});

// eslint-disable-next-line no-sync
fs.writeFileSync('public/sitemap.xml', formatted);

})();

- Then add the following to your next.config.js:

```js
// next.config.js
module.exports = {
  // modify your webpack export if you've already got one
  webpack: (config, { isServer }) => {
    if (isServer) {
      require('./scripts/generateSitemap');
    }

    return config;
  },
};

• Finally, add public/sitemap.xml to your .gitignore

This way, Next will only generate the sitemap as part of the build, and not while you're developing/writing articles.

RSS Feed in Next.js

I originally planned on copying the gatsby plugin to recreate my site's RSS feed, before I ran into this blog post by Florian.

The gist of the blog post is to use Feed, an npm package that abstracts away the pain of generating RSS, Atom, and JSON feeds.

Here's how I did it:

• In the scripts folder we created for the sitemap, create a file called generateRss.js

• Install the following packages (if you're not using markdown files, all you need is feed):

  yarn install feed gray-matter remark remark-html
  

• Paste the following, and update the metadata:

  const Feed = require('feed').Feed;
  const fs = require('fs');
  const path = require('path');
  const matter = require('gray-matter');
  const postsDirectory = path.join(process.cwd(), '_content/articles');
  const remark = require('remark');
  const remarkHtml = require('remark-html');
  
  async function markdownToHtml(markdown) {
    const result = await remark().use(remarkHtml).process(markdown);
    return result.toString();
  }
  
  function getPostSlugs() {
    return fs.readdirSync(postsDirectory);
  }
  
  function getPostBySlug(slug, fields = []) {
    const realSlug = slug.replace(/\.mdx$/, '');
    const fullPath = path.join(postsDirectory, `${realSlug}.mdx`);
    const fileContents = fs.readFileSync(fullPath, 'utf8');
    // parse the markdown file
    const { data, content } = matter(fileContents);
  
    const items = {};
  
    // Ensure only the minimal needed data is exposed
    fields.forEach((field) => {
      if (field === 'slug') {
        items[field] = realSlug;
      }
      if (field === 'content') {
        items[field] = content;
      }
  
      if (data[field]) {
        items[field] = data[field];
      }
    });
  
    return items;
  }
  
  function getAllPosts(fields = []) {
    const slugs = getPostSlugs();
    const posts = slugs
      .map((slug) => getPostBySlug(slug, fields))
      // sort posts by date in descending order
      .sort((post1, post2) => (post1.date > post2.date ? -1 : 1));
    return posts;
  }
  
  (async () => {
    if (process.env.NODE_ENV === 'development') {
      return;
    }
    const baseUrl = 'https://YOURDOMAINHERE.com';
    const date = new Date();
    const author = {
      name: 'Some Person',
      email: 'hey@YOURDOMAINHERE.com',
      link: 'https://twitter.com/sometwitterhandlethattotallyexists',
    };
    const feed = new Feed({
      title: `My Awesome site`,
      description: 'This is my Cool RSS Feed',
      id: baseUrl,
      link: baseUrl,
      language: 'en',
      image: `${baseUrl}/images/logo.svg`,
      favicon: `${baseUrl}/favicon.ico`,
      copyright: `All rights reserved ${date.getFullYear()}, Your Name`,
      updated: date,
      generator: 'Next.js',
      feedLinks: {
        rss2: `${baseUrl}/rss.xml`,
        json: `${baseUrl}/feed.json`,
        atom: `${baseUrl}/atom.xml`,
      },
      author,
    });
    const posts = getAllPosts(['title', 'date', 'path', 'excerpt', 'content']);
  
    const postPromises = posts.map(async (post) => {
      const url = `${baseUrl}${post.path}`;
      //convert the markdown to HTML that we'll pass to the RSS feed
      const content = await markdownToHtml(post.content);
  
      feed.addItem({
        title: post.title,
        id: url,
        link: url,
        description: post.excerpt,
        content: content,
        author: [author],
        contributor: [author],
        date: new Date(post.date),
      });
    });
    await Promise.all(postPromises);
  
    fs.writeFileSync('./public/rss.xml', feed.rss2());
    fs.writeFileSync('./public/atom.xml', feed.atom1());
    fs.writeFileSync('./public/feed.json', feed.json1());
  })();
  

• Add the script to the next.config.js file, similar to what we did for the sitemap:

  // next.config.js
  module.exports = {
    // modify your webpack export if you've already got one
    webpack: (config, { isServer }) => {
      if (isServer) {
        //if you followed the sitemap instructions, you only need the next line
        require('./scripts/generateRss');
      }
  
      return config;
    },
  };
  

• Finally, add public/rss.xml, public/atom.xml, and public/feed.json to your .gitignore

If you've ever looked into your network tab when visiting a React app, chances are you've noticed that some apps send their entire bundle to their visitors. You might then wonder, how is that secure? Surely a motivated user could dive through React DevTools and find your protected routes?

First of all, you'd be correct - you won't stop a motivated user from seeing your admin panel UI, but that shouldn't worry us.

Secondly, it's your backend's job to worry about authentication and authorization before sending data to the frontend.

How it works

• When users first load a React app, the user state is empty, meaning the user is unauthenticated
• We protect routes in React by redirecting unauthenticated users to our login page (see React Router example)
• When the user logs in, we send a request to our backend, and check if the credentials are valid (via database query, or passing off the entire exchange to a third-party service like Auth0 or AWS Cognito)
• If the credentials are valid, the backend generates a token that's been signed with a secret we keep in the backend (so we know it's from our backend), and sends the token to the frontend
• Back on the frontend, we keep the token in state so that we stop redirecting users to the login page
• Now that the user can visit protected routes, we also use the token (normally using the Authorization header) in all API requests to our backend
• Our backend checks if the token is signed correctly, as well as which user the token belongs to, and whether the user has permission before sending back any data
  • If the token is invalid, or not provided in the request, the backend sends back a response with a 401 Unauthorized HTTP status
  • If the token is valid, but the user doesn't have permission to view the data, the backend sends back a response with a 403 Forbidden HTTP status
  • We can then display a big ERROR page on our frontend if the API returns a 401 Unauthorized response, and none of our precious data gets send to unauthorized users
• If everything is valid, we display our protected UI along with our data, and the user gets to use your app

Summary

In short, we shouldn't be worried about protecting our frontend from being downloaded. At worst, they'll find out what your admin/protected routes looks like, but won't get anything valuable.

It's the backend's role to ensure the user is both who they say they are, and that they are allowed to see the data.

Building Shopify apps in React and Node the way Shopify teaches you is cool and all, but what if you wanted to take advantage of Next.js API routes, and deploy on Vercel?

Luckily for you - I've scoured the web to figure this out.

Prerequisites

To start off, you're going to want to go through the official Shopify app tutorial.

It's probably one of the best tutorials I've seen for doing anything in React, so just take an hour, and learn how Shopify apps are built.

Actually deploying to Vercel

The issue with the official Shopify tutorial is that it makes you build a Next.js app with a custom server.

In case you don't know (I didn't), you can't deploy custom servers on Vercel:

So we could either re-write the custom server example to use API routes, or find an example on GitHub that does that already.

This repo by bluebeel is the example you're looking for. It even comes with a "Deploy to Vercel" button.

Smash that "Deploy to Vercel" button.

On Vercel, set your SHOPIFY_API_KEY and SHOPIFY_API_SECRET, as well as HOST and NEXT_PUBLIC_HOST (I guessed the Vercel deployment URL and used the same value for these two).

You'll also want to update your Shopify app's "App URL" and "Allowed redirection URL(s)" so that authentication works. At time of writing this was {VERCEL_URL}//api/shopify/auth/callback. Note the double slash there.

Update: as of March 2021, I've received reports that the single slash version now works as expected, so try using {VERCEL_URL}/api/shopify/auth/callback.

Once deployed, and authenticated, eventually you'll see this screen:

Now the real work begins.

If you've looked into adding Tailwind CSS to your React project, chances are you've seen the official installation guides, but what if you're already using Emotion, or styled-components?

Sure, you could probably try some funky combination of className and styled components such as:

const MyStyledDiv = styled.div`
  color: red;
`;

const MyComponent = () => <MyStyledDiv className="mt-4 flex" />;

Assuming that would even work...

But what if you could use Tailwind classnames with your current CSS-in-JS configuration?

Introducing twin.macro

twin.macro by Ben Rogerson lets you write Tailwind CSS inside your CSS-in-JS, lints your Tailwind classnames, and doesn't make your bundle bigger.

twin.macro gives you access to a few things:

• a tw prop on JSX elements:

  import 'twin.macro';
  
  const MyDiv = () => <div tw="border hover:border-black" />;
  

• Tailwind class linting (this is the main reason I use this library):

  ✕ ml-7 was not found
  
  Try one of these classes:
  ml-0 [0] / ml-1 [0.25rem] / ml-2 [0.5rem] / ml-3 [0.75rem] / ml-4 [1rem] / ml-5 [1.25rem] / ml-6 [1.5rem]
  ml-8 [2rem] / ml-10 [2.5rem] / ml-12 [3rem] / ml-16 [4rem] / ml-20 [5rem] / ml-24 [6rem] / ml-32 [8rem]
  ml-40 [10rem] / ml-48 [12rem] / ml-56 [14rem] / ml-64 [16rem] / ml-auto [auto] / ml-px [1px]
  

• The standard Styled Component API:

  import tw from 'twin.macro';
  
  const MyDiv = tw.div`border hover:border-black`;
  // and cloning/styling other components
  const PurpleDiv = tw(MyDiv)`border-purple-500`;
  

• The css prop:

  import tw from 'twin.macro';
  
  const Input = ({ hasHover }) => (
    <input css={[tw`border`, hasHover && tw`hover:border-black`]} />
  );
  

The library currently supports both Emotion and styled-components when using React, Preact, Create React App, Gatsby, Next.js, Snowpack, and more.

You'll want to see the Get started section of the README for instructions on how to install it for your particular combination of CSS-in-JS library and React framework.

Each year I take this time of year to reflect on how I progressed towards my goal of being self-sufficient as a web developer:

• 2018: Reflections on trying to start an internet business
• 2019: Further reflections on trying to start an internet business

This year is no different, even if it was a total mess.

Table of contents

• How I Indiehack
• Investing in tooling
• Books I Read
• Year in review
  • Mercenary for hire
  • Day-rate contracting
  • Startup Tech Stack
  • PerfBeacon on the side
  • Back into stable full-time work
    • Trade-offs, trade-offs everywhere
  • Writing weekly
    • Taking notes
  • Writing a book
• Financials
• Learnings
• How my fourth year is going

How I Indiehack

To save you reading through the previous year's summaries, here's how I indiehack.

I try to keep either a full-time job that doesn't expect me to work 18 hour days to meet tough deadlines, or I take contract/day-rate jobs where I can negotiate to work 4 days a week.

Before and after business hours, and occassionally on weekends, I work on side-projects.

I tend to work in 1-2 hour increments, partly because that's how long I can focus at a time, and partly because I prefer to chip away at a problem, rather than making one big push.

I started the year with the firm belief that running your own one-person SaaS was the only means of starting your own business as a developer. I now see that SaaS is just one type of fix, in a spectrum of fixes - from books/videos/workshops to consulting, to SaaS and other products.

Investing in tooling

I'm not a big fan of re-inventing the wheel when I build my side-projects, so in previous years I invested time in building my own personal framework to spin up SaaS-like solutions.

This time around, instead of investing time, I spent a few hundred dollars on licenses for Tailwind UI and Divjoy (referral link).

I still maintain a terraform config for spinning up the required infrastructure for my projects, but now I don't need to think about styling my side-projects, or fiddly integrations like Auth0 and Stripe.

I was able to productionise a web app for one of my projects this year within a couple of hours thanks to these investments.

Books I Read

Until this year, I rarely sat down to read books. Instead, I'd use my commute time to work to listen to audiobooks. As a result, when 2020 happened and I stopped commuting, I started having to make time to read, and as a result of that, I was much more impatient with boring or long-winded books.

Here are the ones that made the cut:

• This is Marketing - Seth Godin
• How I Built This - Guy Raz
• How to Take Smart Notes - Sönke Ahrens
• Originals - Adam Grant
• Tribes - Seth Godin
• Obviously Awesome - April Dunford
• The Tipping Point - Malcolm Gladwell

Year in review

Mercenary for hire

I started the year completely burnt out from working for companies that claimed to have certain values, while exhibiting behaviour that ran counter to those values.

So I started looking for React gigs where I could jump in, either fix or build a React app, and jump out as the client needed.

Day-rate contracting

At the end of 2019 I complained across my network long enough that I managed to find myself working as a contractor for a scrappy startup building an entire IoT platform (from devices up to a frontend to display data). Thankfully they had hired a consulting company to handle the IoT device and data ingestion, so I only needed to worry about the web platform.

What started off as a couple of weeks to help the company get to demo day ended up being a few months helping build the company's entire tech stack.

As a result, overnight I unofficially became the:

• Product Manager
• Frontend Dev
• Backend Dev
• Data Engineer
• SRE
• DevOps

and it was surprisingly doable, with the right tech stack (Spoiler: I'm a huge fan of Choose Boring Technology).

Startup Tech Stack

I opted for the same tech stack I know and love for my side projects, and it worked quite well.

• For managing tasks/documentation I used Jira and Confluence,
• for the frontend I used React via create-react-app.
• for the backend I used postgres with a node GraphQL server,
• for Infrastructure as Code (IaC) I used terraform,
• and for CI/CD I used CircleCI (though these days I'd probably look at using GitHub Actions).

On the data engineering side of things, we would regularly need to transform ad-hoc user-provided data into a format that our system could understand. Essentially, clients would already have IoT devices from competitors, and we would make it possible for them to join our platform via our data engineering efforts.

I was able to automate most of this using Python and AWS S3's event system, so we wouldn't need to wrangle the client's custom datasets more than once.

Side note: it blew my mind how incumbent companies can still charge $10k+ for systems built more than 20 years ago, that these days could be replaced by an ESP32, wifi/3g modem and a python script. Though being able to compete with these companies requires a large professional network and willingness to run high-touch sales that I don't have.

PerfBeacon on the side

While contracting four days a week, I would also work on PerfBeacon before and after work, as well as on Wednesdays. For those that don't know, PerfBeacon helps you keep your app/site fast by automating Google Lighthouse checks.

I managed to finish building the minimum viable product early this year, and started marketing and sales.

After launching PerfBeacon to the world, I built a quick CRM in Airtable, and started selling it to people in my network. I estimate I spent around 40 hours trying to sell PerfBeacon to my network directly, netting approximately zero in sales.

It didn't take long for me to realise that most of running a side business is marketing, rather than product building. Realising I was terrible at marketing, and didn't really know what I was doing lead me to pay for 30x500.

I still run PerfBeacon, it only takes a couple of hours a month on average to keep it running.

Funnily enough, while job hunting this year I ran into some resistance from startups "wanting me to be 100% focused, even outside of work hours on their project". In other words, I would have to drop my side-projects to be able to work for them. Often within minutes of telling me my "vast experience with React" made my profile interesting (I wouldn't have a vast experience in React without side-projects).

Total non-starter, so I kept looking.

Back into stable full-time work

Effectively doing any one of six jobs each day grew old surprisingly quickly, and by February I started to look for long-term contracts at more established companies.

By chance I decided to reach out to a recruiter from Atlassian that ran me through the interview process a year prior, and I managed to get another run through the interview process to be a frontend developer on the Growth team at Atlassian.

I ended up getting the job, and it's been fantastic.

Trade-offs, trade-offs everywhere

Working at a huge corporation like Atlassian has made me appreciate trade-offs much more than any small company ever did.

We regularly run through DACIs (basically a fancy RFC) when making technical decisions. Where before I'd run a technical decision past an architect/CTO, I'm now able to tap into our entire department's expertise to get more context, and see any gaps in what I'm trying to build.

Writing weekly

I started the year only writing whenever I got inspired (basically, after something made me angry enough to write about it). While cathartic, this didn't do much for people who read my blog.

Instead of focusing on things that annoyed me, in July I decided to focus on regularly helping people. I knew quite a bit about React from using it in production for several years (both on side-projects and at work), so it'd be a shame not to share the knowledge.

Since starting to blog more regularly, I went from an average of 20 readers on my blog per day, to about 140 readers per day on days when I don't post my articles anywhere, up to 2500 a day when I do share my articles.

Taking notes

Writing weekly has become easier as I started to treat my articles like "semi-permanent notes" to myself about certain topics in React.

I tend to take notes (whether in a notebook, on my phone, or on scrap pieces of paper) from wherever I see people discussing React (Twitter threads, reddit posts, etc) and eventually type them up into an article. Eventually, I revise the article as I find new information. A good example of this is Keeping up with React Libraries.

I learned this process after reading How to Take Smart Notes by Sönke Ahrens, which I'd highly recommend to aspiring writers out there.

Writing a book

After writing consistently for a few months, I started to notice the articles that would get significantly more traffic and links than others.

In the end, I decided to write a book to try help people more than a few blog posts ever could. It's called useEffect By Example, and I launched it in January 2021.

Financials

PerfBeacon is now break-even (in terms of running costs), averaging between $1-200 MRR.

Judging by pre-orders alone, useEffect By Example looks like it'll beat PerfBeacon in terms of revenue, even in the long term, and, even though PerfBeacon runs on a recurring subscription model.

I'm still very far from being able to employ myself, but at least now I have a repeatable process that works - writing consistently.

Learnings

SaaS is only one way of solving problems for your customers. Explore all possible means (books, videos, workshops, consulting, code snippets, plugins) of solving a problem before diving into building a SaaS. SaaS is often the most difficult, and time consuming way to run a business, and there are no prizes for playing on hard mode.

Pre-sales are an incredibly powerful tool to gauge buyer interest. Indiehackers can easily start a gumroad pre-sale to take valid credit card details, and only process the payment when they ship.

Write regularly. Similar to running/working out, the more you work out the muscle, the easier it becomes. There are unintentional benefits to this:

• Writing documentation, emails, tickets, etc at work becomes easier
• SEO: the more you write, the more long-tail keywords your articles will pick up - note that helping people is the goal here, not "winning" the top spot on Google
• You grow an audience that wants to see what you're regularly creating
• You get to practice shipping in a way you wouldn't get if you only focused on building product.
  • Building OnlineOrNot and PerfBeacon, I got to experience launch anxiety perhaps once every six months, while with my writing on MaxRozen.com I experience it weekly.
  • This in turn has taught me lessons on editing, marketing, running a newsletter, engaging with the community, and more that I probably don't even realise yet.

How my fourth year is going

In case you're wondering how my fourth year of indiehacking is going, check out my post on building OnlineOrNot.

It's pretty common to ask whether there's a rule of thumb for deciding whether or not something should be a custom hook. While it's down to developer preference how you write your custom hooks, there are still some things that aren't immediately obvious.

Luckily for us, hooks are (almost, but with some caveats) functions, meaning we can extract them and test them as we like.

At the risk of repeating the docs, here's the gist of custom hooks:

• Name your custom hooks starting with use (useDataFetcher, for example)
• Rules of hooks still apply
• You can call other hooks in your custom hooks
• Hooks don't share state, meaning you can use the same hook that uses useState in two different places, and they'll be isolated from each other
• As they're still functions, you can pass the results from one hook as an argument to the next hook

Table of Contents

• Why custom hooks?
• What do custom hooks look like?
• Document your custom hooks!
• Testing custom hooks
• On Folder Structure

Why custom hooks?

Since hooks can be treated as functions in a lot of ways, what we know about functions still applies.

• They're reusable
• We can break our larger hooks into smaller hooks
• We can compose our smaller hooks together, like lego bricks
• They're testable

Sure, you could always re-use the same sequence of hooks in each component (useState, useEffect, update state...), but why repeat yourself several times when you could extract the logic out into a well-tested custom hook?

What do custom hooks look like?

This is a relatively contrived example, but focus on the concepts for a moment.

Say you have a React component that fetches data and displays it:

import React, { useEffect, useState } from 'react';

export default function MyComponent() {
  const [data, setData] = useState(null);
  useEffect(() => {
    const fetchData = async () => {
      const response = await fetch('https://swapi.dev/api/people/1/');
      const newData = await response.json();
      setData(newData);
    };

    fetchData();
  });

  return (
    <div>
      <h1>Hello!</h1>
      {data ? <div>{data.name}</div> : null}
    </div>
  );
}

You decide you want to use the same useEffect logic in another component.

So you extract it into a custom hook:

//useFetchData.js
import { useEffect, useState } from 'react';

export const useFetchData = () => {
  const [data, setData] = useState(null);
  useEffect(() => {
    const fetchData = async () => {
      const response = await fetch('https://swapi.dev/api/people/1/');
      const newData = await response.json();
      setData(newData);
    };

    fetchData();
  });
  return data;
};

Our original component becomes much simpler:

import React from 'react';
import { useFetchData } from './useFetchData';

export default function MyComponent() {
  const data = useFetchData();

  return (
    <div>
      <h1>Hello!</h1>
      {data ? <div>{data.name}</div> : null}
    </div>
  );
}

In the real world, we probably wouldn't extract a data fetcher like this, as it's vulnerable to race conditions and we'd probably use an existing library such as react-query instead of useFetchData.

Document your custom hooks!

As with most things in a large organisation, the more custom hooks your team writes, the easier it is to lose track of them.

I recommend documenting each hook you write. If not for your team, for future-you. Whether it's a README in each hook's folder or a doc in a wiki - ensure people know your hook exists, what it does, and what your intentions were.

Leaving a note like "This was a massive hack where we only covered case X due to this buggy API we use" is significantly more valuable than writing nothing.

Adding JSDOC comments above your hooks is also useful (here's a cheat sheet):

/**
 * This is a JSDOC comment.
 * VS Code's tooltip will show extra information because of me.
 */
const useMyCustomHook = (props) => {
  // ...
};

Don't assume your code is self-documenting/easy enough to understand. Chances are you just think your code is simple because it's still fresh in your mind.

Testing custom hooks

Thanks to React Testing Library's react-hooks-testing-library, it's never been easier to test hooks in isolation.

Here's an example from their docs. Given a hook extracted as useCounter:

//useCounter.js
import { useState, useCallback } from 'react';

function useCounter() {
  const [count, setCount] = useState(0);

  const increment = useCallback(() => setCount((x) => x + 1), []);

  return { count, increment };
}

export default useCounter;

Your tests would look like this:

//useCounter.test.js
import { renderHook, act } from '@testing-library/react-hooks';
import useCounter from './useCounter';

test('should increment counter', () => {
  const { result } = renderHook(() => useCounter());

  act(() => {
    result.current.increment();
  });

  expect(result.current.count).toBe(1);
});

On Folder Structure

As many things in React go, it's up to developer preference how your code is structured. I wrote some words on the topic already, but here's how I would structure my folders when writing custom hooks:

src/
|-- components/
|   |-- Avatar/
|   |   |-- Avatar.js
|   |   |-- Avatar.test.js
|   |-- Button/
|   |   |-- Button.js
|   |   |-- Button.test.js
|-- hooks/
|   |-- useCounter/
|   |   |-- useCounter.js
|   |   |-- useCounter.test.js

Figuring out how and where to deploy React can be pretty confusing. A common question for newcomers from other frameworks is "where does React run?", while others wonder what the best practices for deploying React to production are.

Let's clear up some of that confusion.

Table of Contents

• On static files
• So where does React "run"?
• Deploying React: DIY vs Platforms
  • DIY
  • Platforms

On static files

When using create-react-app, you trigger a React build by running npm run build or yarn build. The output you'd see looks like this:

We call these static files. When building client-side rendered apps (such as when using create-react-app), we only need to worry about where to host these files. Server-side rendering or SSR (running a server that generates the HTML the users see as they request it) also uses these files, but that's for a future article to cover.

Static files are awesome because you technically only need a file host to upload them to, in order to deploy your app. I say technically, because when we deploy to production, we typically also want a CDN and HTTPS to make our app fast and secure around the world.

So where does React "run"?

In short, if you're using create-react-app, React runs in your user's browser. Your static files get sent to them when they visit your app's URL.

Deploying React: DIY vs Platforms

There are two routes to deploying a React app on the internet:

• DIY, or set-up your own infrastructure
• Platforms, such as Netlify and Vercel

DIY

Having worked for some old-school engineers who wanted to be able to see all of the magic before they trusted it, I basically learned how to build React apps while DIYing all of the infrastructure, and CI/CD.

Scaling the client-side part of React isn't particularly challenging: the key to not going offline during high load is a decent CDN, and good caching settings.

To DIY your React production setup, you'll want to:

• Choose a web host
• Choose a CDN provider (particularly one that provides free HTTPS)
• Choose a DNS provider
• Set up CI/CD
  • (not mandatory, I've worked with very small teams that would just use package.json scripts to test and deploy their apps)

These days, I wouldn't particularly recommend small teams use the DIY approach. Your engineers' time is better spent building features or writing tests. God help you if you decide to deploy to Kubernetes before achieving product-market fit.

In my case with the old-school engineers, we had to support government clients, so we wanted to configure every part of the system by hand (via terraform), and to know exactly where our code was being deployed to. We ended up going with AWS to handle hosting (S3), CDN (CloudFront), DNS (Route 53), and CI/CD (Self-hosted Jenkins on AWS).

Years later, I would still pick AWS when going down the DIY route, the thing I'd change is opting for GitHub Actions or CircleCI for CI/CD.

Platforms

Platforms such as Netlify and Vercel are absolute magic compared to the DIY route.

Setting up a project with them is as simple as logging into the platform, authenticating to GitHub, picking a repo, double checking the default settings are correct, and hitting "Done".

For that, you automatically get:

• Hosting
• CDN with free HTTPS
• CI/CD

All that's left to do is point your DNS records to the platform.

You also get access to serverless functions, though limited compared to running directly on AWS.

The other day I setup useEffectByExample.com on Vercel. It took me about two hours total from completely new Next.js app to deployed production-grade React app. Roughly two minutes of which were spent setting up Vercel.

So you've got a component that fetches data in React. The component accepts an id as a prop, uses the id to fetch data with useEffect, and display it.

You notice something strange: sometimes the component displays correct data, and sometimes it's invalid, or out of date.

Chances are, you've run into a race condition.

You would typically notice a race condition (in React) when two slightly different requests for data have been made, and the application displays a different result depending on which request completes first.

In fetching data with useEffect, we wrote a component that could have a race condition, if id changed fast enough:

import React, { useEffect, useState } from 'react';

export default function DataDisplayer(props) {
  const [data, setData] = useState(null);

  useEffect(() => {
    const fetchData = async () => {
      const response = await fetch(`https://swapi.dev/api/people/${props.id}/`);
      const newData = await response.json();
      setData(newData);
    };

    fetchData();
  }, [props.id]);

  if (data) {
    return <div>{data.name}</div>;
  } else {
    return null;
  }
}

It might not seem obvious that the snippet above is vulnerable to race conditions, so I cooked up a CodeSandbox to make it more noticeable (I added a random wait period of up to 12 seconds per request).

You can see the intended behaviour by clicking the "Fetch data!" button once: a simple component that displays data in response to a single click.

Things get a bit more complicated if you rapidly click the "Fetch data!" button several times. The app will make several requests which finish randomly out of order. The last request to complete will be the result displayed.

The updated DataDisplayer component now looks like this:

export default function DataDisplayer(props) {
  const [data, setData] = useState(null);
  const [fetchedId, setFetchedId] = useState(null);

  useEffect(() => {
    const fetchData = async () => {
      // highlight-next-line
      setTimeout(async () => {
        const response = await fetch(
          `https://swapi.dev/api/people/${props.id}/`
        );
        const newData = await response.json();

        setFetchedId(props.id);
        setData(newData);
        // highlight-next-line
      }, Math.round(Math.random() * 12000));
    };

    fetchData();
  }, [props.id]);

  if (data) {
    return (
      <div>
        <p style={{ color: fetchedId === props.id ? 'green' : 'red' }}>
          Displaying Data for: {fetchedId}
        </p>
        <p>{data.name}</p>
      </div>
    );
  } else {
    return null;
  }
}

Fixing the useEffect race condition

There are a couple of approaches we can take here, both taking advantage of useEffect’s clean-up function:

• If we're okay with making several requests, but only rendering the last result, we can use a boolean flag.

• Alternatively, if we don't have to support users on Internet Explorer, we can use AbortController.

useEffect Clean-up Function with Boolean Flag

First, the gist of our fix in code:

useEffect(() => {
  // highlight-next-line
  let active = true;

  const fetchData = async () => {
    setTimeout(async () => {
      const response = await fetch(`https://swapi.dev/api/people/${props.id}/`);
      const newData = await response.json();
      // highlight-next-line
      if (active) {
        setFetchedId(props.id);
        setData(newData);
      }
    }, Math.round(Math.random() * 12000));
  };

  fetchData();
  // highlight-next-line
  return () => {
    // highlight-next-line
    active = false;
    // highlight-next-line
  };
}, [props.id]);

This fix relies on an often overlooked sentence in the React Hooks API reference:

Additionally, if a component renders multiple times (as they typically do), the previous effect is cleaned up before executing the next effect

In the example above:

• changing props.id will cause a re-render,
• every re-render will trigger the clean-up function to run, setting active to false,
• with active set to false, the now-stale requests won't be able to update our state

You'll still have a race-condition in the sense that multiple requests will be in-flight, but only the results from the last one will be used.

It's likely not immediately obvious why the clean-up function in useEffect would fix this issue. I'd recommend you see this fix in action, by checking out the CodeSandbox (I also added a counter to track the number of active requests, and couple of helper functions).

useEffect Clean-up Function with AbortController

Again, let's start with the code:

useEffect(() => {
  // highlight-next-line
  const abortController = new AbortController();

  const fetchData = async () => {
    setTimeout(async () => {
      try {
        const response = await fetch(`https://swapi.dev/api/people/${id}/`, {
          // highlight-next-line
          signal: abortController.signal,
        });
        const newData = await response.json();

        setFetchedId(id);
        setData(newData);
        // highlight-next-line
      } catch (error) {
        // highlight-next-line
        if (error.name === 'AbortError') {
          // highlight-next-line
          // Aborting a fetch throws an error
          // highlight-next-line
          // So we can't update state afterwards
          // highlight-next-line
        }
        // Handle other request errors here
      }
    }, Math.round(Math.random() * 12000));
  };

  fetchData();
  // highlight-next-line
  return () => {
    // highlight-next-line
    abortController.abort();
    // highlight-next-line
  };
}, [id]);

As with the previous example, we've used the fact that React runs the clean-up function before executing the next effect. You can check out the CodeSandbox too (this time we're not counting the number of requests as there can only be one at any time).

However, this time we're:

• initialising an AbortController at the start of the effect,
• passing the AbortController.signal to fetch via the options argument,
• catching any AbortErrors that get thrown (when abort() is called, the fetch() promise rejects with an AbortError, see MDN reference), and
• calling the abort function inside the clean-up function

With this example, we're faced with the following trade-off: drop support for Internet Explorer/use a polyfill, in exchange for the ability to cancel in-flight HTTP requests.

Personally, I'm lucky enough to work for a company where Internet Explorer is no longer supported, so I'd prefer to avoid wasting user bandwidth and use AbortController.

So you're building a component, and need to fetch some data from an API before rendering your component. You've been told that useEffect is the way for fetching data, but all you can find is discussion about side-effects (particularly in the official useEffect docs).

Let's unpack what side-effects are, and fetch ourselves some data.

What are side-effects?

To talk about side-effects, we should probably first talk about pure functions.

A pure function is a function, that when given an input, will always returns the same output. Pure functions also don't modify the arguments passed to them.

While you can have pure functions as simple as this:

function myPureFunction(count) {
  return count + 1;
}

We can also have pure functions that return JSX in React:

function MyComponent(props) {
  return <div className={props.className}>Some content goes here</div>;
}

Side-effects then, are operations that change things outside of your function, making the function impure.

Fetching data from an API, communicating with a database, and sending logs to a logging service are all considered side-effects, as it's possible to have a different output for the same input. For example, your request might fail, your database might be unreachable, or your logging service might have reached its quota.

This is why useEffect is the hook for us - by fetching data, we're making our React component impure, and useEffect provides us a safe place to write impure code.

Fetching data

Here's how to use useEffect to only fetch data (there are a few more steps to make it useful):

useEffect(() => {
  const fetchData = async () => {
    const response = await fetch(`https://swapi.dev/api/people/1/`);
    const newData = await response.json();
  };

  fetchData();
});

You might notice a few things are missing from this example:

• we're not doing anything with the data once we fetch it
• we've hardcoded the URL to fetch data from

To make this useEffect useful, we'll need to:

• update our useEffect to pass a prop called id to the URL,
• use a dependency array, so that we only run this useEffect when id changes, and then
• use the useState hook to store our data so we can display it later

useEffect(() => {
  const fetchData = async () => {
    // highlight-next-line
    const response = await fetch(`https://swapi.dev/api/people/${props.id}/`);
    const newData = await response.json();
    // highlight-next-line
    setData(newData);
  };

  fetchData();
  // highlight-next-line
}, [props.id]);

Now let's build the rest of the component. It needs to:

• store our fetched data using useState
• render part of the data when we do have data
• render nothing if we don't have data

import React, { useState } from 'react';

export default function DataDisplayer(props) {
  // highlight-next-line
  const [data, setData] = useState(null);
  // highlight-next-line
  if (data) {
    return <div>{data.name}</div>;
    // highlight-next-line
  } else {
    return null;
  }
}

Finally, putting our pure React component together with our side-effect:

import React, { useEffect, useState } from 'react';

export default function DataDisplayer(props) {
  const [data, setData] = useState(null);

  useEffect(() => {
    const fetchData = async () => {
      const response = await fetch(`https://swapi.dev/api/people/${props.id}/`);
      const newData = await response.json();
      setData(newData);
    };

    fetchData();
  }, [props.id]);

  if (data) {
    return <div>{data.name}</div>;
  } else {
    return null;
  }
}

You might find fetching data in this way results in quite a bit of repeated code, especially if you're using fetch, and handle error and loading states. To avoid this, a common solution is to write a custom hook.

One caveat however: this code works fine if you want to fetch data once - but if you attach a button to let users change id too quickly, you'll run into a race condition!

You might also want to read this article about fixing race conditions with useEffect.

If you also want caching (to avoid requesting the same data twice), I highly recommend looking into one of these data fetching libraries instead.

After publishing my previous article tracking React Libraries worth talking about, a few people asked me how I decide which library to use in my own projects.

Truth is, I don't have a single hard and fast rule, but rather a feeling that comes from looking at how a library stacks up against a set of quick checks that I've developed over the years of being burned by dodgy libraries.

I've also been asked this several times over the years as an interview question for frontend developer roles. I've heard different answers every time I asked the question back to the interviewer - keep in mind that some teams care about different things, and you might have to decide for yourself.

Also, if you strongly disagree with these points, feel free to write up an article, and share it with me! I'm genuinely interested in what other developers look at when picking their libraries.

Docs

One of the first things I check before installing a library is the documentation.

• Are the docs up to date?
• Are they versioned (if the maintainers update the library over time, can I go back and still read the docs from the version I use)?
• Are they detailed enough that I can figure out how to use the library for my use case?

Issues

I also check GitHub Issues to see if the library still works, and to see how active the maintainers are. Not so much to outright reject libraries with inactive maintainers, but more to guide my expectations.

• Will I have to support myself/contribute before I can even use the library?
• Are there glaring open issues that I might care about, such as the library not working any more, or not supporting certain use cases.

Browser/Mobile Compatibility

Especially in the case of Component/UI libraries, I want to know the extent of browser and mobile support. I wouldn't always check this, but checking GitHub Issues for problems with browsers can save you pain later.

Unfortunately there are still end-users out there that still want IE11 to be supported (particularly government agencies), so some teams may wish to check for Internet Explorer compatibility when picking libraries.

Library size

If a library is small enough, or I only need a small portion of the library, I might not even install it with yarn or npm. I'll just copy the function into a utils folder and write my own tests for it.

In the end, we're hunting for functionality, and I'd prefer to avoid writing fresh code where possible. If a library exists, you may as well use it rather than writing your own from scratch.

Side note: I witnessed the cost of ignoring this, particularly with SWR - a team I worked with implemented their own version, experienced and fixed the same bugs/pitfalls, and learned the same lessons in state and cache management. Easily hundreds of hours that could have been saved with a yarn add swr/npm install swr.

On the other hand, is it too big? Unless I'm building a super quick prototype, I will always compare libraries in Bundlephobia, and prefer the smaller library (and consider the other points in this article).

Examples

If I have to choose between two libraries, (and all else being equal), I'd pick the one with examples. Bonus points for using CodeSandbox or providing running examples that I can copy paste out of the repo.

If you want to see how well this can be done in the React ecosystem, see Razzle and React Hook Form.

Popularity

I'd be lying if I said popularity didn't bias my decision, so I've included it in this article. That being said though, I wouldn't shy away from being an early adopter of a library if it solved a problem I was looking to fix.

There are a few means of understanding how popular a library is:

• Number of stars on GitHub, combined with "Used by" on GitHub

  (In my opinion) the number of stars alone will just tell you how many blog posts people write about a library, and how famous the maintainers are. Combining the number of stars with the number of projects that use the library as a dependency gives you a better understanding of whether it's actually used.

• Weekly downloads on npm

  It's worth keeping in mind that this number is not always bulletproof.

  For example, @testing-library/react recently beat enzyme on weekly downloads, however @testing-library/react is now downloaded as part of create-react-app, regardless of whether it's used or not.

Summary

In conclusion, this article was an attempt at explaining what I look at (often without even realising) when deciding to use a library.

Different developers will have different opinions and criteria - we haven't all had the same career, we've all seen and experienced different things to shape what we value.

If you're just starting out in the frontend, hopefully this article gives you guidance in terms of what to look for.

It's pretty common for people to say

Don't use useCallback/useMemo everywhere!

Without actually explaining cases where you would want to use useCallback/useMemo.

In my last article we learned that useCallback is useful for passing stable references to functions down to the children of a React component, particularly when using those functions in a child's useEffect.

If you're scratching your head wondering "...but then, what the hell is useMemo for?", you're not alone!

One hint that the React docs give is:

useCallback(fn, deps) is equivalent to useMemo(() => fn, deps).

Which is great if you're well versed on the significance of passing a function reference versus passing an arrow function that calls the function (while quickly scanning docs for an answer), but for the rest of us, hopefully this article will help.

What useMemo does

In short, useMemo calls a function when dependencies change, and memoizes (remembers) the result of the function between renders.

This is in contrast with useCallback which remembers an existing value (typically a function's definition), between renders.

You want to use useMemo to save yourself from rerunning an expensive calculation to generate a new value, and you want to use useCallback to store an existing value.

When to use useMemo

This part is where it's easy to get frustrated. There are a lot of blog posts out there describing useMemo, and then presenting examples of when not to use it.

Unfortunately, it needs repeating: don't use useMemo until you notice parts of your app are frustratingly slow. "Premature optimisation is the root of all evil", and throwing useMemo everywhere is premature optimisation.

Here are a couple of cases when you should consider using useMemo:

• You're noticing a component's render is frustratingly slow, and you're passing a calculation to an unknowable number of children, such as when rendering children using Array.map()
• Your app often becomes unresponsive because you're fetching a large amount of data, and having to transform it into a usable format

The key is to focus on the problem.

"My app is slow, and calculation-heavy" is a problem that useMemo helps to solve. Run your app through React DevTools Profiler, as well as Google Lighthouse or WebPageTest to understand its performance metrics, wrap your calculation in useMemo, then measure again.

"I just learned useMemo, and want to use it everywhere" is focusing on the solution, and will lead you to premature optimisation, and a potentially slower app.

Why not use useMemo everywhere then?

In short, it's not a free performance optimisation.

There's an additional cost (memory usage, for one) incurred when setting up useMemo, that can very quickly outweigh the performance benefit of remembering every single function's possible value.

When we use useMemo, we're taking up more memory in order to free up CPU time. If your app is hammering the CPU with a lot of calculations, that's when you might consider taking up some memory and use useMemo instead.

What about stable references?

If you want to keep a stable reference to an object/array that doesn't require recalculation, consider using useRef.

On the other hand if you need to recalculate the value when dependencies change, useMemo is the hook for you.

Potential mistakes when using useMemo

Using useMemo isn't free of pitfalls as well - one of the big ones is that the cache isn't guaranteed to keep all of its values between renders. Taken from the docs:

You may rely on useMemo as a performance optimization, not as a semantic guarantee

Translation: the cache isn't stable!

Meaning if you absolutely want to avoid recalculations with your useMemo call, it's not guaranteed. For a version of useMemo with a stable cache, see useMemoOne.

What happens if you add a function to your useEffect's dependency array, and suddenly start to get infinite re-renders?

Chances are, you've run in to the perfect opportunity to use useCallback!

The syntax is:

const memoizedCallback = useCallback(() => {
  doSomething(a, b);
}, [a, b]);

useCallback returns you a new version of your function only when its dependencies change. In the example above, that's only when a or b changes.

This means even when your component re-renders, you can be sure your function wrapped in useCallback won't be re-declared, preventing the dreaded infinite re-render/useEffect loop.

Before we go too far with useCallback, let's have a quick refresher on React components.

Quick refresher

Here's a React component that renders a child component. Occassionally, something will happen that will make the component re-render (such as props changing, or useState being called).

function SomeComponent(props) {
  //do some other stuff here that might cause re-renders, like setting state
  return <DataFetcher />;
}

Now, if we wanted to pass <DataFetcher/> a prop, such as a function that generates a URL to fetch data from, you might define a function as follows:

function SomeComponent(props){
  // highlight-next-line
  function getUrl(id){
    // highlight-next-line
    return "https://some-api-url.com/api/" + id + "/"
    // highlight-next-line
  }
  //do some other stuff here that might cause re-renders, like setting state
  return <DataFetcher getUrl={getUrl}>
}

Before we had to worry about hooks, we could define a function in a class, and pass it down to children that could fire off this.getUrl(id) without a worry. However, now that we're in a function component, the way we've defined getUrl means something different.

Since by default all of SomeComponent's code re-runs on render, getUrl gets re-defined every render.

If DataFetcher then uses getUrl as part of a useEffect hook, even if you add getUrl to the dependency array, your useEffect would fire every single render.

useEffect(() => {
  fetchDataToDoSomething(getUrl);
}, [getUrl]); // 🔴 re-runs this effect every render

How do we stop useEffect from running every render?

Back in SomeComponent, we have two options to deal with this (assuming we can't just move getUrl into the troublesome useEffect hook).

1. The old fashioned way: move getUrl outside of the component, so it doesn't get re-declared every render:

   // highlight-next-line
   function getUrl(id){
      // highlight-next-line
      return "https://some-api-url.com/api/" + id + "/"
      // highlight-next-line
   }
   
   function SomeComponent(props){
      //do some other stuff here that might cause re-renders, like setting state
      return <DataFetcher getUrl={getUrl}>
   }
   

2. The Hooks way, which is to wrap getUrl in a useCallback:

   function SomeComponent(props){
    // highlight-next-line
      const getUrl = useCallback(function (id) {
      // highlight-next-line
        return "https://some-api-url.com/api/" + id + "/";
      // highlight-next-line
      }, []); // <-- Note that we can't add id to the deps array in this case
   
      //do some other stuff here that might cause re-renders, like setting state
      return <DataFetcher getUrl={getUrl}>
   }
   

   Of course, this is a pretty simplified example to illustrate what you could do to fix much more complicated code.

   I'm not suggesting you should pass a function that returns a string in your real code, when you could pass the string, and avoid using useCallback/useMemo everywhere.

The key takeaway here is that useCallback returns you a new version of your function only when its dependencies change, saving your child components from automatically re-rendering every time the parent renders. This is particularly useful when used with useEffect, as we can safely add functions wrapped in useCallback to the dependency array without fear of infinite re-renders.

Ever find yourself chasing weird bugs in React, like sometimes it seems as though your components fetch all of the data they need, and sometimes they don't?

Chances are you've probably got yourself a race condition.

That's the special insight I'm giving you after spending several days at work chasing weird behaviour in one of our React apps, that could only be reproduced once in 75 page refreshes.

In case you're wondering, here's some backstory.

Imagine your web app needs to make calls to several APIs to get the information it needs to render your component:

useEffect(() => {
  // assume these API calls just write to a global state store
  // and the input state is also coming from that global state store
  getDataFromFirstAPI(someState);
  getDataFromSecondAPI(someOtherState);
  getDataFromThirdAPI(someThirdState);
}, [someState, someOtherState]);

What would happen is that either of getDataFromFirstAPI or getDataFromSecondAPI could mutate the value of someThirdState (as a feature of our particular implementation), making calls to getDataFromThirdAPI use stale data.

Sharp readers will notice the fix pretty quickly: someThirdState is missing from the dependency array, but if your component was complex and had several useEffect calls already, chances are you probably wouldn't notice it. Especially if several of those useEffect calls also have missing dependencies.

In fact, create-react-app would only tell you about it via a warning, not an error. In our case, the warning would be buried deep in a stack of noisy logs (as part of the review into this type of bug, as a team we decided to make it an error, but it's up to you and your team).

Turns out there's an eslint rule specifically for this class of bug: react-hooks/exhaustive-deps, AND it's part of a package maintained by the React team.

That's where eslint-plugin-react-hooks comes in. You already have it if you use create-react-app, but chances are you don't have it if you've decided to go with a custom webpack config.

You add it via npm/yarn:

yarn add eslint-plugin-react-hooks -D
# OR
npm i eslint-plugin-react-hooks -D

Afterwards, you can add it to your ESLint config like so:

// Your ESLint configuration
{
  "plugins": [
    // ...
    "react-hooks"
  ],
  "rules": {
    // ...
    "react-hooks/rules-of-hooks": "error", // Checks rules of Hooks
    // highlight-next-line
    "react-hooks/exhaustive-deps": "warn" // Checks effect dependencies
  }
}

Now every time you hit save in your codebase with missing dependencies in your useEffects, you'll have a similar warning/error to this show up:

Compiled with warnings.

./src/App.js
  Line 16:6:  React Hook useEffect has a missing dependency: 'someThirdState'. Either include it or remove the dependency array  react-hooks/exhaustive-deps

Search for the keywords to learn more about each warning.
To ignore, add // eslint-disable-next-line to the line before.

Since enabling the react-hooks/exhaustive-deps rule, I've already saved myself hours of head scratching and general outrage by saving myself from committing buggy code several times.

Do yourself a favour and check if you've got the rule enabled.

React has a lot of jargon and three-letter acronyms. Even as an intermediate React developer you might find yourself forgetting what certain things mean.

Got any React terms or expressions you'd like defined here? Feel free to message me via Email or BlueSky.

Table of Contents

• Table of Contents
  • Class Component
  • Component
  • CRA
  • Enzyme
  • ESLint
  • Functional Component
  • Flow
  • Higher-order component
  • HOC
  • Hooks
  • Jest
  • Linting
  • Props
  • PropTypes
  • React Testing Library
  • Ref
  • RTL
  • Stateless Functional Component
  • Styled Components
  • TypeScript
  • webpack

Class Component

At its simplest, a Class Component is a component written using a JavaScript ES6 Class.

class Welcome extends React.Component {
  render() {
    return <h1>Hello, {this.props.name}</h1>;
  }
}

Component

A Component is (most-commonly) a function that accepts props, and returns things to display in the browser.

See also: Class Component, Functional Component

CRA

CRA, or create-react-app, refers to a set of scripts open sourced by Facebook to make it easier to get started with your React app. It comes with its own opinions on webpack, testing, and linting.

CRA has become more popular recently as developers begin to realise maintaining their own webpack config and keeping related dependencies up to date isn't worth the time or energy.

Links: docs | website

Enzyme

Enzyme is a utility that renders React components in tests, and provides methods for querying their state and props.

Used in conjunction with Jest.

Links: docs | npm

ESLint

ESLint is a program that is run to analyse your codebase, typically looking for ways to improve your code.

These "ways to improve your code" are typically distributed as a set of rules, such as eslint-config-react-app.

Some sets of rules are considered highly opinionated (such as eslint-config-airbnb), and aren't recommended for use as often.

Links: docs | website

Functional Component

A component written using a JavaScript function.

Thanks to the advent of Hooks, Functional components are considered "the way" components are written now.

Functional components can be written either by using an arrow function, or using the function keyword.

Using an arrow function:

const Welcome = (props) => {
  return <h1>Hello, {props.name}</h1>;
};

Using the function keyword:

function Welcome(props) {
  return <h1>Hello, {props.name}</h1>;
}

Flow

A type checker that can analyse types on any function, not just React components. It also checks your code at compile-time, rather than run-time.

Has fallen by the wayside due to TypeScript's meteoric rise to fame, thousands of unresolved GitHub issues, and sluggish performance.

Links: docs | website

Higher-order component

A fancy way of saying a component whose sole purpose is to wrap other components and pass props.

Links: docs

HOC

See Higher-order component

Hooks

Hooks let developers use state and other React features previously only available in class components, in functional components.

Links: docs | hooks reference | rules of hooks

Jest

Jest is a testing framework responsible for running your tests. Supports both Node and React (and other JS frameworks/languages).

Links: docs | website

Linting

Linting means to run a program that analyses your code for issues. Issues could mean syntax or style issues, as well as potential bugs.

The most commonly used linter in React is ESLint.

Props

Props are arguments you pass as input to a component in React.

PropTypes

PropTypes is a package (once part of React) that provides runtime type checking for your React components' props. It was one of the first ways to type-check React code.

Effectively superseded by Flow and TypeScript.

Usage (from the docs):

import React from 'react';
import PropTypes from 'prop-types';

class MyComponent extends React.Component {
  render() {
    // ... do things with the props
  }
}

MyComponent.propTypes = {
  // These are optional by default
  optionalArray: PropTypes.array,
  optionalFunc: PropTypes.func,
  optionalNumber: PropTypes.number,
  optionalString: PropTypes.string,
  requiredFunc: PropTypes.func.isRequired,

  // A value of any data type, required
  requiredAny: PropTypes.any.isRequired,
};

Links: npm | repo

React Testing Library

This is a library for testing React, literally named "React Testing Library". It's also commonly referred to as RTL.

RTL grew in popularity due to its focus on testing functionality, not implementation details, as well as its inclusion in create-react-app.

Recently became popular over existing library Enzyme. Both libraries provide methods for rendering React components in tests, however RTL exposes functions that nudge developers away from testing implementation details.

Links: npm | website

Ref

Ref, short for reference, is used for accessing and modifying the child of a React component.

Usage:

function MyFunctionalComponent() {
  const myDiv = useRef(null);

  return <div ref={myDiv} />;
}

Particularly useful when integrating with legacy libraries that modify the DOM, and you just want to fetch a value from the DOM and continue using React.

Links: docs

RTL

See React Testing Library.

Stateless Functional Component

How we used to call Functional Components before Hooks were added to React.

Basically, a stateless functional component is a functional component:

function Welcome(props) {
  return <h1>Hello, {props.name}</h1>;
}

Styled Components

Styled Components is a library that allows developers to style their components by writing CSS in their JavaScript files (a solution known as CSS-in-JS).

Links: docs | website

TypeScript

A typed language that compiles to JavaScript, TypeScript rapidly checks types across your entire codebase at compile-time.

Now (optionally) included as part of CRA.

Links: cheatsheet | free book | handbook | website

webpack

webpack (with a lower-case w), is a program that reads through your codebase, follows your imports and exports, removes unused code, and outputs a bundle ready to be served by a server.

When reading webpack's docs, pay close attention to the version (in the top left hand corner). As the API greatly changes between major versions, you may think you've found a solution to your problems, but it may be unavailable in your version of webpack.

Links: docs | website

Do you sometimes worry that your tests don't make sense? Struggling to get what people mean by "test from the user's perspective" and the classic piece of advice "test functionality, not implementation details"?

You're not alone!

I felt the same thing when I moved from Enzyme to React Testing Library. I used to think of testing as just checks you had to do on individual components, directly asserting against props and state, and would struggle to think about how to test the integration of several components together.

What does "integration test" even mean?

It helps to think of integration testing like a bigger unit test, except the unit you're testing is the combination of several smaller components.

More concretely, instead of just testing a Button component, or a TextField component in isolation, we're going to test that they work when placed together into a form.

Let's get started!

We're going to be testing a form almost every public web app you're going to build has: a Login form. It's probably one of the most important parts of your app (in terms of business value), so let's be confident it actually works!

Setup

We're going to be using create-react-app, because it comes bundled with @testing-library/react. I'm also using react-hook-form to build our form, because it's the quickest way I could think of to display the form data in our web app.

You can either:

1. Clone the repo
2. Follow the steps below to set this up manually (you'll still need to download the repo)

Manual steps

1. Run:

   npx create-react-app <YOUR_APP_NAME>
   

2. Run:

   cd <YOUR_APP_NAME>
   

3. [Only for react-hook-form] Run:

   yarn add react-hook-form mutationobserver-shim
   # OR
   npm install react-hook-form mutationobserver-shim
   

4. [Only for react-hook-form] In src/setupTests.js, in a new line, add import 'mutationobserver-shim';

5. Copy the src/ directory from the repo into your src/ directory, overriding existing files

6. Run:

   yarn start
   

   You should see something like this:

7. At this point, if you ran yarn test, you would see the following:

 PASS  src/pages/Login.test.js
  ✓ renders all inputs (75ms)
  ✓ integration test (110ms)

Test Suites: 1 passed, 1 total
Tests:       2 passed, 2 total
Snapshots:   0 total
Time:        3.883s
Ran all test suites.

Watch Usage: Press w to show more.

So how do we get here?

Let's start off with a render test:

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

test('renders all inputs', () => {
  const { getByLabelText } = render(<Login />);

  // here we're using regex so that updating the
  // component to UPPER CASE won't fail the test
  const userInput = getByLabelText(/username/i);
  expect(userInput).toBeInTheDocument();

  const passwordInput = getByLabelText(/password/i);
  expect(passwordInput).toBeInTheDocument();
});

It's not the most complicated test out there, and it's already giving us benefits beyond what a unit test would give. It's also technically an integration test.

In particular, we're saying "on my login form, I want a username input to be visible at the same time as the password input".

Now let's test the happy path of our login form:

import React from 'react';
import { render, fireEvent } from '@testing-library/react';
import user from '@testing-library/user-event';
import Login from './Login';

test('integration test', async () => {
  const USER = 'some-username';
  const PASS = 'some-pass';

  const { getByLabelText, findByText, getByText } = render(<Login />);

  const userInput = getByLabelText(/username/i);
  user.type(userInput, USER);

  const passwordInput = getByLabelText(/password/i);
  user.type(passwordInput, PASS);

  const submitButton = getByText(/submit/i);
  fireEvent.click(submitButton);
  expect(await findByText(/your username/i)).toBeInTheDocument();
  expect(await findByText(/your password/i)).toBeInTheDocument();
});

This integration test builds on top of our initial test in a few ways:

• We've imported the '@testing-library/user-event' library to allow us to type into our inputs
• We've imported fireEvent from the '@testing-library/react' library to allow us to click on our Button component
• We've marked the test async to enable us to use findByText()
  • findByText is neat because it returns a Promise, letting us wait until it finds the text it's looking for before continuing
• Most importantly, we've built a test that can type into our TextField components, click on our Button component, and trigger the Form component's onSubmit function!

If you're confused about findByText vs getByText, don't worry - that's normal. React Testing Library's cheatsheet has tips to help you decide which one to use.

Conclusion

You've just started to understand integration testing, but you best believe there's a lot more to it than this article!

If you want a more advanced perspective of integration testing your forms, I highly recommend reading the testing section of React Hook Form's Advanced Usage guide.

If you've done any amount of research into the best way to structure your React app's folders, you've probably run into the following advice copy-pasted into forum threads:

Move files around until it feels right.

To me that reads a lot like unhelpfully telling people to RTFM, so let's develop a better answer than that (the quote originated from Dan Abramov in a long-ago deleted Tweet, and has since taken on a life of it's own).

Folder structures for React apps

I'll start by showing you the folder structure I tend to use, then teach you the guiding principles I use for my structure to "feel right" for my purposes.

My Project Structure

src/
|-- components/
|   |-- Avatar/
|   |   |-- Avatar.ts
|   |   |-- Avatar.test.ts
|   |-- Button/
|   |   |-- Button.ts
|   |   |-- Button.test.ts
|   |-- TextField/
|   |   |-- TextField.ts
|   |   |-- TextField.test.ts
|-- contexts/
|   |-- UserContext/
|   |   |-- UserContext.ts
|-- hooks/
|   |-- useMediaQuery/
|   |   |-- useMediaQuery.ts
|-- pages/
|   |-- UserProfile/
|   |   |-- Components/
|   |   |   |-- SomeUserProfileComponent/
|   |   |   |   |-- SomeUserProfileComponent.ts
|   |   |   |   |-- SomeUserProfileComponent.test.ts
|   |   |-- UserProfile.ts
|   |   |-- UserProfile.test.ts
|   |-- index.ts
|-- utils/
|   |-- some-common-util/
|   |   |-- index.ts/
|   |   |-- index.test.ts
|-- App.ts
|-- AuthenticatedApp.ts
|-- index.ts
|-- UnauthenticatedApp.ts

Guiding Principles

• Folder structures for React apps
  • My Project Structure
  • Guiding Principles
    • 1. On testing
    • 2. Naming your component files
    • 3. Separate your pages from your components
    • 4. Keep styled components in your component files
    • 5. Split things out only when you need to
    • 6. [Advanced] Split up your codebase by team

1. On testing

Many guides out there will suggest using a __tests__ folder whose structure mimics your app's.

I strongly suggest you avoid this pattern for two reasons:

1. You'll discourage newcomers from testing by hiding your tests
2. You'll need to refactor to keep in sync every time you want to move your components/pages around

Instead, use either an index.test.ts file, or a MyComponent.test.ts file. Keep your tests with your components so you remember to test them.

2. Naming your component files

There are two ways you can name your component files:

1. index.ts

   The advantage of naming your file index.ts is that that you don't repeat yourself - you've already named the folder MyComponent/, why name the file the same?

   The disadvantage is that when you search for index.ts you'll have dozens (if not hundreds, or thousands) of index.ts files, making it hard to find the file you're looking for.

2. MyComponent.ts

   The advantage of using MyComponent.ts is that VS Code and similar code search tools will find exactly the file you're looking for faster, rather than listing all files in the directory.

It doesn't particularly matter which way you choose to name your components, as long as you pick one, and use it consistently.

3. Separate your pages from your components

React frameworks like Next.js make this easier by using page-based routing, but you can use it in any React project.

For example:

src/
|-- components/
|   |-- Avatar/
|   |   |-- Avatar.ts
|   |   |-- Avatar.test.ts
|   |-- Button/
|   |   |-- Button.ts
|   |   |-- Button.test.ts
|   |-- TextField/
|   |   |-- TextField.ts
|   |   |-- TextField.test.ts
|-- pages/
|   |-- UserProfile/
|   |   |-- Components/
|   |   |   |-- SomeUserProfileComponent/
|   |   |   |   |-- SomeUserProfileComponent.ts
|   |   |   |   |-- SomeUserProfileComponent.test.ts
|   |   |-- UserProfile.ts
|   |   |-- UserProfile.test.ts
|   |-- index.ts

In your pages/index.ts file you can then keep your React-Router routes.

4. Keep styled components in your component files

I tend to keep my styled-components in the same file as my components. This is mainly to avoid context switching when trying to figure out what a component does.

You can also choose not to do this, up to you.

In practice, this looks something like this:

//DataChip.js
import React from 'react';
import styled from '@emotion/styled';

const Title = styled.p`
  font-size: 16px;
  line-height: 16px;
  font-weight: 700;
  margin-bottom: 4px;
`;

const Value = styled.p`
  font-weight: 700;
  font-size: 32px;
  line-height: 32px;
  margin-bottom: 0;
  color: ${(props) => {
    if (props.sentiment === 'GOOD') return '#30B17E';
    if (props.sentiment === 'BAD') return '#E94740';
  }};
`;

const ChipHolder = styled.div`
  @media (max-width: 600px) {
    margin-bottom: 8px;
  }
`;

export const DataChip = ({ label, value, sentiment }) => {
  return (
    <ChipHolder>
      <Title>{label}</Title>
      <Value sentiment={sentiment}>{value}</Value>
    </ChipHolder>
  );
};

In the past I would use CSS Modules, and keep the MyComponent.module.css file in the same folder as MyComponent.ts.

5. Split things out only when you need to

If you have a component that only gets imported by one other component, it either belongs in the same file that imports it, or at least in the same folder.

Don't move things up into components/ that aren't shared across multiple components. Also don't move things to a higher level than they get used in general (such as moving a component-specific utility function into the src/ level utils).

We're trying to organise our folders so that when you modify a folder, it has a minimal impact on other folders, and the impact of that change is predictable.

6. [Advanced] Split up your codebase by team

Eventually with a large enough project and engineering team, the CODEOWNERS file just doesn't cut it, and it becomes necessary to split up your codebase by team.

Like all good things in tech, there are trade-offs:

• On the one hand, your teams stop treading on each other's toes as often (with merge conflicts, and implementing things differently to the team's standard approach)
• On the other hand, you risk creating silos and having teams re-implement work that another team has done

For example:

src/
|-- growth/
|   |-- components/
|   |   |-- GrowthSpecificAvatar/
|   |   |   |-- GrowthSpecificAvatar.ts
|   |   |   |-- GrowthSpecificAvatar.test.ts
|   |-- pages/
|   |   |-- UserProfile/
|   |   |   |-- Components/
|   |   |   |   |-- SomeUserProfileComponent/
|   |   |   |   |   |-- SomeUserProfileComponent.ts
|   |   |   |   |   |-- SomeUserProfileComponent.test.ts
|   |   |   |-- UserProfile.ts
|   |   |   |-- UserProfile.test.ts
|-- edgyTeamName/
|   |-- components/
|   |   |-- EdgyTeamNameSpecificAvatar/
|   |   |   |-- EdgyTeamNameSpecificAvatar.ts
|   |   |   |-- EdgyTeamNameSpecificAvatar.test.ts
|   |-- pages/
|   |   |-- UserList/
|   |   |   |-- Components/
|   |   |   |   |-- SomeUserListComponent/
|   |   |   |   |   |-- SomeUserListComponent.ts
|   |   |   |   |   |-- SomeUserListComponent.test.ts
|   |   |   |-- UserList.ts
|   |   |   |-- UserList.test.ts

At this point you might wonder whether a monorepo would make sense, but that opens up a whole new set of problems to solve, outside of the scope of this article.

Are you unsure of what exactly you're trying to achieve when writing tests? Do you write tests based on other existing tests in your codebase? Perhaps you've quickly glanced at the React Testing Library documentation to try figure out "the right way" of testing.

At some point, you need to step back and think:

What does 'the right way' even mean when testing React?

What are we trying to achieve here?

If you've heard of React Testing Library, chances are you've heard the almost-slogan "test functionality, not implementation details".

Not testing implementation details requires a pretty large mindset shift if you're used to testing with Enzyme, as it provides several utilities explicitly for that purpose, such as find(), instance() and state().

For me, it helps to think from the perspective of a malicious user. Think about a sign-up form. I might try submit the form with no data to see what happens, maybe try submit the form without a password, or supply an invalid email address.

Just like that, you've got tests to write with no knowledge of implementation details:

Test 1 - no data

1. Render the form
2. Find the submit button, and click it
3. Assert that the error message appears

Test 2 - no password

1. Render the form
2. Find the email field, and enter a random valid email address
3. Find the submit button, and click it
4. Assert that the error message appears

Test 3 - invalid email address

1. Render the form
2. Find the username field, and enter an invalid email address
3. Find the submit button, and click it
4. Assert that the error message appears

Side note: Once you've got a few tests like this, you can look at refactoring them to avoid duplicating code in your tests.

React Testing Library helps quite a bit with utility functions that let you easily write tests like this, but Enzyme will let you do the same thing too. The difference is, Enzyme won't stop you from going further, and writing tests against your props and state too, while React Testing Library goes out of its way to stop you from doing this.

The important thing is to test functionality, because it'll let you avoid writing brittle tests that rely too much on knowing which functions to call, and hopefully means you'll be rewriting your tests less often as your code gets refactored.

Conclusion

I find the easiest way to avoid testing implementation details is to pretend I'm not a developer, and try to perform a specific task in my application just like a user would.

For example, typing into a sign-up form, and trying to submit the form.

The tests I write would then seek to automate the clicking and typing the user would do (via React Testing Library's getByRole queries), rather than calling find(MyComponent) and calling functions directly.

It's bloody hard to find a good example of a large production-grade, open-source React app.

There are a few reasons for this:

1. No one writes amazing code the first time they write it

   • Experienced product engineers know there's a trade-off between quality and getting features in the hands of customers. You're more likely to find ugly tech debt with a //TODO: Improve this later! comment than best practices

2. Most companies keep their apps in private repos

   • Trade secrets and all that jazz.

3. There's a lot of beginner-grade repos out there

   • Without a ton of experience, it's hard to tell the good from the bad

On that note, I've reviewed the following well-known open-source React apps, and reckon they're worth checking out.

I've split this article into two parts:

1. Example Apps
2. Apps with Users

Example Apps

Jira Clone by Ivor Reic

Project link: Jira Clone

Jira Clone is... a Jira clone built in modern React, entirely out of functional components with Hooks. It's noteworthy because its stack is more or less what I'd use on my own side-projects:

• TypeScript with TypeORM on the backend, communicating with a Postgres database
• React on the frontend with a custom webpack config
• Relies on Cypress for end-to-end testing

On top of that, the author has done an amazing job making it look very similar to Jira (when the clone was built), using a mix of styled-components and global styles.

This repo also highlights the benefits of just working on a project by yourself with a clear understanding of what you're trying to build. You'll see the contrast when you check out the other projects in this article.

RealWorld aka Conduit by Thinkster

Project links:

• Repo
• Demo

RealWorld by Thinkster re-implements the same app (a Medium.com clone called Conduit) in over 24 different languages and frameworks. In this case, we're reviewing the React/Redux version.

It uses create-react-app, with react-router for routing, Redux for state management, classNames for styling, superagent for data fetching, with no testing, or type-checking.

It seems like a decent way to understand the syntactical differences between dozens of language and framework combinations, but isn't exactly a beacon of best practices.

Real World App by Cypress

Project link: Real World App

Real World App is a great example of best-practices to use for end-to-end testing an application with Cypress, with example data in the repo, so both tests and the app run out-of-the-box without the need for a database.

It's built with create-react-app, written in TypeScript with an Express backend, using Material UI as a UI/component library, Formik for forms, and react-router for routing.

It looks like a pretty solid example of an application you would see in the real world, (especially since it uses forms), though data-fetching and form submission are optimised for ease of testing/portability rather than best practices.

Apps with Users

HospitalRun by HospitalRun

Project links:

• Repo
• components src

HospitalRun is an offline-first electronic health record (EHR) and hospital information system (HIS) web application. It's an incredibly complete solution for OSS without a massive company building it (though it is sponsored by some companies).

It's written in modern React (as far as I can tell, not a single class component), with TypeScript, and uses SCSS for styles. Most components live in the components package (also worth checking out).

Simorgh by the BBC

Project links:

• Repo
• @bbc/psammead src

Simorgh is the BBC's React SPA, currently serving millions of users in production around the world. It is being progressively rolled out to each BBC World Service News website, and you can track the progress here.

It uses PropTypes for type-checking, Jest and Enzyme for unit testing, Cypress for end-to-end testing, styled-components for styling (with most components living in @bbc/psammead, which is an awesome component library to check out too), react-router for routing, with Express handling server-side rendering.

It's extremely well-tested (98% coverage) and well-documented, with READMEs throughout the project to explain large directories.

AST Explorer by Felix Kling and open-source community

Project link: AST explorer

AST Explorer is a tool for exploring Abstract Syntax Trees.

It's worth checking out as a React project because it's a good example of a project under continuous development for several years. It's a classic React project that uses PropTypes for type-checking, and Redux for state management while still using local state where possible.

While you won't find anything fancy like TypeScript/Flow here, the code is well commented, with hacks and workarounds clearly pointed out.

Some might say there's some "tech debt", as the authors have chosen to stick with class components, and not immediately rewrite to functional components + Hooks. Instead, they've maintained class components in older files, with functional components + Hooks in newer files.

Also worth noting, that like many real life, open-source projects, AST Explorer was started with the intention of adding tests later, but only one contributor in four years mentioned wanting to add tests in the GitHub Issues.

Excalidraw by Vjeux and open-source community

Project link: Excalidraw

Excalidraw is a tool for drawing flow-charts, and various other diagrams with a hand-drawn style. I actually use it quite a bit for my own projects.

It's worth checking out because it's one of the most popular (in terms of daily users) examples of an un-ejected create-react-app application I've seen in production.

It's written in relatively modern React (mostly functional components with Hooks) with TypeScript, uses SCSS for styles, there are tests, and rather than using Redux, they've lifted state up and persisted it in localStorage.

Spectrum by Spectrum

Project link: Spectrum

Spectrum is a community site, seeking to combine the features of a real-time chat app with the features of forums. It's been under active development since early 2017, and was acquired by GitHub at the end of 2018.

Spectrum was very interesting to follow during its early years, as it used RethinkDB for (almost) live updates on queries, server-side rendering and GraphQL (very cutting edge at the time).

The codebase uses Flow for type-checking, Apollo (GraphQL) for data-fetching, Redux for state management, an Express server for server-side rendering, and uses functional components + Hooks, with custom hooks here. Naturally, as one of the founders is Max Stoiber (creator of styled-components), the app is styled with styled-components.

Since the acquistion, Max has written a post called Tech Choices I Regret at Spectrum that's also worth checking out.

Sentry by Sentry

Project links:

• Repo
• App src

Sentry is a service that allows you to report on errors in your web app.

It runs on a Django backend, with a React frontend written in TypeScript (with PropTypes too), uses Emotion for styling, react-router for routing, Redux for state management, and is a great example of trade-offs and //TODO comments in a SaaS app with users that pay for it.

One peculiar thing to check out is that the app is internationalized, using a translation service to convert strings here.

Grafana by Grafana

Project links:

• Repo
• App src
• @grafana/ui src

I almost didn't add Grafana as an example here, since it's an AngularJS project in the process of migrating to React.

It's an AngularJS app being progressively rewritten into a modern React app, written in TypeScript. It uses Redux for state management, an internal design system that uses emotion for styling (@grafana/ui).

It's kind of a nightmare to navigate as a codebase, mainly due to mixing folders only used by AngularJS with folders only used by React, and that's exactly why it's in this article, as an example of what you'll see in the real world.

GoAlert by Target

Project links:

• Repo

• App src

GoAlert is an open source on-call scheduler and notifier (simlar to PagerDuty or Opsgenie).

It runs on a Go backend, using Apollo (GraphQL) for data-fetching, react-router for routing, Redux for state management, Cypress for end-to-end testing, Material UI for some components, and plain old CSS for styling.

Surprisingly, it's a pretty good example of Cypress testing in a real application, using data-cy for selecting elements (for example).

If you're coming over from React's class components, you might be confused about how useState works, particularly since you can now define what the initial value is.

Let's take a closer look.

You'd typically use it like this:

import React, { useState } from 'react';

const SomeComponent = () => {
  const [someState, setSomeState] = useState('starting value');

  return <div onClick={() => setSomeState('new value')}>{someState}</div>;
};

If you want to play with this example, check out the CodeSandbox.

In class-based components, you might be used to defining a whole bunch of initial state values inside the component's state object. That's no longer the case with useState. Instead, we tend to declare a single state value at a time, like so:

import React, { useState } from 'react';

const SomeComponent = () => {
  const [someState, setSomeState] = useState('starting value');
  const [someOtherState, setSomeOtherState] = useState(null);
  const [importantState, setImportantState] = useState(42);

  return <div onClick={() => setSomeState('new value')}>{someState}</div>;
};

The key difference is that the initial value of the state defined by useState can be anything you want it to be. It no longer has to be an object. A string, a number, an object, undefined, null - anything goes!

The other difference, is that calling useState returns you an array with two things in it: the value, and a function to set a new value. The typical approach to the array useState returns is to destructure it in the same line it's declared, as we saw above:

const [someState, setSomeState] = useState('starting value');

If you're new to React, you might be wondering why there are so many different tutorials that teach different ways to style your React app. The truth is, we're all still figuring out the best way to do things.

Styles in React were more-or-less worked out in this order:

1. Global CSS
2. CSS Modules
3. CSS in JS (styled-components, Emotion, etc)
   • Utility-first CSS
   • Styled System
4. Statically extracted CSS in JS

These days, I recommend starting with CSS in JS. If you'd like to know why, read on.

Quick note

When I say styling, I mean writing your CSS styles more-or-less from scratch. If you're looking for pre-built components, I wrote a guide to commonly used React component libraries.

Global CSS

Global CSS is likely the way you're used to styling webpages. You have a giant styles.css file, and try to write BEM or SMACSS names for all of your classes. Alternatively, you have a ton of tiny files, and don't always know where each class lives.

We as frontend developers quickly realised that global CSS doesn't really scale. The more teams you have editing a single file, the more likely you are to have CSS that doesn't do anything (people become too afraid to delete anything in case it breaks).

If you still want to use Global CSS in your React app, all you need to do is import the CSS file at the top level of your React app (assuming you've configured webpack to do so, or are using create-react-app).

//App.js
import './styles.css';
import React from 'react';

const App = () => {
  return <div className="some-class">some other stuff in here</div>;
};

CSS Modules

CSS Modules look a lot like Global CSS, in the sense that you're importing a CSS file into your React component, but under the hood it's quite different.

A lot of the problems we used to have with Global CSS are gone with CSS Modules.

Your CSS looks like this:

/* style.css */
.makeItGreen {
  color: green;
}

and your React Component looks like this:

import React from 'react';
import styles from './style.css';

const MyComponent = () => {
  return <div className={styles.makeItGreen}>Green!</div>;
};

The key difference here is that only files that import style.css will be able to access the class names that it defines, and the class names that get generated during the build process will be unique.

No more conflicts, no more "too afraid to delete things in case it breaks", just locally scoped CSS. You can also set-up SCSS/LESS support, if you need it.

The really cool thing about this is that you can start to play around with JavaScript to change a component's styles.

import React from 'react';
import styles from './style.css';

const MyComponent = (props) => {
  const myStyle = props.color === 'RED' ? styles.makeItRed : styles.makeItGreen;
  return <div className={myStyle}>{props.color}!</div>;
};

Although, that starts to get a bit messy if you're using several props to change the style and behaviour of your components. What if your styles could just be components?

CSS in JS

That's where CSS in JS comes in.

Libraries like styled-components and Emotion make it possible to wrap components (including divs, spans, <p> tags, <a> tags) with styles, and use them as React components.

The best part is, you can use all of the standard CSS features you're used to, such as media queries, and :hover and :focus selectors.

Our example from above now becomes:

import React from 'react';
import styled from '@emotion/styled';
// OR import styled from 'styled-components'

const StyledGreenThing = styled.div`
  color: ${(props) => (props.color === 'RED' ? 'red' : 'green')};
`;

const MyComponent = (props) => {
  return (
    <StyledGreenThing color={props.color}>{props.color}!</StyledGreenThing>
  );
};

As of 2020, Emotion and styled-components are evenly matched performance-wise. Contributors to styled-components worked hard to bring their performance up to Emotion's level, so deciding which one to use isn't as much of a big deal any more (even if people argue endlessly about them as though they're sports teams).

Emotion does provide some extra options for styling, such as the css prop, while styled-components tries to keep a single, standard way of doing things via the styled API.

Utility-first CSS

A guide to styling React apps wouldn't be complete without mentioning utility-first CSS frameworks such as Tailwind. You don't actually need React to use utility-first CSS, but in my opinion, it makes for a better developer experience when you add React and CSS in JS.

In short, Tailwind lets you style your components one class at a time. Here's what it looks like:

<div className="md:flex bg-white rounded-lg p-6">
  <img
    className="h-16 w-16 md:h-24 md:w-24 rounded-full mx-auto md:mx-0 md:mr-6"
    src="avatar.jpg"
  />
  <div className="text-center md:text-left">
    <h2 className="text-lg">Erin Lindford</h2>
    <div className="text-purple-500">Product Engineer</div>
    <div className="text-gray-600">erinlindford@example.com</div>
    <div className="text-gray-600">(555) 765-4321</div>
  </div>
</div>

Which creates a component that looks like this:

You might be thinking that it's not a particularly re-usable solution, however it's possible to use Tailwind class names with your favourite CSS in JS library using twin.

You can then have styled Tailwind components:

import tw, { styled } from 'twin.macro';

const Input = styled.input`
  color: purple;
  ${tw`border rounded`}
`;

export const MyStyledInput = () => {
  return <Input />;
};

Styled System

Styled System takes the styled API supplied by styled-components or Emotion, and adds utilities as props, rather than class names.

The Styled System approach is particularly powerful when it comes to theming/white labelling, as changing the entire appearance of your app can be done by replacing the theme.js file you provide.

Your components end up looking like this:

import styled from '@emotion/styled';
import { typography, space, color } from 'styled-system';

const Box = styled('div')(typography, space, color);

const UsedBox = () => {
  return (
    <Box
      fontSize={4}
      fontWeight="bold"
      p={3}
      mb={[4, 5]}
      color="white"
      bg="primary"
    >
      Hello
    </Box>
  );
};

Statically extracted CSS in JS

The trouble with CSS in JS is that it takes JavaScript to load your CSS. This slows things down big time, so people started looking for ways to extract the CSS from CSS-in-JS during build time.

There are a few libraries that can do this:

• Compiled
• linaria
• treat

Compiled and linaria let you use the styled API that you know and love, while giving you the performance benefit of not having CSS in your bundle.

Ant Design

Project link: Ant Design

Bundle Size (from BundlePhobia): 1.2 mB minified, 349.2kB minified + gzipped, less with treeshaking

Pros:

• Ant Design comes with a huge amount of supporting documentation, community, including a separate project (Ant Design Pro) with pre-made templates
• The kind of UI library you'd use to quickly throw up as a back-office/internal app design

Cons:

• Accessibility is lacking
• It's huge. Expect a sizable performance impact when using
• Pollutes your CSS (expect to add !important to prevent it styling your non-Ant components)

Bootstrap

I actually rate Bootstrap relatively highly as a UI library. It's not going to win you any design awards, but it gets the job done for side projects and minimum viable products.

It depends what you want to use it for, though. If you're new to React, it's a great library to use to get started. As a more experienced developer, chances are you'll want to look into styled-components/Emotion.

There are two popular libraries with React bindings for Bootstrap, I've personally only used Reactstrap.

Project links:

• React Bootstrap

  • Bundle Size (from BundlePhobia): 111kB minified, 34.4kB minified + gzipped, less with treeshaking

• Reactstrap

  • Bundle Size (from BundlePhobia): 152.1kB minified, 39.4kB minified + gzipped, less with treeshaking

Pros:

• The Bootstrap library that you know and love, with React bindings
• Easily customised via CSS-in-JS
• It's been around long enough with widespread usage that bugs/issues aren't a worry
• Quick to get started
• No jQuery dependency as it's been reimplemented entirely in React

Cons:

• It's Bootstrap: your site will look like everyone elses if you don't customise it

Bulma

Bulma is different to most libraries presented here because it's purely a CSS framework, no JS required. You can choose to either use the classes from Bulma directly, or use a wrapper library such as react-bulma-components.

Project links:

• Bulma
• react-bulma-components
  • Bundle Size (from BundlePhobia): 179kB minified, 20.1kB minified + gzipped

Pros:

• Doesn't have the Bootstrap look and feel
• Good for getting something up and running quickly
• Modern features (Flexbox/Grid under the hood)

Cons:

• Accessibility: there's some, but doesn't follow WCAG guidelines as strongly as other libraries

Chakra UI

Project link: Chakra UI

• Bundle Size (from BundlePhobia): 326.2kB minified, 101.2kB minified + gzipped, less with treeshaking

Pros:

• Accessibility: follows WAI-ARIA guidelines and components use aria tags
• Discord server for support
• Easily customisable (with theming support)
• Highly modular, so treeshaking actually removes code you don't use

Cons:

• Quite new.

Material UI

Material UI is one of those libraries that I love to hate. It has helped me get through some extremely tight deadlines for clients in the past, but I always end up removing it in favour of almost anything else as soon as possible.

In the past you could only customise Material UI's styles by writing JSS, but thankfully it's now possible to override styles with styled-components and Emotion.

Project link: Material UI

• Bundle Size (from BundlePhobia): 325.7kB minified, 92kB minified + gzipped, less with treeshaking

Pros:

• Comprehensive documentation
• Icon library is massive
• Simple to use (at first)

Cons:

• Customisation is difficult, and painful, yet necessary (to improve visuals)
• Performance: known to render excessive DOM nodes
• Your app will look like Google made it (which could be a pro, for some people)

Semantic UI

Project links:

• Semantic UI

• Semantic-UI-React

  • Bundle Size (from BundlePhobia): 300.8kB minified, 80.9kB minified + gzipped, less with treeshaking

Pros

• Composable (using the as prop to pass components)
• Easily customisable
• Helpful docs
• High profile users (Netflix internally, Amazon publishing)
• TypeScript support

Cons

• Potential uncertainty about the open source project.
  • See issues: https://github.com/Semantic-Org/Semantic-UI/issues/6109 https://github.com/Semantic-Org/Semantic-UI/issues/6413
  • Community-run fork exists: https://github.com/fomantic/Fomantic-UI

Honourable mentions

Reach UI

Reach UI is a low-level component library, focusing on allowing developers to build accessible React components in their design system.

There's no bundle size available as each component is exported individually as its own npm package.

Reakit

Reakit is another low-level component library. It's technically a UI library, but doesn't come with CSS. So you still need to come up with a styling solution.

• Bundle Size (from BundlePhobia): 119.9kB minified, 32.1kB minified + gzipped, less with treeshaking

Rebass

Rebass has been on my radar for some time. It's an extremely powerful component library that doesn't come with a theme, but can be themed easily. For an example of how this works in practice, see their demo.

Project link: Rebass

• Bundle Size (from BundlePhobia): 43kB minified, 14.4kB minified + gzipped, less with treeshaking

Notes

In making this list, I've attempted to avoid corporate design systems, however some (Material UI) have achieved such widespread adoption that this list would be incomplete without them.

I've also intentionally left out CSS-in-JS such as styled-components and Emotion, and utility CSS systems such as Tailwind, as they are not explicitly "React Component libraries", but rather tools with which to make your components.

Trying to render an SVG in your React app, and getting errors? You're not alone - it's a relatively common issue.

There are two ways to do it, and both have tradeoffs.

Using <img> tags, and passing your SVG's URL

Here's a basic example:

import React from 'react';
import logoSrc from './logo.svg';

const MyLogo = () => {
  return <img src={logoSrc} />;
};

The benefit of this approach is that your logo will not end up in your bundle, but rather exported as a static file when you run yarn build (assuming you're using a standard webpack config, such as the one found in create-react-app).

This then gives you the option of aggressively caching icons that you know won't change.

You would typically use this approach for larger company logos on your marketing site, or for illustrations in your app.

Creating a React component, and passing props

The other option is to create a React component containing your SVG. Also known as "inlining" your SVG.

This done by pasting your raw svg markup into a new React component.

There are a few ways to achieve this:

• Manually, byremoving/replacing all HTML props with the React equivalent, and adding {...props} to the main svg element),
• CLI via SVGR - a utility to automate this process
• Webpack config via SVGR

If you're using create-react-app, it already has SVGR's webpack config built-in, so you can already use your SVGs like React components:

import Star from './star.svg';
const App = () => (
  <div>
    <Star />
  </div>
);

Here's what a manually created SVG-based React component looks like:

import React from 'react';

export const DeleteIcon = (props) => (
  <svg
    xmlns="http://www.w3.org/2000/svg"
    height="24px"
    viewBox="0 0 24 24"
    {...props}
  >
    <path d="M6 19c0 1.1.9 2 2 2h8c1.1 0 2-.9 2-2V7H6v12zM19 4h-3.5l-1-1h-5l-1 1H5v2h14V4z" />
    <path d="M0 0h24v24H0z" fill="none" />
  </svg>
);

This approach lets you easily access props on your SVG icon. For example, changing the fill color:

<DeleteIcon fill="#fff" />

The downside being that your icons won't be as easily cached, so I would use this approach for smaller icons, such as the Material Design Icons.

If you're new to React, and you've been working through tutorials, chances are you've run into examples of both functional components with Hooks, and class components, with no strong indication of which one you should be using. Even as a seasoned developer, you might still be using class components, wondering if its worth the rewrite.

You're probably thinking:

I've been digging for answers, but I just can't find a clear answer for this!

That's fair enough, even the official documentation didn't have a strong recommendation until the middle of 2020.

Which one should you use?

The official React team stance (according to the docs), is:

When you’re ready, we’d encourage you to start trying Hooks in new components you write. [...] We don’t recommend rewriting your existing classes to Hooks unless you planned to rewrite them anyway (e.g. to fix bugs).

To summarise:

• New code should use functional components with Hooks, when you're ready
• Old code can keep using class components, unless you want to rewrite

Should I just focus on hooks then?

It's not that simple.

You still need class components to build Error Boundaries. Sure, you could head to npm and find a Hook-based Error Boundary library to use, but ignorance doesn't justify adding yet another dependency to your project.

On top of that, most code written before 2019 will likely still use class components, as there is no immediate need to rewrite them to functional components with Hooks. If you want to understand existing code in a codebase, you'll need to also learn class components. Side note: The company I currently work at has class components with >1k lines of code used by tens of thousands of users per day. You better believe we're not rewriting them unless we have to.

You'll also find that companies that ask React questions during their interviews will still ask you about classes.

Should we rewrite our old class-based code to use Hooks?

As with all good things, there are tradeoffs to consider here.

Hooks result in much cleaner, easier to understand components compared to class components of a similar complexity.

To illustrate my point, compare this component that fetches some data from The Star Wars API, written first as a class, then as a functional component with hooks:

import React from 'react';

export default class DataDisplayer extends React.Component {
  constructor(props) {
    super(props);

    this.state = {
      data: null,
    };
  }

  async componentDidMount() {
    const response = await fetch(
      `https://swapi.dev/api/people/${this.props.id}/`
    );
    const newData = await response.json();
    this.setState({ data: newData });
  }

  render() {
    const { data } = this.state;
    if (data) {
      return <div>{data.name}</div>;
    } else {
      return null;
    }
  }
}

As your app grows, the lifecycle methods grow larger, and the context switching involved just from scrolling through the file increases.

I don't know about you, but my thought process when scrolling through classes is like:

Okay so I'm in componentDidMount, so we'll be fetching data here

Okay so here we're rendering, so this code runs every single time

I need to add some extra functionality... hmm which lifecycle method does that go in again?

On the other hand, you have Hooks:

import React, { useEffect, useState } from 'react';

export default function DataDisplayer(props) {
  const [data, setData] = useState('');

  useEffect(() => {
    const getData = async () => {
      const response = await fetch(`https://swapi.dev/api/people/${props.id}/`);
      const newData = await response.json();
      setData(newData);
    };
    getData();
  }, [props.id]);

  if (data) {
    return <div>{data.name}</div>;
  } else {
    return null;
  }
}

With Hooks, writing code that follows sequentially is much easier, and I find reading functional components with Hooks requires less context switching, as you're not jumping around the file to find which lifecycle method you think something happened in.

That's the main benefit of rewriting to Hooks - your codebase's developer experience improves as it takes less time to understand what each component does.

The main drawback is time - time spent rewriting is time you could have spent building new features or writing integration tests.

Where to from here?

When introducing Hooks to my team in the past I recommended the following approach (we used it to rewrite our entire codebase from Flow to TypeScript), and it worked quite well:

• All new code should be written as functional components with Hooks
• Existing code should only be rewritten if it gets modified frequently (for example, if you're fixing a bug or adding functionality, take the time to swap the component over to Hooks)

Do you have clients, or stakeholders asking about improving their site performance, or wondering why their site seems to have gotten slower over time?

It happens to everyone: you deliver a fast website from the start, but then over time you get feature request after feature request, deadlines get rushed in, and the next thing you know you've got a client asking why some pages are taking up to ten seconds to load.

It doesn't have to be this way.

It's actually a simple fix: regularly check your site speed.

There are several manual tools you can use for free:

• WebPageTest
• Google PageSpeed Insights or Google Lighthouse

Pro tip: Export the numbers, and use Excel or Google Sheets to graph your performance over time.

Once you start checking your site speed daily, it becomes easier to notice your performance slipping over time.

Let's take a step back, pause for a moment, and think about what useEffect and useState actually do.

Changing state will always cause a re-render. By default, useEffect always runs after render has run. This means if you don't include a dependency array when using useEffect to fetch data, and use useState to display it, you will always trigger another render after useEffect runs.

Unless you provide useEffect a dependency array.

The dependency array

The dependency array in useEffect lets you specify the conditions to trigger it. If you provide useEffect an empty dependency array, it'll run exactly once, as in this example (CodeSandbox link):

import React, { useEffect, useState } from 'react';

export default function DataDisplayer() {
  const [data, setData] = useState('');

  useEffect(() => {
    const getData = async () => {
      const response = await fetch(`https://swapi.dev/api/people/1/`);
      const newData = await response.json();
      setData(newData);
    };

    getData();
    // highlight-next-line
  }, []); //<-- This is the dependency array

  if (data) {
    return <div>{data.name}</div>;
  } else {
    return null;
  }
}

What if you wanted to let users decide which id they wanted to query, and forgot to add the dependency array? You'd cause an infinite loop.

import React, { useEffect, useState } from 'react';

export default function DataDisplayer(props) {
  const [data, setData] = useState('');

  useEffect(() => {
    const getData = async () => {
      const response = await fetch(`https://swapi.dev/api/people/${props.id}/`);
      const newData = await response.json();
      setData(newData);
    };

    getData();
    // highlight-next-line
  }); //<-- Notice the missing dependency array

  if (data) {
    return <div>{data.name}</div>;
  } else {
    return null;
  }
}

Why does the above example cause an infinite loop?

1. Your first render runs, and because data is falsey, render returns null and kicks off useEffect
2. useEffect runs, fetching your data, and updating it via setData
3. Since data has been updated, the component re-renders to display the new data value
4. However, useEffect runs after each render, so it runs again, updating data via setData
5. Repeat steps 3 and 4 until your app crashes, or the API rate-limits your requests

Preventing infinite loops

This is where the dependency array comes in handy.

Adding variables to the dependency array tells useEffect: "Hey, I need you to run only if this value changes".

In this case, adding props.id will ensure useEffect only runs if props.id changes:

import React, { useEffect, useState } from 'react';

export default function DataDisplayer(props) {
  const [data, setData] = useState('');

  useEffect(() => {
    const getData = async () => {
      const response = await fetch(`https://swapi.dev/api/people/${props.id}/`);
      const newData = await response.json();
      setData(newData);
    };
    getData();
    // highlight-next-line
  }, [props.id]); //<-- This is the dependency array, with a variable

  if (data) {
    return <div>{data.name}</div>;
  } else {
    return null;
  }
}

According to the docs, running Google Lighthouse five times against the same URL will reduce the variability of your results by around half if you pick the median result.

The problem is, how do you pick the right result to use as your median, or representative result?

A naïve approach would be to take the median of the performance score, however since the performance score itself is a weighted average of other scores, and is more prone to outliers, it isn't as useful as you'd think.

Lighthouse actually exports a function to help you calculate which result to use: computeMedianRun.

How to use computeMedianRun in Node

const spawnSync = require('child_process').spawnSync;
const lighthouseCli = require.resolve('lighthouse/lighthouse-cli');
const {
  computeMedianRun,
} = require('lighthouse/lighthouse-core/lib/median-run.js');

const results = [];
for (let i = 0; i < 5; i++) {
  console.log(`Running Lighthouse attempt #${i + 1}...`);
  const { status = -1, stdout } = spawnSync('node', [
    lighthouseCli,
    'https://example.com',
    '--output=json',
  ]);
  if (status !== 0) {
    console.log('Lighthouse failed, skipping run...');
    continue;
  }
  results.push(JSON.parse(stdout));
}

const median = computeMedianRun(results);
console.log(
  'Median performance score was',
  median.categories.performance.score * 100
);

Under the hood, computeMedianRun finds the run that's closest to the median First Contentful Paint (FCP), AND the closest to the median Time to Interactive (TTI).

FCP and TTI are used because they're the earliest and latest moments in a page's lifecycle.

Is this you?

I've tried so many different things I've found online

Holy crap it works now, such a small problem I've lost hours to :(

All I want to do is a simple thing, this is all so unnecessarily complex

Try using react-hook-form.

React-hook-form is different, because it (mostly) keeps its state in the DOM (like classic HTML form elements).

Here's an example of a single field form in react-hook form (taken from their docs):

import React from 'react';
import { useForm } from 'react-hook-form';

const Example = () => {
  const { handleSubmit, register, errors } = useForm();
  const onSubmit = (values) => console.log(values);

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input
        name="email"
        ref={register({
          required: 'Required',
          pattern: {
            value: /^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/i,
            message: 'invalid email address',
          },
        })}
      />
      {errors.email && errors.email.message}

      <input
        name="username"
        ref={register({
          validate: (value) => value !== 'admin' || 'Nice try!',
        })}
      />
      {errors.username && errors.username.message}

      <button type="submit">Submit</button>
    </form>
  );
};

Compare that to your existing form code. I don't know about you, but my React forms with Formik would have twice as many lines of code to achieve the same thing.

You'll notice that it's using ref, rather than tracking state within the library. Since moving to react-hook-form, I no longer have to worry about state not syncing correctly in huge forms.

Everything just works as expected, and my code is much simpler too.

Do we even need a client?

First things first — depending on how large your application is, and what you’re trying to achieve with GraphQL, you may not even need a GraphQL client.

If you're just testing the waters with GraphQL and don't want to change your existing app too much, you can just use fetch in your component like so:

fetch('/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Accept: 'application/json',
  },
  body: JSON.stringify({ query: '{ hello }' }),
})
  .then((r) => r.json())
  .then((data) => console.log('data returned:', data));

The main benefit to adopting a GraphQL client is the cache implementation. Using fetch is fine to begin with, but you don't want to be using it in an app where users quickly jump between views.

In PerfBeacon we use Apollo to cache query results - which gives us quite a noticable boost in performance. How it works in practice:

You view a list of websites: this list of websites is now cached in memory, for example:

[
  {
    "id": "123",
    "url": "https://perfbeacon.com"
  },
  {
    "id": "124",
    "url": "https://maxrozen.com"
  }
]

You then choose to review reports for your first website. As the GraphQL client already knows the id and url, it doesn't need to refetch this data. It only needs to fetch the array of reports, as shown below:

[
  {
    id: '123',
    url: 'https://perfbeacon.com'
    reports: [
      {
        id: '1',
        date: '2020-01-01',
      }
    ]
  }
]

As you now have the list of websites, and a list of reports for the first website, clicking back in your browser to view the list of websites is instant, as no GraphQL request is made.

Essentially, the more the user clicks around your application, the faster your user experience becomes.

Apollo Client

The setup is considerably easier than Relay - it involves installing one package, and adding the ApolloProvider to the root of your React tree.

The API is nice - they have an equivalent to Relay's QueryRenderer called Query that does what it says:

<Query
  query={gql`
    {
      rates(currency: "USD") {
        currency
        rate
      }
    }
  `}
>
  {({ loading, error, data }) => {
    if (loading) return <p>Loading...</p>;
    if (error) return <p>Error :(</p>;

    return data.rates.map(({ currency, rate }) => (
      <div key={currency}>
        <p>{`${currency}: ${rate}`}</p>
      </div>
    ));
  }}
</Query>

It can be used to manage state in your React app - that is, you can directly write to Apollo's Redux-like store and consume that data in another part of the React tree. Though with React's new Context API, and React's best practices of Lifting State Up you probably won't need it.

import React from 'react';
import { ApolloConsumer } from 'react-apollo';

import Link from './Link';

const FilterLink = ({ filter, children }) => (
  <ApolloConsumer>
    {(client) => (
      <Link
        onClick={() => client.writeData({ data: { visibilityFilter: filter } })}
      >
        {children}
      </Link>
    )}
  </ApolloConsumer>
);

Downsides to Apollo

• It's huge. It weighs in at 10x more than the smallest GraphQL client I'd consider using, and 3x more than urql

Quirks

Apollo is not without quirks however:

• Since Apollo uses id to build its cache, forgetting to include id in your query can cause some interesting bugs and error messages

On Bundle size

One of the biggest complaints I hear about adopting Apollo is the bundle size (Apollo Boost, the "easiest way to get started with Apollo Client" weighs in at 30.7 kB min+gzipped), so luckily there are also alternative lightweight clients to consider:

• Formidable Labs' urql - 12kB min+gzipped (with perhaps the best README I've ever seen)
• Prisma's graphql-request - 4 kB min+gzipped
• Adam Rackis' micro-graphql-react - 3.1kB min+gzipped

Relay

Setup

The main benefit to using Relay is that relay-compiler doesn't get included in your frontend bundle, saving your user from downloading the whole GraphQL parser - it "pre-compiles" the GraphQL queries at build time.

What annoys me about Relay is that it requires a fair bit of work to even add to a project. Just to get it running on the client side, you need to:

• add a relay plugin to your .babelrc config
• set up relay-compiler as a yarn script
• setup a "relay environment" (essentially your own fetch utility to pass data to the relay-runtime), and
• add QueryRenderer components to the React Components you wish to pass your data to

On the server side, you need to:

• Ensure the IDs your app returns are unique across all of your types (meaning you can't return nice ID values like 1, 2, 3, they need to be like typename_1, typename_2)

Developer Experience

The developer experience itself is pretty unpleasant too - relay-compiler needs to run each time you modify any GraphQL query, or modify the schema. In large frontend teams this means teaching everyone to run relay-compiler every time you change branches in Git, since almost all of our work involves fetching data from GraphQL in some way.

Update: Thanks to relay-compiler-webpack-plugin you no longer need to remember to re-run the relay-compiler every time you make a change, webpack will do it for you.

Quirks

Being one of Facebook's Open Source projects doesn't necessarily mean issues get fixed quickly. Occasionally, things break in unexpected ways:

• Using an old version of graphql breaks relay: https://github.com/facebook/relay/issues/2428
• Errors don't get sent via the error object in GraphQL when using QueryRenderer, instead one needs to create an error type, and send the errors through the data object: https://github.com/facebook/relay/issues/1913

In Summary

If I were starting a new project today in the middle of 2020, I’d use Apollo Client by default.

If my users were using cellular data, bandwidth constrained, or using lower-spec devices, I would opt to use urql instead.

I wouldn’t bother rewriting an application from Relay to Apollo. There are benefits, mainly from developer experience/ergonomics of the API, but not enough to outweigh the cost of rewriting. You may also consider writing new features using Apollo, and heavily using code-splitting to avoid sending two GraphQL implementations to your users — I’ve used a similar approach to slowly roll-out TypeScript for companies I’ve worked at.

Here is a non-exhaustive list of books you should read as a developer. Not specifically because they'll make you a better developer, but a better person, too.

While this blog post has a date attached, please consider this advice timeless.

Badass: Making Users Awesome by Kathy Sierra

Badass teaches you to stop thinking purely in terms of solutions, and start thinking of what your users want to achieve by using your software.

Hence the name Badass. It's about helping your users become badass at your product, but also at what your users want your product to help them do.

It's a short read (with lots of visuals!), highly recommended.

How to Win Friends and Influence People by Dale Carnegie

A lot of people refuse to read this book due to the title. Whether you think it's manipulative, or a book to give as an offensive joke, just read it.

Dale Carnegie emphasises an honest interest in other people's lives that is rare in the modern era.

If you have any other recommendations that I've missed, I'd love to know!

Nonviolent Communication by Marshall Rosenberg PhD

Nonviolent Communication is another book with an unfortunate name that often stops people from reading it (I personally procrastinated from reading it for several months because of the name).

Also highly recommended, as it teaches you to both actively listen when others are describing their problems, but also more effective ways to communicate your pain.

As an example, the book insists the reader use phrases such as "I feel anxious when I deploy, because..." rather than "Deploying sucks, it's terrible!".

Hey, you! Does your project have jest already installed?

Do you wish management would care more about accessibility but just can't get them to invest or pay attention?

A few design systems I've worked with had the following code to prevent app-wide accessibility regressions, and it's so simple yet powerful that I had to share.

import React from 'react';
import { render } from '@testing-library/react`;
import { axe, toHaveNoViolations } from 'jest-axe';

expect.extend(toHaveNoViolations);

function AccessibleForm() {
  return (
    <form>
      <label htmlFor="email">Email</label>
      <input id="email" placeholder="email" />
    </form>
  );
}

test('accessible forms pass axe', async () => {
  const { container } = render(<AccessibleForm />);
  expect(await axe(container)).toHaveNoViolations();
});

Credit to Kent C. Dodds' TestingJavaScript.com course for the above snippet

With a few lines of code, auditing your entire design system for accessibility issues suddenly becomes surprisingly doable.

Without @testing-library/react, the code is more or less the same. Using Enzyme, you mount() your component, and pass it to jest-axe to validate.

It's worth noting that while this can find issues with inaccessible HTML, it doesn't guarantee your components are actually accessible. To do that, you'll want to involve actual people with disabilities involved in your research. For more information about jest-axe, see the GitHub repo.

Further reading

Google's actually has a pretty comprehensive article on auditing accessibility at https://web.dev/accessibility-auditing-react/ - however it mainly touches on catching issues via eslint or while running the application in development, rather than using your test suite.

Hey there, I'm Max. I'm the creator, engineer, designer and customer support at PerfBeacon. During the day, I work as a Frontend Software Engineer at Atlassian, and have worked at Ernst & Young (EY), and various startups around Sydney.

I built PerfBeacon as an automated wrapper around Google Lighthouse to automate a repetitive part of my job as a frontend developer. With the API set up to run at the end of CI/CD, it makes it fast to iterate on performance tweaks.

PerfBeacon lets you:

• Continuously monitor the performance of unlimited sites
• Schedule your performance checks to run throughout the day
• Use an API to run a performance check at any time
• Export the underlying Google Lighthouse report to share with your team
• Invite your entire team at no extra cost
• ... and more coming soon!

You can get started for free at PerfBeacon.com

For a short period I worked for a company whose business revolved around writing articles on WordPress. It would rank extremely well on Google for these articles, and then sell ad space on those articles to the companies it displaced.

This worked mainly because the company hired writers of authority - people who knew the topic well, and had written about the topic extensively before working there.

Anyway, here's what I learned.

Fundamental tips

• Shorter sentences
  • In general, you should aim to write sentences with 8-13 words each.
• Shorter words
  • You may think of this as "dumbing-down" your writing, but think of your readers.
• One idea per sentence
  • In other words, don't write non sequiturs.
• One concept per paragraph

Structure

• Spend lots of time on headline
  • Your headline is likely what will end up in Google. Ensure it's catchy enough to get your readers to check it out, but not so clickbaity that they avoid you.
• Spend lots of time on your first paragraph
  • Most people will judge whether your content is worth reading in the first paragraph. If it fails to land, they'll bounce.
• Start your articles with the positives, and what's important, rather than exceptions.
  • Think of it like a newspaper article: most important facts first, then gradually taper off.

Editing

• Rewriting is important
  • I personally don't agree with this for personal blogging, though some authors rewrite their content until it sounds "right".
• Change the screen you read the content on.
  • For example, if you write your article on your laptop, edit on your phone. Potentially even print the article, and edit on paper. Changing the format will force your brain to actually read what you wrote, rather than skimming.
• Change font size
  • In a similar vein to changing the screen, changing font size can help catch typos.

Human tips

• Have empathy for your audience
  • Writing things like, "I'm going to avoid explaining this because it's obvious" can and will piss off your audience. Either explain things or don't.
• Be specific
  • Don't list generic tips without examples. For example, see this entire article.
• Admit what you don't know, and link to a reputable authority
  • Hyper-specific example: if you're writing an article about useEffect() in React and you think your readers would benefit from a 49 minute read, you could link out to Dan Abramov's guide.
• Think about what your audience knows
  • Don't assume your audience knows what something is. There are two schools of thought here (especially in web development), some authors just assume audience knowledge, others preface their articles with links for required reading.
  • See my previous tip on having empathy for your audience.

In TypeScript, typing a HoC can be a little bit confusing, especially if you read some of the blog posts out there.

I came across a situation at work in which I needed to use a React Hook in a class-based component. My initial instinct was to rewrite from a class component to a function component, however upon further inspection I realised it had 1100 lines of code, with relatively complicated lifecycle methods.

I decided to wrap the component with a functional HoC that called the Hook, and passed the result down to the component as a prop.

In normal JavaScript, it isn't too complicated, you'd do something like this:

import React, { useState } from 'react';

export function withExtraInfo(WrappedComponent) {
  const [extraInfo, setExtraInfo] = useState('');

  const ComponentWithExtraInfo = (props) => {
    return <WrappedComponent {...props} extraInfo={extraInfo} />;
  };

  return ComponentWithExtraInfo;
}

If you tried to run TypeScript against the code above, you'd need to fix a few things:

1. Both WrappedComponent and props have an implicit any type
2. Make the function generic

Here's how we'd do that:

import React, { useState } from 'react';

// First we need to add a type to let us extend the incoming component.
type ExtraInfoType = {
  extraInfo: string;
};
// Mark the function as a generic using P (or whatever variable you want)
export function withExtraInfo<P>(
  // Then we need to type the incoming component.
  // This creates a union type of whatever the component
  // already accepts AND our extraInfo prop
  WrappedComponent: React.ComponentType<P & ExtraInfoType>
) {
  const [extraInfo, setExtraInfo] = useState('');
  setExtraInfo('important data.');

  const ComponentWithExtraInfo = (props: P) => {
    // At this point, the props being passed in are the original props the component expects.
    return <WrappedComponent {...props} extraInfo={extraInfo} />;
  };
  return ComponentWithExtraInfo;
}

You'll probably notice we marked withExtraInfo as a generic using <P>. For more information, see the TypeScript Handbook.

To wrap things up, you'll want to add a displayName to your HoC, which I've left as an exercise for the reader.

React-Loadable provides you with a component you can use to load a React component later, rather than immediately as you load the React app.

Why would I want to load a component later?

For example, lets say you've inherited a project from another engineer, and they've decided to use moment.js in one of the components.

The output of your webpack build gives you these chunk files, with the main one being 500kB. Of this massive bundle, 65.9kB belongs to the minified + gzipped moment.js library.

Since you're only using the component in a couple of places, it doesn't really make sense to load moment.js immediately as your users load your app. After all, they may not even use the component that uses moment.js!

If instead, you wrapped your component in Loadable, your main bundle would be (roughly) 65.9kB smaller, and only the people that need your component that uses moment.js would download that bundle.

How do I use it?

First, install it:

yarn add react-loadable

or

npm install react-loadable

React-Loadable lets you wrap your massive component like this:

import Loadable from 'react-loadable';
import Loading from './my-loading-component';

const LoadableComponent = Loadable({
  loader: () => import('./my-massive-component'),
  loading: Loading,
});

export default class App extends React.Component {
  render() {
    return <LoadableComponent />;
  }
}

Resulting in a much smaller initial load time for your React app.

<LoadableComponent> doesn't have to be in your App file, it can be anywhere in your component hierarchy.

Halving my React app's load time

Using the above approach was all I needed to shave 200KB from the main bundle of the performance monitoring tool I built (PerfBeacon).

Results:

| | | :-----------------------------------------------------------------------------------------------: | | Shaving 200KB off PerfBeacon's initial bundle reduced the TTI by more than half |

More specifically, I combined react-loadable with react-router-dom to split my bundle by the routes of my web app, resulting in a dozen or so Loadable components like this one:

// pages.js
export default pages = {
  NotFound: Loadable({
    loader: () => import('./NotFound'),
    loading: Loading,
  });
}

While this is great for a start, there's still quite a bit more optimisation work to be done here.

Jamie has a much more in-depth explanation but essentially, any place with tabs, modals, or even low priority content at the bottom of a page can benefit from using react-loadable.

Conclusion

So that's how you can use react-loadable to massively speed up your react app.

Do you manually test your web performance? Do you wish you didn't have to? I'd love to help!

I built PerfBeacon.com to automatically test web performance after each deployment.

Hey there! I've been working on building a sustainable internet business for just over two years now, and I figured I should share some lessons I've learned along the way.

In summary, over the years I've built: a job board, an appointment scheduler, a room booking tool based on the appointment scheduler, a GraphQL monitoring service, an uptime monitoring service, and I'm currently building a web performance monitoring service.

So, at the end of 2018 I wrote this article: 2018: Reflections on trying to start an internet business, in which I promised I would:

• Launch OnlineOrNot, the GraphQL monitoring solution
• Go camping more

How did I do? Well:

Real-life

We travelled and camped quite a bit!

We went camping with friends from work in Mudgee, NSW in the middle of the year, where it was as low as 0 celsius overnight. The upside of the cold being a lack of insects. Mudgee's great if you like wine and fresh air.

Later in the year we camped in the Myall Lakes National Park, south of Forster. Much warmer this time, and many, many more insects. Also it's next to a ridiculously long beach, great for chilling out.

Over Christmas, we hiked Mount Kosciuszko (highest mountain in Australia) - a 13 kilometer walk from the Thredbo chairlift. It was a really nice break from sitting in front of a laptop all day long.

Work

I worked at Expert360 as a full-time employee, working on the React frontend. After speeding up their frontend's performance (Time to Document Complete) by 75% and scrapping the microfrontend architecture in favour of a monolithic React app to save 4 seconds on each page load, I decided to go off in search of bigger and better challenges. In doing so, I also noticed I really enjoyed the challenges of tracking down performance issues on the web.

I ended up working for a large Australian marketing/advertising business, and yet again found myself working at a company that advertised a job description that didn't meet the reality of what the business needed. I lasted about two months before realising they wouldn't be needing my skills for months (if not years), and I didn't want to sit around building features for their WordPress site.

So I became a contractor! I'm currently building SiteHive's entire React frontend, data pipelines, and Node/GraphQL backend, while also building the foundation for a design system in the future.

SiteHive is an extremely early stage startup, having just made it out of an accelerator program. It's been incredibly eye-opening to witness first-hand how to find customers (mainly through personal networks), and how we use customer conversations to feed the product roadmap.

After Work

OnlineOrNot

OnlineOrNot was a GraphQL monitoring service that took snapshots of your queries, and checked them at intervals to ensure your resolvers would return what you expected them to.

My main means of acquiring users was content marketing, targeting two main keywords: 'graphql testing' and 'graphql monitoring'. Neither was particularly successful.

'graphql testing' received 929 impressions, and 3 clicks.

'graphql monitoring' received 83 impressions, and 1 click.

So if directly targeting keywords didn't work, what did?

Complaining!

I wrote an article comparing two GraphQL clients: Apollo and Relay, in which I mainly complained about their shortcomings, and in total received 20.2k impressions, and 2.28k clicks for "Relay", and 21.1k impressions, 2.41k clicks for "Apollo".

In the past 12 months OnlineOrNot received 65k total impressions, leading to 4.82k clicks, leading to 54 real signups, which lead to 1 paid user (who I sold to personally, rather than relying on content marketing).

Lesson learnt: recruit your first customers.

In short, OnlineOrNot launched on HackerNews, ProductHunt, and IndieHackers. It received very little attention, I gave it a few months to see how well content marketing would go, and I sort of gave up.

Kind of.

In September I started rewriting OnlineOrNot to be a simple uptime monitoring solution (a space with many, many competitors), with the aim of answering a single question: is my site still online, if not, what's happening?

I have no plans on a public launch, and I'm happy with just using it while contracting as a web developer.

Using a template: revisited

Though that's not the end of my indie-hacker story. Last year I built a template to make launching SaaS ideas faster. This year I spent some time developing the overall "framework" a SaaS idea needs, adding:

• Auth0 integration
• More robust authentication code (seriously, check this out)
• Rewrote most of the frontend to use React Hooks (for readability, mostly)
• Stripe integration
• Mailchimp integration
• Subscription handling (particularly feature availability in trials, but also pricing/subscription pages within the apps)

While building these features I noticed the AWS Lambda architecture I used in OnlineOrNot made swapping out the "core" of the business extremely simple, and launching another business in parallel wouldn't take much effort.

Introducing PerfBeacon

At Expert360, I found the manual work involved in optimising a web application's performance frustrating, and went searching for better tooling. PerfBeacon was started out of a desire to help improve performance across the web, and the realisation that one cannot improve without first measuring.

PerfBeacon is a synthetic frontend performance monitor, similar to how OnlineOrNot worked when it tested GraphQL queries. It runs Google Lighthouse from anywhere in the world you'd like (assuming there's an AWS datacentre there...) against a webpage, extracts key metrics you'd like to visualise, and graphs them for you.

The coolest thing I've found about it so far is that it lets you find where in the world your CDN isn't performing as well as it could be:

In terms of idea validation, I mainly just put up a landing page, and started a Twitter account to follow interesting people in web performance. Since starting in mid October, I've had 307 visitors on the website, resulting in 19 subscriptions to the mailing list (I still have no idea what I'm doing with mailing lists, I plan on sending a "We've launched!" email, and that's about it).

While this is roughly half the attention OnlineOrNot received, people are actually signing up to the mailing list, and I'm thinking this idea might have legs after all. If not, I'll still use it daily to monitor frontend performance every time I deploy, so not all will be lost.

Main things I learned this year

Recruit your first customers

This year I read The Mom Test, and Your first ten customers, and I think I finally get the whole customer acquisition/sales thing.

In my experience, getting your first 10 customers from content marketing alone is:

1. Extremely difficult to get right
2. Kind of a waste of time (unless you've got thousands of people in your mailing list)

Talking to customers is the fastest way to figure out if the problem you're solving is even a problem at all.

Your MVP can really be extremely minimal

As part of the accelerator program, SiteHive had to demonstrate its solution to potential investors and customers by a certain date. I shipped a demo with barely functioning login (hardcoded values in the backend), no database, and just a bunch of charts stuck together in React.

While the solution was quite sparse, it was already solving the problem at this point.

We were able to have highly valuable conversations with potential customers and investors with only the core features they cared about (the data visualisation). It made me realise that I really over-engineer my side-projects, thinking that everything had to be done to be able to launch.

Your tech stack does not matter

This year I worked for a company that pulls in millions in revenue per month from an insanely beefy WordPress installation. The engineering team's velocity of being able to ship features was probably the lowest I've ever seen, and yet the business was still making bank.

The takeaway here is to just use whatever technology you're comfortable with.

There is no shame in using Ruby on Rails, Django, or even a code-free solution like Airtable/Zapier in 2020.

Shipping something that people find useful/valuable beats using Svelte/Vue/Angular/React or whatever people are arguing about in JavaScript frameworks.

2020 Plans

Finish up PerfBeacon, and launch!

I originally was going to wait until PerfBeacon was "feature-complete" before launching, but after working for SiteHive for a few months, I've realised getting anything to market, and being able to talk to people about it is much more valuable.

After launching, I'll be making it possible to test on-demand (like during a CI process), and also show screenshots of different points in the tested page's load process.

Writing this section feels like déjà vu - I essentially had an identical goal for OnlineOrNot at the end of 2018.

This time it'll be different though. I won't be relying on/praying for content marketing to do the job for me, and instead will be reaching out to companies in real life to discuss how they track their web performance.

Screencasts

Around October this year I bought a microphone with the intention of making screencasts explaining things in JavaScript and React that took me ages to understand. I didn't get around to actually doing it in between hunting for jobs and building PerfBeacon and OnlineOrNot, so hoping to get some out there next year. I intend to follow these awesome guides from egghead.io.

Ciao!

Anyway, here’s me signing off for 2019, Happy New Year folks!

Alternative title: Why early startups are either the worst or best idea for junior developers, depending on what they're after.

Before I dive into what I have to say, I feel like I should introduce myself.

Hey 👋! I'm Max, I work as a software engineer at an early stage startup. I'm building a web performance monitoring service on the side, I've worked in the corporate world as well as various stages of startup, from seed round through to Series C. I feel like I finally understand what I want out of my career, and I wanted to share my thoughts.

At the risk of grossly generalising, I'd say there are three types of developer that you'll meet.

1. You've got the people that want to be the best version of themselves they can be, by mastering their craft.
2. Then there are the people that want to build the best product, and understand how to make their users happy.
3. Finally, you have people that just want to do the job from 9 to 5, and not think about programming once they're done.

Personally, I jump between the three types several times per day depending on my mood, though up until recently I'd say I focused most on trying to master my craft.

From what I've seen (from myself), being the first type of developer easily leads you to dissatisfaction and burn-out if you're not in the right organisation. Your typical early stage startup is more worried about finding a product that matches a user's need much more than it worries about writing unit tests, or typing its JavaScript correctly. Although having a product focus isn't unique to early stage startups. I've seen it first-hand in several organisations, as well as the impact on the organisation when its best engineers get frustrated by the "ship it now!" culture and leave.

If as a junior developer your goal is to learn as much as possible about the best ways of doing things, I'd argue a startup that is still finding its product-market fit is a bad idea.

The trick to building a career that lets you work towards being the best developer you can be is to find an organisation that has already found its product-market fit, and is comfortably guided by a tight engineering culture.

It's not all doom and gloom for early-stage startups however.

If your goal is to build the best product, develop the skills you need to build things that people actually want, maybe an early-stage startup is the right fit.

As a developer, one of the hardest things you need to learn is that the user does not care what technology your product is running. You could still be using PHP 5.6.40 and Zend framework - as long as you're building product that does what the user needs to be awesome at their job, and your product doesn't piss them off, they'll be happy.

In the end, you need to:

• figure out what you want from an organisation, whether it's a product focus, engineering focus, or just want to do the job
• interview the organisation as much as they're interviewing you, and figure out what kind of focus they have, and whether that's compatible with your goals
• be comfortable with ending an interview process for a role that doesn't meet your goals

style-loader

style-loader takes CSS you've imported in your JavaScript files, and injects them as <style></style> tags into the DOM. It's particularly useful for inlining Critical CSS into the <head> of your page.

If you decide to self-host your fonts instead of using Google Fonts, style-loader can also help you inline your font declarations so the browser knows immediately what to do with the font files it downloads.

How do you use style-loader?

/* style.css */
body {
  background: green;
}

/* component.js */
import './style.css';

/* webpack.config.js */
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: ['style-loader', 'css-loader'],
      },
    ],
  },
};

mini-css-extract-plugin

mini-css-extract-plugin on the other hand, extracts your CSS into separate files.

It generates a CSS file for each JS file that imports CSS. It's more useful for CSS that you want to load asynchronously.

How do you use mini-css-extract-plugin?

/* webpack.config.js */
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
module.exports = {
  plugins: [
    new MiniCssExtractPlugin({
      // Options similar to the same options in webpackOptions.output
      // all options are optional
      filename: '[name].css',
      chunkFilename: '[id].css',
      ignoreOrder: false, // Enable to remove warnings about conflicting order
    }),
  ],
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: MiniCssExtractPlugin.loader,
            options: {
              // you can specify a publicPath here
              // by default it uses publicPath in webpackOptions.output
              publicPath: '../',
              hmr: process.env.NODE_ENV === 'development',
            },
          },
          'css-loader',
        ],
      },
    ],
  },
};

Making relay-compiler run automatically

Relay can be annoying to work with as relay-compiler needs to run every time you change your GraphQL schema, or your resolvers.

With relay-compiler-webpack-plugin that's no longer the case - webpack can run it for you!

Here's how you use it:

const RelayCompilerWebpackPlugin = require('relay-compiler-webpack-plugin');
// rest of your config
new RelayCompilerWebpackPlugin({
    schema: 'schema.graphql',
    src: 'src/',
    extensions: ['js', 'jsx', 'ts', 'tsx'],
    artifactDirectory: 'src/__generated__',
}),

Through the use of html-webpack-plugin you can inject variables into the HTML your webpack build generates - no more hardcoding!

Here's how you use it:

First, run yarn add -D html-webpack-plugin or npm install --save-dev html-webpack-plugin

Then, add the following to your webpack config:

/* webpack.config.js */
const HtmlWebpackPlugin = require('html-webpack-plugin');
// rest of your config
plugins: [
  new HtmlWebpackPlugin({
    template: 'index.tmp.html',
    filename: 'index.html',
    templateParameters: {
      some_variable: process.env.SOME_VAR,
    },
  }),
];

index.tmp.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta name="description" content="" />
    <meta name="author" content="" />
    <title><%= some_variable %></title>
  </head>
  <body>
    <div id="root"></div>
  </body>
</html>

In order for process.env.SOME_VAR to have a variable, you can either use a .env file, or enter the values as part of your CI's configuration (services such as CircleCI and Netlify support this).

Remember that variables injected this way are visible to your users!

webpack has an option called resolve which can help prevent some gnarly errors in packages like React and GraphQL.

What happens is, some packages choose to include common packages as dependencies rather than as peer dependencies. Net result is that your bundle ends up larger, or in the case of React or GraphQL packages, you get random errors.

In React, having more than one version of React in your dependencies can cause this common error: hooks can only be called inside the body of a function component.

Luckily for us, the fix is pretty simple - we add the following to our webpack config:

 resolve: {
    alias: {
      react: path.dirname(require.resolve('react')),
    },
  }

webpack has a ridiculous number of settings and plugins that you can fine-tune to make your frontend more performant, have smaller bundles, and generally behave the way you expect it to.

The trick is taking the time to actually understand what the settings in your webpack config do.

The articles below cover a few settings and plugins (that were correct as of 2019-10-26) I use regularly, and can help optimise your webpack configuration.

• Settings
  • Using resolve.alias to set which package your code should use
  • The difference between style-loader and mini-css-extract-plugin
• Plugins
  • Injecting variables into HTML that webpack builds
  • Making webpack compile Relay automatically

Why is Google Fonts an issue?

The cost of using a call such as

@import url('https://fonts.googleapis.com/css?family=Lato:300,400,900');

is that the browser first has to download the CSS file, and parse it. Afterwards, the browser downloads your fonts. This process is particularly syncronous, so we can't download your fonts until we ask Google for the location of the font files we need.

How do we speed things up?

We can get a large performance boost by self-hosting our fonts. To do this, you would need to:

1. Use google-webfonts-helper to figure out which fonts you needed to download
2. Check them into your repo
3. Reference them in your CSS
4. Ensure that CSS is in-lined in your HTML, and among the first CSS to be read by browsers

This is a bit involved, but totally worth it. At a previous employer I managed to shave 300ms off of page load time by self-hosting fonts.

Enter gatsby-plugin-prefetch-google-fonts

Now with gatsby-plugin-prefetch-google-fonts, you can save 3-400ms with a little bit of configuration.

1. Install: yarn add gatsby-plugin-prefetch-google-fonts
2. Configure gatsby-config.js:

  {
      resolve: `gatsby-plugin-prefetch-google-fonts`,
      options: {
        fonts: [
          {
            family: `Lato`,
            variants: [`300`, `400`, `900`],
          },
        ],
      },
    },

Results

Before:

WebPageTest result

If you look at the time spent by Resource 8, 10, and 11, you can see we're waiting quite a bit just to get the page's fonts loaded.

It's also not the first thing the browser does, so we're likely going to see a flash of missing font. This also depends on what your font-display setting is in CSS.

After:

WebPageTest result

After adding the prefetch plugin, we can see Resource 2, 3, and 4 being immediately loaded once we fetch the page.

I was so impressed with these results that I wrote this blog post!

What does "semantic" mean?

To write semantic HTML is to give it meaning, rather than just describing how it should look in the browser.

Take this code snippet for example:

<div class="heading">My Heading</div>
<div class="paragraph">Here's a sentence I wrote just for you.</div>

While it is possible to write CSS to make your heading and paragraph classes appear as you like, software tooling that reads your markup has no idea what it means. It'll just see text within a div, and not know how the text in the first div relates to the second div.

Here's the semantic way of writing the previous example:

<h1>My Heading</h1>
<p>Here's a sentence I wrote just for you.</p>

The advantages of writing your HTML semantically are:

• You get a set of default styles for free (which you can override with CSS if you wish)
• Communication: Developers who read your code in the future instantly know what was intended - there is no ambiguity to semantic markup
• SEO: Search engines like Google look for <h1> tags to determine which keywords to associate your content with
• Screen readers can now read your content as you intended

More examples of Semantic vs Non-semantic markup

Buttons

Good:

<button>Click me</button>

Bad:

<div>Click me</div>

Why is this bad?

Divs are not focusable by keyboards. We could make them focusable by adding tabindex="0", but this can still be hacky in the case of inputs.

Inputs

Good:

<input type="checkbox" />

Bad:

<div role="checkbox"></div>

Why is this bad?

As mentioned before, divs are not focusable by default. Adding tabindex="0" here will make your div focusable, but then you would also need to write additional JavaScript to submit the value of your "checkbox" when the rest of the form submits.

How I read:

I used to absolutely suck at reading books (and I still do, come to think of it). The whole having a physical book in your hands thing, trying to find a comfortable position to read just before going to sleep while your elbows are going numb - so annoying. Don't get me wrong though, I absolutely love the physical act of reading, I just sucked at making it a habit, and being comfortable while reading.

Then I discovered podcasts, which eventually lead me to Audible. Instead of reading 3-4 books a year (mostly while on flights/trains to holiday destinations), I now read around 14-16. I typically listen while commuting to work, though occasionally while doing household chores I'll also put on a book. You'd be surprised how quickly those 30 minute commutes add up!

The books that didn't make it

A few books I bought either didn't resonate with me, or the narration was atrocious - so I just returned them. The books below are only the ones I actually wanted to finish reading.

The list

• Why We Sleep - Matthew Walker
• Bullshit Jobs - David Graeber
• It Doesn't Have To Be Crazy at Work - DHH, Jason Fried
• Rework - Jason Fried, DHH
• Angel - Jason Calacanis
• Blitzscaling - Reid Hoffman, Chris Yeh
• Debt - David Graeber (half-finished)
• Hooked: How to Build Habit-Forming Products - Nir Eyal
• Thinking in Bets - Annie Duke
• High Growth Handbook - Elad Gil (half-finished)
• The Upstarts - Brad Stone
• The Everything Store - Brad Stone
• All Marketers Are Liars - Seth Godin
• Creativity Inc - Ed Catmull
• The Icarus Deception - Seth Godin
• Purple Cow - Seth Godin

2018, what a year

On the personal side

I Interviewed at Facebook, first for front-end, then for full-stack. Considering the year Facebook has had, I'm okay with not getting the job.

Roughly around the time I was interviewing at Facebook, I took up the #vanlife with my partner and toured through California in a purple van. When I came back home, I finally took the driving test and got a wagon to continue the #vanlife here in Australia.

I then quit my job at Arup (building engineering consultancy) to go work at a Fintech startup aiming to revolutionise the retail investing space for Mum & Dad investors. After 3 weeks I quit the startup job, once we realised the job they advertised for and the job they wanted me to do weren't exactly aligned with my skillset (I see myself as probably 75% front-end, while 100% of the work they had for me was back-end for the foreseeable future).

In between jobs I picked up freelancing as a way to make some extra money, migrating EthicalEquities from WordPress to Django, and added a forum to build more of a community around ethical investing.

After about 6 days of freelancing full-time, I joined Expert360 as an employee, where I (mostly) work on the front-end in React. I've been helping to build a Design System as well as some product work.

On the business side, chronologically

JobsOk.io

I finished building an MVP for JobsOk.io (A tech job board where posting an ad would only cost $199 US) in a thinly veiled attempt at emulating Pieter Levels' success with RemoteOk.

What I learned here is that your implementation is meaningless to the user if you're not delivering the value they came for. In this case, I wanted to take a technologically inferior product, make it extremely efficient, scalable and "blazing fast", and pocket pure profit from running a serverless job board (effectively free to run for the first million visits a month)

I was failing to deliver value to users solely because I didn't have the traffic to compete with other job boards. The reason StackOverflow can charge as much as it does is the millions of page views per month it receives, creating value to its job posters.

In total, JobsOk logged 761 sessions for 661 users in 2018. While a total commercial failure, I did learn a lot about running GraphQL in production, and using off the shelf Design Systems (Material-UI).

I eventually revisited JobsOk, and migrated it from being a client-side app to server-side rendered app in AWS Lambda (Check out Razzle).

AppointmentScheduler.org

I finished building an MVP for AppointmentScheduler.org - another hero-inspired product (in this case, patio11), AppointmentScheduler was going to have a freemium product model to take appointments for any industry that needed appointment scheduling software. I intended to use content marketing to acquire users.

I honestly thought I had learned "if you build it, they will not come" before building AppointmentScheduler. Turns out I did not. It took about a month of weekends, and time after work to build. I also spent part of that month writing pretty vague, average blog posts to try attract users, to no avail. I had planned to build beyond the free feature set if I had seen enough users using the site, however most people came for the blog posts, and didn't stick around to see the app.

The site was unique in that it was a 100% pure Gatsby.js site, where I added a client-only section under the /app path.

In total, AppointmentScheduler logged 561 sessions for 496 users in 2018.

RoomBooking.co

I started work on an MVP of a spin-off product from AppointmentScheduler - Roombooking.co, only to find the Google API restrictions meant I would have to implement most of it myself. RoomBooking would let you select slots in a Room's Google Calendar and see when it would be available for use.

I was starting to finally understand the lean start-up methodology at this point, so I had spoken to a few people working in businesses too small to afford using Microsoft Outlook for meeting room bookings, but large enough to need a system to book meeting rooms. There seemed to be a clear need for a means of booking rooms in a business. I only spent a week of time after work on this, as I wasn't particularly interested in the problem space.

I wanted to be able to create a public calendar in Google Calendar, while also allowing anyone to create events on that public calendar, while restricting the viewing of events to the Owner of the calendar. Turns out Google won't let you do it. Unwilling to implement it myself, I canned the project, and wrote a blog post about the experience.

Using a template to build side-projects

Half-way through the year, I realised I had been building all of these side projects from scratch each time, and had been pretty burned out by the experience. I basically didn't write any fresh side-project code for four months, though I did try to keep coming up with ideas (I actually bought the domain for two of the ideas, RecordMyWeight.com and IndiePhotogs.com - though I never used them).

In August, I collected all of the code I had written all year and built myself a React + GraphQL server template in Terraform that deploys a complete site with HTTPS, CDN caching via CloudFront, GraphQL server & SSR server running in AWS Lambda.

To avoid having to go back and update version numbers in the template, I actually wrote it in the form of a three-part blog:

• Server-side Rendering, Serverlessly!
• Deploying to a real domain name
• Let's build a GraphQL backend!

OnlineOrNot - finally a problem worth solving

Since starting my career as a software engineer I've found APIs to be a pain to work with.

My first experience working with a "back-end" developer as a front-end developer to build a dashboard for financial data essentially involved having a financial quant dump a spreadsheet into the Python pandas library, and outputting the result to JSON. At one point in the project, the API's result would break the front-end every 3 hours, despite there being contracts in place to prevent this from happening. If we had a tool capable of snapshotting the API result and alerting our boss whenever it changed, the project would have gone much more smoothly.

Most developers I spoke to while validating this project's commercial viability had a similar story, or could relate to the problem. Being able to ensure your API is operating correctly is particularly tricky with GraphQL, as GraphQL servers do not respond with 5xx error codes when they fail.

My approach to deciding whether or not to build OnlineOrNot was slightly more rigorous than my previous side-projects, as I really wanted to make sure people would actually pay for this. I spoke to former coworkers, and current coworkers to try understand how developers ensure GraphQL is running - and in short, it's really hard!

So after a month of testing whether people liked the idea, I set off to build OnlineOrNot using my side-project template I had developed back in August. I had quite ambitiously wanted to launch my beta by December 1, however when you're working on a product after work and on weekends, occasionally life gets in the way. I have still not yet officially "launched" the product, I'm still actively recruiting my first ten customers to help beta test the tool.

It being December 31 today, I'd say OnlineOrNot is very close to a public launch - it's embarrassingly under-featured, but still executes on its core-value proposition of automating GraphQL testing & uptime monitoring.

Since October 1 the marketing site has received 557 sessions from 491 users (roughly 4x each of my previous side-projects in a comparable period of time).

2019 Plans

Launch OnlineOrNot, make an actual "Company"

I plan on launching OnlineOrNot on ProductHunt, IndieHackers and Hacker News to get more users for the public beta. I'm not really expecting much, if I can get around 10 users trialling the product and leaving feedback I would be over the moon.

If I manage to get a few customers I'll also start a company to own the IP. As much as I love being a sole-trader, something about being exposed to unlimited liability when dealing with B2B transactions sounds a touch unpleasant.

My longer-term play for user acquisition will still be classic content marketing, but also launching on LinkedIn, and using StackOverflow questions to help potential users learn about the service.

Go camping more

My partner and I bought a Subaru Outback 2005 to go car camping around Australia, and when (if?) the weather cools down a bit we'll try car camping around the East Coast of NSW.

Sell some camera gear

Since I started photography as a hobby about 5 years ago, I've accumulated around 26 cameras and various lenses. While I've been slowly selling off bits and pieces to friends and family, I'd love to be able to spend that money on investing, instead of cameras.

Anyway, here's me signing off for 2018, Happy New Year folks!

Note that this series was written in 2018, using an older version of Terraform (version 12), available here. As it also uses an old version of Node, this series is left online as more of a guideline.

To start, open up your terminal, navigate to your app, and type:

mkdir api

We'll now start a new npm project for our GraphQL server (you could integrate more with the Razzle project, but I'm not entirely sure how).

npm init -y

And now we'll add all the dependencies:

yarn add cors graphql graphql-tag graphql-tools request request-promise-native

and dev-dependencies:

yarn add -D webpack babel-core babel-loader babel-plugin-inline-import babel-plugin-transform-class-properties babel-plugin-transform-object-rest-spread cross-env zip-webpack-plugin webpack-cli

Time to add add some JavaScript files

Create a .babelrc file in api/, containing:

{
  "presets": ["env"],
  "plugins": [
    "inline-import",
    "transform-class-properties",
    "transform-object-rest-spread"
  ]
}

In your package.json add the following scripts:

"dev": "cross-env BABEL_DISABLE_CACHE=1 node -r babel-register local.js",
"build": "cross-env BABEL_DISABLE_CACHE=1 webpack --config=webpack.config.babel.js --env=production"

Create a local.js file in api/, containing:

import cors from 'cors';
import express from 'express';
import schema from './schema';
import { json } from 'body-parser';
import { graphql } from 'graphql';

const PORT = process.env.PORT || 3002;

const app = express();

app.use(cors());

app.post('/graphql', json(), (req, res) => {
  const { query, variables } = req.body;
  const rootValue = {};
  const context = {};
  let operationName;
  console.log('query: ', query);
  console.log('variables: ', variables);
  graphql(schema, query, rootValue, context, variables, operationName)
    .then((d) => {
      console.log('d: ', d);
      res
        .status(200)
        .set('Content-Type', 'application/json')
        .send(JSON.stringify(d));
    })
    .catch((e) => {
      console.log('e: ', e);
      res
        .status(500)
        .set('Content-Type', 'application/json')
        .send(JSON.stringify(e));
    });
});

app.listen(PORT, (err) => {
  if (err) {
    throw err;
  }
  console.log(`Listening on http://localhost:${PORT}/`);
});

Create an index.js file in api/, containing:

import { graphql } from 'graphql';
import schema from './schema';

export const handler = (event, context, callback) => {
  context.callbackWaitsForEmptyEventLoop = false;
  console.log('event:', event);

  if (event.httpMethod == 'OPTIONS') {
    callback(null, {
      statusCode: 200,
      headers: {
        'Access-Control-Allow-Origin': '*',
        'Access-Control-Allow-Headers': 'Authorization, Content-Type',
        'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, PATCH',
        'Access-Control-Allow-Credentials': 'true',
        'Content-Type': 'application/json',
      },
      body: null,
    });
  } else {
    const { query, variables, operationName } = JSON.parse(event.body);
    const rootValue = {};
    const ctx = {};
    graphql(schema, query, rootValue, ctx, variables, operationName)
      .then((d) => {
        callback(null, {
          statusCode: 200,
          headers: {
            'Access-Control-Allow-Origin': '*',
            'Access-Control-Allow-Headers': 'Authorization, Content-Type',
            'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, PATCH',
            'Access-Control-Allow-Credentials': 'true',
            'Content-Type': 'application/json',
          },
          body: JSON.stringify(d),
        });
      })
      .catch((e) => {
        callback(null, {
          statusCode: 503,
          headers: {
            'Access-Control-Allow-Origin': '*',
            'Access-Control-Allow-Headers': 'Authorization, Content-Type',
            'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, PATCH',
            'Access-Control-Allow-Credentials': 'true',
            'Content-Type': 'application/json',
          },
          body: JSON.stringify(e),
        });
      });
  }
};

Create a resolvers.js file in api/, containing:

export default {
  Query: {
    hello: () => 'world',
  },
  // Mutation: {
  //
  // },
};

Create a schema.graphql file in api/, containing:

type Query {
  hello: String!
}

#type Mutation {
#
#}

schema {
  query: Query
  #mutation: Mutation
}

Create a schema.js file in api/, containing:

import { makeExecutableSchema } from 'graphql-tools';
import typeDefs from './schema.graphql';
import resolvers from './resolvers';

export default makeExecutableSchema({
  typeDefs,
  resolvers,
});

Finally, create a webpack.config.babel.js file in api/, containing:

import path from 'path';
import webpack from 'webpack';
import zip from 'zip-webpack-plugin';

export default {
  entry: path.resolve(__dirname),
  output: {
    path: path.join(__dirname, '..', 'build'),
    filename: 'index.js',
    library: 'index',
    libraryTarget: 'umd',
  },
  target: 'node',
  module: {
    rules: [
      {
        test: /\.js$/,
        include: path.resolve(__dirname, '..'),
        exclude: path.resolve(__dirname, '..', 'node_modules'),
        loader: 'babel-loader',
      },
      {
        test: /\.graphql$/,
        include: path.resolve(__dirname, '..'),
        exclude: path.resolve(__dirname, '..', 'node_modules'),
        loader: 'graphql-tag/loader',
      },
    ],
  },

  plugins: [
    new webpack.ProvidePlugin({
      XMLHttpRequest: ['xmlhttprequest', 'XMLHttpRequest'],
    }),
    new zip({
      filename: 'graphql.zip',
    }),
  ],
};

That's all you should need to get the GraphQL service running locally.

Terraform changes

We also need to make some changes to our Terraform configuration to:

• Spin up a new Lambda for GraphQL
• Spin up a new API Gateway for the new Lambda
• Tell Cloudfront to forward all /graphql requests to our API Gateway

Back in infrastructure/, create a api_gateway_lambda.tf file containing:

resource "aws_api_gateway_rest_api" "graphql_api" {
  name        = "${var.name}_api"
  description = "${var.comment}"
}

resource "aws_api_gateway_deployment" "graphql_api_deployment" {
  rest_api_id = "${aws_api_gateway_rest_api.graphql_api.id}"
  stage_name  = "prod"
}


resource "aws_api_gateway_resource" "grapqhl_endpoint" {
  rest_api_id = "${aws_api_gateway_rest_api.graphql_api.id}"
  parent_id   = "${aws_api_gateway_rest_api.graphql_api.root_resource_id}"
  path_part   = "graphql"
}

resource "aws_api_gateway_method" "graphql_path_post" {
  rest_api_id   = "${aws_api_gateway_rest_api.graphql_api.id}"
  resource_id   = "${aws_api_gateway_resource.grapqhl_endpoint.id}"
  http_method   = "ANY"
  authorization = "NONE"
}

resource "aws_api_gateway_integration" "graphql_path_integration" {
  rest_api_id             = "${aws_api_gateway_rest_api.graphql_api.id}"
  resource_id             = "${aws_api_gateway_resource.grapqhl_endpoint.id}"
  http_method             = "${aws_api_gateway_method.graphql_path_post.http_method}"
  integration_http_method = "POST"
  type                    = "AWS_PROXY"
  uri                     = "arn:aws:apigateway:${var.aws_region}:lambda:path/2015-03-31/functions/${aws_lambda_function.graphql.arn}/invocations"
  content_handling        = "CONVERT_TO_TEXT"
}

resource "aws_api_gateway_method" "graphql_post" {
  rest_api_id   = "${aws_api_gateway_rest_api.graphql_api.id}"
  resource_id   = "${aws_api_gateway_rest_api.graphql_api.root_resource_id}"
  http_method   = "ANY"
  authorization = "NONE"
}

resource "aws_api_gateway_integration" "graphql_integration" {
  rest_api_id             = "${aws_api_gateway_rest_api.graphql_api.id}"
  resource_id             = "${aws_api_gateway_rest_api.graphql_api.root_resource_id}"
  http_method             = "${aws_api_gateway_method.graphql_post.http_method}"
  integration_http_method = "POST"
  type                    = "AWS_PROXY"
  uri                     = "arn:aws:apigateway:${var.aws_region}:lambda:path/2015-03-31/functions/${aws_lambda_function.graphql.arn}/invocations"
  content_handling        = "CONVERT_TO_TEXT"
}

In infrastructure/ create a lambda_graphql.tf file containing:

resource "aws_lambda_function" "graphql" {
  function_name    = "graphql_${var.name}"
  role             = "${aws_iam_role.lambda_iam.arn}"
  handler          = "index.handler"
  runtime          = "nodejs8.10"
  timeout          = "45"
  memory_size      = "512"
  filename         = "../build/graphql.zip"
  source_code_hash = "${base64sha256(file("../build/graphql.zip"))}"

  tags {
    Site = "${var.name}"
  }
}


resource "aws_lambda_permission" "allow_api_to_exec_lambda_graphql" {
  statement_id  = "allow_api_to_exec_lambda_graphql"
  action        = "lambda:InvokeFunction"
  function_name = "${aws_lambda_function.graphql.function_name}"
  principal     = "apigateway.amazonaws.com"
  source_arn = "${aws_api_gateway_rest_api.graphql_api.execution_arn}/*/*/*"
}

In our existing cloudfront.tf file, we'll want to add this immediately after the ssr origin_id block:

 origin {
   origin_id = "api"

   domain_name = "${aws_api_gateway_rest_api.graphql_api.id}.execute-api.${var.aws_region}.amazonaws.com"

   custom_origin_config {
     http_port              = "80"
     https_port             = "443"
     origin_protocol_policy = "match-viewer"
     origin_ssl_protocols   = ["TLSv1", "TLSv1.1", "TLSv1.2"]
   }

   origin_path = "/${aws_api_gateway_deployment.graphql_api_deployment.stage_name}"
 }

Similarly, still in the cloudfront.tf file, add the following immediately after the ordered_cache_behavior for /static/*:

 ordered_cache_behavior {
   path_pattern           = "graphql"
   allowed_methods        = ["DELETE", "GET", "HEAD", "OPTIONS", "PATCH", "POST", "PUT"]
   cached_methods         = ["GET", "HEAD"]
   target_origin_id       = "api"
   default_ttl            = 0
   max_ttl                = 0
   min_ttl                = 0
   viewer_protocol_policy = "https-only"
   compress               = true

   forwarded_values {
     query_string = true

     cookies {
       forward = "all"
     }

     headers = [
       "Accept",
       "Authorization",
       "Origin",
     ]
   }
 }

At this point you can run terraform apply - You will most likely get an error regarding an API Gateway integration not existing. This is a race condition, and we can get around it just by re-running terraform apply.

Note that this series was written in 2018, using an older version of Terraform (version 12), available here. As it also uses an old version of Node, this series is left online as more of a guideline.

Welcome to Part 2 of Starting your own app. In Part 1, we got an AWS Lambda function to render React, and in Part 2, we'll be setting that function up to run on our own domain name, with a free SSL certificate!

To begin, you'll need to already own a domain in AWS Route 53. Check out https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/registrar.html for more details on getting that set up.

1. Create a new file in your infrastructure/ folder, called route53.tf, containing:

   data "aws_route53_zone" "site_zone" {
     name = "${var.domain_name}"
   }
   
   resource "aws_route53_record" "cf_alias_A" {
     zone_id = "${data.aws_route53_zone.site_zone.zone_id}"
     name    = "${var.domain_name}"
     type    = "A"
   
     alias {
       name                   = "${aws_cloudfront_distribution.site.domain_name}"
       zone_id                = "${aws_cloudfront_distribution.site.hosted_zone_id}"
       evaluate_target_health = true
     }
   }
   
   resource "aws_route53_record" "cf_alias_AAAA" {
     zone_id = "${data.aws_route53_zone.site_zone.zone_id}"
     name    = "${var.domain_name}"
     type    = "AAAA"
   
     alias {
       name                   = "${aws_cloudfront_distribution.site.domain_name}"
       zone_id                = "${aws_cloudfront_distribution.site.hosted_zone_id}"
       evaluate_target_health = true
     }
   }
   

   This creates records pointing to the CloudFront distribution we'll create later on

2. Edit your vars.tf file, adding the following variable (swap out recordmyweight.com with your own domain name):

   variable "domain_name" {default = "recordmyweight.com"}

3. You'll also want to change the bucket_site variable in vars.tf to match your domain (Remove .'s in your bucket_site to avoid issues with SSL):

   variable "bucket_site" {default = "recordmyweightcom"}

   This renames the my-app-12345 bucket to your new variable value.

4. In your main.tf file, add the following:

   provider "aws" {
     alias  = "east"
     region = "us-east-1"
   }
   

   This will let us create an SSL certificate in the us-east-1 zone later, for CloudFront's use.

5. Create a acm_certificate.tf file, containing the following (making sure to replace www.recordmyweight.com with your own subdomain):

   variable "san_domains" {
     default = [
       "www.recordmyweight.com"
     ]
   }
   
   data "aws_route53_zone" "zone" {
     name = "${var.domain_name}."
     private_zone = false
   }
   
   resource "aws_acm_certificate" "cert" {
     domain_name               = "${var.domain_name}"
     validation_method         = "DNS"
     subject_alternative_names = "${var.san_domains}"
     provider = "aws.east"
   }
   
   resource "aws_route53_record" "cert" {
     count   = "${length(var.san_domains) + 1}"
     zone_id = "${data.aws_route53_zone.zone.id}"
     name    = "${lookup(aws_acm_certificate.cert.domain_validation_options[count.index], "resource_record_name")}"
     type    = "${lookup(aws_acm_certificate.cert.domain_validation_options[count.index], "resource_record_type")}"
     records = ["${lookup(aws_acm_certificate.cert.domain_validation_options[count.index], "resource_record_value")}"]
     ttl     = 60
   }
   
   resource "aws_acm_certificate_validation" "cert" {
       provider = "aws.east"
       certificate_arn = "${aws_acm_certificate.cert.arn}"
       validation_record_fqdns = ["${aws_route53_record.cert.*.fqdn}" ]
   }
   

   This creates a globally accessible SSL certificate, and verifies that you own the domain you're registering the certificate for.

6. The final step is to add a cloudfront.tf file, containing the following:

   resource "aws_cloudfront_distribution" "site" {
     origin {
       domain_name = "${var.bucket_site}.s3-website-${var.aws_region}.amazonaws.com"
       origin_id   = "s3"
   
       custom_origin_config {
         http_port              = "80"
         https_port             = "443"
         origin_protocol_policy = "http-only"
         origin_ssl_protocols   = ["TLSv1", "TLSv1.1", "TLSv1.2"]
       }
     }
   
     origin {
       domain_name = "${aws_api_gateway_rest_api.ssr.id}.execute-api.${var.aws_region}.amazonaws.com"
       origin_id = "ssr"
   
       custom_origin_config {
         http_port              = "80"
         https_port             = "443"
         origin_protocol_policy = "match-viewer"
         origin_ssl_protocols   = ["TLSv1", "TLSv1.1", "TLSv1.2"]
       }
   
       origin_path = "/${aws_api_gateway_deployment.ssr_deployment.stage_name}"
     }
   
     enabled             = true
     is_ipv6_enabled     = true
     comment             = ""
     default_root_object = "index.html"
     retain_on_delete    = true
     aliases             = ["${var.domain_name}"]
   
     default_cache_behavior {
       allowed_methods  = ["GET", "HEAD"]
       cached_methods   = ["GET", "HEAD"]
       target_origin_id = "ssr"
       compress         = true
       forwarded_values {
         query_string = true
   
         cookies = {
           forward = "none"
         }
       }
   
       viewer_protocol_policy = "redirect-to-https"
       min_ttl                = 0
       max_ttl                = 0
       default_ttl            = 0
     }
   
     ordered_cache_behavior {
       path_pattern           = "/static/*"
       allowed_methods        = ["GET", "HEAD"]
       cached_methods         = ["GET", "HEAD"]
       target_origin_id       = "s3"
       compress               = true
       default_ttl            = 0
       max_ttl                = 0
       min_ttl                = 0
       viewer_protocol_policy = "https-only"
   
       forwarded_values {
         query_string = true
   
         cookies {
           forward = "all"
         }
   
         headers = [
           "Accept",
           "Authorization",
           "Origin",
         ]
       }
     }
   
     price_class = "PriceClass_All"
   
     restrictions {
       geo_restriction {
         restriction_type = "none"
       }
     }
   
     tags {
       Project = "${var.name}"
     }
   
     viewer_certificate {
       ssl_support_method       = "sni-only"
       minimum_protocol_version = "TLSv1"
       acm_certificate_arn   = "${aws_acm_certificate_validation.cert.certificate_arn}"
   
     }
   }
   

   This one might seem quite complicated initially - but it only does a few things:

   • Sets up two origins (ssr and s3)
   • Creates a default cache (pointing at the ssr origin), and a secondary cache (pointing to the s3)
   • Uses the SSL certificate created earlier to secure the CDN

7. Finally, run terraform apply again, type yes to confirm and wait for terraform to finish building your infrastructure.

8. At this point, go into razzle.config.js and remove this line:

   appConfig.output.publicPath = `${process.env.PUBLIC_PATH}`
   

9. Also go into package.json and remove this part of the build script:

   PUBLIC_PATH=https://recordmyweightcom.s3-ap-southeast-2.amazonaws.com/public/
   

   You also want to change this section:

   aws s3 sync \"./build/public/\" s3://recordmyweightcom/public
   

   to be:

   aws s3 sync \"./build/public/\" s3://recordmyweightcom
   

   So in the end it should look like:

   "razzle build && aws s3 sync \"./build/public/\" s3://recordmyweightcom && cd ./build && zip -r ./server.zip ./server.*",
   

10. Also, in infrastructure/s3.tf, change this line:

    allowed_origins = ["https://${aws_api_gateway_deployment.ssr_deployment.rest_api_id}.execute-api.${var.aws_region}.amazonaws.com"]
    

    to read:

    allowed_origins = ["https://${var.domain_name}"]
    

11. Now run npm run build, wait for it to complete, then go into infrastructure/ and run terraform apply. This'll redeploy our app using a CDN, rather than your local S3 to serve static resources. This concludes Part 2: Let's get this running in production

Note that this series was written in 2018, using an older version of Terraform (version 12), available here. As it also uses an old version of Node, this series is left online as more of a guideline.

In this blog post series I'll walk you through what you need to do (tech-wise) to have a React app where your customers can login, pay for things and use your internet business.

Pre-work - Know:

1. Basics of JavaScript ES6
2. AWS (we'll be spinning up resources using terraform)
3. How to debug when things don't go your way.

I'll be describing modifications to make to existing code, rather than providing a fully complete repository, to ensure that this guide is easier to update.

The architecture consists of four main parts:

1. A GraphQL server (A server running in AWS Lambda - Node v8 environment)
2. A database of some sort (either Key:Value store such as DynamoDB or traditional, like postgres/mysql)
3. A 'Server-side rendering' server (the React app running in AWS Lambda - Node v8 environment)
4. The Static resources - sitting in an S3 bucket, sent to your users via a CloudFront CDN (which also conveniently provides you with free SSL certificates!)

On the payment side of things, we'll add a GraphQL resolver that talks to Stripe, but that'll be covered in a later blog post.

To begin, we're going to use Razzle. It's like Create-react-app, but for server-side rendering.

npm install -g create-razzle-app

create-razzle-app my-app
cd my-app
npm start

Now, because we're going to be deploying this onto a serverless environment, we need to change how Razzle builds code. To do that, we're going to create a file in the project root directory called razzle.config.js, with the following content:

module.exports = {
  modify: (config, { target, dev }, webpack) => {

    const appConfig = config

    if (target === 'node' && !dev) {
      appConfig.externals = []
      appConfig.output.publicPath = `${process.env.PUBLIC_PATH}`
    }

    return appConfig
  },
}

Next, we'll edit the src/index.js file to allow us to run in AWS Lambda when we're in production, and run normally when we're developing locally. Run npm install aws-serverless-express in the project root, then replace the contents of src/index.js with:

import app from './server'
export let handler

if (process.env.NODE_ENV === 'production') {
  const awsServerlessExpress = require('aws-serverless-express')

  const binaryMimeTypes = [
    'application/octet-stream',
    'font/eot',
    'font/opentype',
    'font/otf',
    'image/jpeg',
    'image/png',
    'image/svg+xml',
  ]
  const server = awsServerlessExpress.createServer(app, null, binaryMimeTypes)

  handler = (event, context, callback) => {
    awsServerlessExpress.proxy(server, event, context)
  }
} else {
  const http = require('http')

  const server = http.createServer(app)

  let currentApp = app

  server.listen(process.env.PORT || 3000, error => {
    if (error) {
      console.log(error)
    }

    console.log('🚀 started')
  })

  if (module.hot) {
    console.log('✅  Server-side HMR Enabled!')

    module.hot.accept('./server', () => {
      console.log('🔁  HMR Reloading `./server`...')
      server.removeListener('request', currentApp)
      const newApp = require('./server').default
      server.on('request', newApp)
      currentApp = newApp
    })
  }
}

What we've done here is dynamically import aws-serverless-express, as well as the http module. This allows us to run the same file for both production, and developing locally.

Lastly on the React code side of things, we'll need to edit src/app.js, and remove the exact keyword from line 9, such that it reads:

    <Route path="/" component={Home} />

(this is a requirement to have React function in AWS API Gateway correctly)

At this point, we can step back, write some terraform files to build our infrastructure, and eventually bask in the awesome fact that you've set up server-less server-side rendering in React.

1. Create an infrastructure folder and enter it: mkdir infrastructure && cd infrastructure

2. Create a main.tf file, containing:

   provider "aws" {
     region = "${var.aws_region}"
   }
   

3. Create a vars.tf file, containing:

   variable "name" { default = "my-app" } #name of your service
   variable "aws_region" { default = "ap-southeast-2" } #ch
   variable "comment" {default = "my-app resource - generated by maxrozen.com/2018/08/08/start-your-own-internet-business-with-react-part-1"}
   variable "bucket_site" {default = "my-app-12345"} # IMPORTANT - set your own app name here!
   output "API Gateway URL" {
     value = "${aws_api_gateway_deployment.ssr_deployment.invoke_url}"
   }
   output "S3_BUCKET" {
     value = "${aws_s3_bucket.site.bucket_domain_name}"
   }
   

4. Create a lambda.tf file, containing:

   resource "aws_iam_role" "lambda_iam" {
     name = "lambda_iam_${var.name}"
   
     assume_role_policy = <<EOF
   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Action": "sts:AssumeRole",
         "Principal": {
           "Service": "lambda.amazonaws.com"
         },
         "Effect": "Allow"
       }
     ]
   }
   EOF
   }
   
   resource "aws_lambda_function" "lambda" {
     function_name = "lambda_${var.name}"
     role             = "${aws_iam_role.lambda_iam.arn}"
     handler       = "server.handler"
     runtime       = "nodejs8.10"
     timeout       = "300"
     memory_size   = "256" #MB. in production, this can be up to 3GB
   
     filename = "../build/server.zip"
     source_code_hash = "${base64sha256(file("../build/server.zip"))}"
   
     tags {
       Project = "${var.name}"
     }
   }
   
   resource "aws_lambda_permission" "allow_api_to_exec_lambda" {
     statement_id  = "allow_api_to_exec_lambda"
     action        = "lambda:InvokeFunction"
     function_name = "${aws_lambda_function.lambda.function_name}"
     principal     = "apigateway.amazonaws.com"
     # The /*/*/* part allows invocation from any stage, method and resource path
     # within API Gateway REST API.
     source_arn = "${aws_api_gateway_rest_api.ssr.execution_arn}/*/*/*"
   
   }
   

5. Create an api_gateway.tf file, containing:

   resource "aws_api_gateway_rest_api" "ssr" {
     name        = "${var.name}_ssr"
     description = "${var.comment}"
   }
   
   resource "aws_api_gateway_resource" "proxy" {
     rest_api_id = "${aws_api_gateway_rest_api.ssr.id}"
     parent_id   = "${aws_api_gateway_rest_api.ssr.root_resource_id}"
     path_part   = "{proxy+}"
   }
   
   resource "aws_api_gateway_method" "proxy" {
     rest_api_id   = "${aws_api_gateway_rest_api.ssr.id}"
     resource_id   = "${aws_api_gateway_resource.proxy.id}"
     http_method   = "ANY"
     authorization = "NONE"
   }
   
   resource "aws_api_gateway_integration" "lambda" {
     rest_api_id = "${aws_api_gateway_rest_api.ssr.id}"
     resource_id = "${aws_api_gateway_method.proxy.resource_id}"
     http_method = "${aws_api_gateway_method.proxy.http_method}"
   
     integration_http_method = "POST"
     type                    = "AWS_PROXY"
     uri                     = "${aws_lambda_function.lambda.invoke_arn}"
   }
   
   resource "aws_api_gateway_method" "proxy_root" {
     rest_api_id   = "${aws_api_gateway_rest_api.ssr.id}"
     resource_id   = "${aws_api_gateway_rest_api.ssr.root_resource_id}"
     http_method   = "ANY"
     authorization = "NONE"
   }
   
   resource "aws_api_gateway_integration" "lambda_root" {
     rest_api_id = "${aws_api_gateway_rest_api.ssr.id}"
     resource_id = "${aws_api_gateway_method.proxy_root.resource_id}"
     http_method = "${aws_api_gateway_method.proxy_root.http_method}"
   
     integration_http_method = "POST"
     type                    = "AWS_PROXY"
     uri                     = "${aws_lambda_function.lambda.invoke_arn}"
   }
   
   resource "aws_api_gateway_deployment" "ssr_deployment" {
     depends_on = [
       "aws_api_gateway_integration.lambda",
       "aws_api_gateway_integration.lambda_root",
     ]
   
     rest_api_id = "${aws_api_gateway_rest_api.ssr.id}"
     stage_name  = "prod"
   }
   

6. Finally, create an s3.tf file to store your static content, containing:

   resource "aws_s3_bucket" "site" {
       bucket = "${var.bucket_site}"
       acl = "public-read"
       website {
           index_document = "index.html"
           error_document = "404.html"
       }
       tags {
         Project = "${var.name}"
       }
       cors_rule {
         allowed_headers = ["*"]
         allowed_methods = ["GET"]
         allowed_origins = ["https://${aws_api_gateway_deployment.ssr_deployment.rest_api_id}.execute-api.${var.aws_region}.amazonaws.com"]
         expose_headers  = ["ETag"]
         max_age_seconds = 3000
       }
       force_destroy = true
       policy = <<EOF
   {
           "Id": "bucket_policy_site",
           "Version": "2012-10-17",
           "Statement": [
             {
               "Sid": "bucket_policy_site_main",
               "Action": [
                 "s3:GetObject"
               ],
               "Effect": "Allow",
               "Resource": "arn:aws:s3:::${var.bucket_site}/*",
               "Principal": "*"
             }
           ]
         }
   EOF
   }
   

If you've made it this far, I'm genuinely impressed. You now have terraform ready to go and deploy your infrastructure.

We do this by entering the infrastructure/ directory, and running terraform apply. Terraform will then list all of the changes it's about to make, and then at the end, will say:

Plan: 11 to add, 0 to change, 0 to destroy.
Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

Type yes if and only if terraform states 0 to destroy. I will not be liable for the destruction of your production AWS resources.

Terraform will take a couple of minutes to create all the resources we specified, and eventually will output:

Apply complete! Resources: 11 added, 0 changed, 0 destroyed.

Outputs:

API Gateway URL = https://hfytoyl60m.execute-api.ap-southeast-2.amazonaws.com/prod
S3_BUCKET = my-app-12345.s3.amazonaws.com

To actually deploy this I manually edited my package.json file, and replaced the "build" key, with:

"build":
      "PUBLIC_PATH=https://my-app-12345.s3-ap-southeast-2.amazonaws.com/public/ razzle build && aws s3 sync \"./build/public/\" s3://my-app-12345/public && aws s3 sync \"./build/static/\" s3://my-app-12345/static && cd ./build && zip -r ./server.zip ./server.*",

This sets the PUBLIC_PATH (the static files like css/js) to point to the S3 bucket we created. Yours will be different. Take particular notice of the s3-ap-southeast-2 portion of the URL, as I doubt you'll also be setting your region to Sydney, Australia.

This concludes Part 1: Server-side Rendering, Serverlessly.

Check https://maxrozen.com for future updates!

The first time I worked through deploying a server-side rendered React app to AWS Lambda, it took me about 5 hours of messing around with my Terraform config, and actual server-side code before I figured out what was wrong (My terraform config was for a outputting JSON from my API Gateway, rather than HTML).

While the easiest way to get started with server-side rendering in React is to start your project with it in mind, I realise for 95% of people this is not an option.

So, you have two options that will save you HOURS figuring out how to setup babel and webpack to play nicely together.

Either:

Use Next.js.

Next.js solves server-side rendering of React applications with a framework approach. Similar to using Gatsby. If you have a site with content that you want indexed on search engines, and you're fine with learning a new framework, then you probably want to look into Next.js

OR

Use Razzle.

It's basically Create-React-App, for server-side rendered Javascript.

It has an extensive list of examples including: AfterJS, Elm, Firebase Functions, Inferno, JSX, Material-UI, Koa, Preact, React Native Web, Redux, Styled Components and TypeScript.

Once you've seen some Razzle examples, and added Razzle to your project (or just created a fresh Razzle project and copied all of your components into it), you're ready for the next steps.

Usually all you need to do is render some React components, and inject them as Strings into a HTML template. Easier said than done, but if you take baby steps (for example, start with rendering your CSS) you'll find it much more achievable than attempting to refactor your entire Application to be Server-side rendered in one go (See Indispensible resources below for the resources I used).

Step 1: Refactor all of your CSS-modules into CSS-in-JS.

Using either Emotion or Styled-Components. You should avoid global CSS if you're using Material-UI, though Styled-Components/Emotion are more forgiving if you modify existing components via global CSS.

Step 2: Refactor your Redux.

In my case I only needed to call createStore on the server like this:

import { createStore, applyMiddleware } from 'redux';
import thunkMiddleware from 'redux-thunk';

import reducer from './reducers';

export default (initialState) =>
  createStore(reducer, initialState, applyMiddleware(thunkMiddleware));

Where the reducer was my client-side reducer code. See this link for further info.

Step 3: Add Apollo/GraphQL

The trick to making this work in my case was adding ssrForceFetchDelay: 100 to my Apollo Client (This prevents Apollo from refetching GraphQL queries after the server already fetches them). Follow the tips at Resource [2] below.

Step 4: Deploying a bundle without having to copy your node_modules/ folder into your AWS Lambda function

This one was surprisingly easy, and at the time not particularly well documented: Create a razzle.config.js file with the following contents:

module.exports = {
  modify: (config, { target, dev }, webpack) => {
    // do something to config
    const appConfig = config; // stay immutable here

    if (target === 'node' && !dev) {
      appConfig.externals = [];
    }

    return appConfig;
  },
};

Razzle by default will use nodeExternals to prevent webpack from bundling your node_modules - which you need for AWS Lambda. This fixes that issue.

Indispensable resources:

1. Getting started: https://medium.freecodecamp.org/demystifying-reacts-server-side-render-de335d408fe4
2. Adding Apollo/GraphQL: https://dev-blog.apollodata.com/how-server-side-rendering-works-with-react-apollo-20f31b0c7348
3. Adding Styled-Components: https://www.styled-components.com/docs/advanced#server-side-rendering
4. Adding Material-UI https://material-ui.com/guides/server-rendering/

The inspiration for this post comes from this closed issue in babel-plugin-inline-import (https://github.com/Quadric/babel-plugin-inline-import/issues/1) a plugin that my company uses in almost all of our projects.

Essentially, the issue is that you'll run your npm run dev script, decide to modify your resolvers, or your schema, re-run the script to get your resolvers, and boom:

'Query.X defined in resolvers, but not in schema'

The root cause here is that the babel-plugin-inline-import plugin caches your schema.

The resolution is essentially to have BABEL_DISABLE_CACHE=1 in your .env, and to have two separate webpack files, one for your graphql API, and another for your client.

In my graphql webpack config I have the following:

module: {
    rules: [
      {
        test: /\.js$/,
        include: path.resolve(__dirname, '..'),
        exclude: path.resolve(__dirname, '..', 'node_modules'),
        loader: 'babel-loader'
      },
      {
        test: /\.graphql$/,
        include: path.resolve(__dirname, '..'),
        exclude: path.resolve(__dirname, '..', 'node_modules'),
        loader: 'graphql-tag/loader'
      }
    ]
  }

Which will include my graphql schema inline (which I keep in my project root)

For customisable dropdowns, react-select is one of the most popular select dropdown pickers in Github.

In terms of CSS-in-JS solutions, styled-components and emotion are often the first options developers consider. They use the same API, which makes it a breeze to swap between the two.

How to use react-select and styled-components together:

import React from "react";
import ReactSelect from "react-select";
import styled from 'styled-components';

const MultiSelect = styled(ReactSelect)`
	&.Select--multi  {

		.Select-value {
			display: inline-flex;
			align-items: center;
		}
	}

	& .Select-placeholder {
		font-size: smaller;
	}
`

export (props) => <MultiSelect multi {...props} />

How to use react-select and emotion together:

import React from "react";
import ReactSelect from "react-select";
import styled from 'emotion';

const MultiSelect = styled(ReactSelect)`
	&.Select--multi  {

		.Select-value {
			display: inline-flex;
			align-items: center;
		}
	}

	& .Select-placeholder {
		font-size: smaller;
	}
`

export (props) => <MultiSelect multi {...props} />

It's really that easy to go between the two libraries.

You can also do the exact same thing with react-dates saving you from having those pesky global.css files several thousand lines long.