DEV Community: Corbin Crutchley

Merging the "This Is" Community into "Playful Programming"

Corbin Crutchley — Mon, 09 Feb 2026 11:50:04 +0000

Today marks a major milestone for open-source education: "This is Learning" and "Playful Programming" are joining forces. We are bringing two communities together to reinforce our shared goal of transparent, accessible developer education.

Let's introduce each community and explain what this means for both communities.

Introducing "This is Learning" (TiL)

"This is Learning" (TiL) was originally created in 2020 by Santosh Yadav and Lars Gyrup Brink Nielsen to bring together authors and share software development knowledge.

Santosh and Lars are both highly accomplished engineers and community leaders. Both receiving multi-year awards from prestigious organizations like GitHub, Microsoft, Google, and Nx for their efforts on "This is" as well as many other open-source projects.

It's no wonder, then, that since they started their project they've:

As we migrate these resources to "Playful Programming" branding and our main website, these links may break over time. We will leave them as-is for historical context.

Throughout it all, they always remained strictly "not for profit" and encouraged cross-posting, self-controlled content ownership, and community wellbeing over all else.

Introducing "Playful Programming" (PFP)

"Playful Programming" (PFP) was started by James Fenn, Evelyn Hathaway, and myself (Corbin Crutchley) in 2019.

Playful Programming (originally called "Unicorn Utterances") started as an alternative to a bootcamp that I worked in that I felt was acting predatory to the students in my area. Knowing that James and Evelyn were all-star engineers, I asked for their help to propel our mission — of teaching others in a transparent and helpful way — forward.

More history:

Want to learn more about Playful Programming's origins? When we rebranded from "Unicorn Utterances" we wrote a historical article on our project that you can read on our site.

Since then, we as a community have:

That last item is one I'm particularly proud of. It continually reminds (and enforces) our goals to keep our content accessible and driven towards the community; not towards profits.

Details about the merger

As both organizations have scaled, we've faced different challenges:

For TiL, they've remained focused on the content. This has meant that they have a strong repertoire of content, but have focused less on other avenues of growth.
Contrarily, PFP has developed a powerful brand, a "uniquely ours" website, and a larger community in our Discord. We're proud of what we've put out, but it does mean that our content catalog is comparatively weak.

After some discussion between Lars, Santosh, and myself, we realized that we'd be able to grow a substantially healthier community with a joint effort.

As such, we will be doing the following going forward:

Retain Playful Programming's name, branding, and structure
Keeping our board of directors as-is
Rename This is Learning's Dev.to blog to "Playful Programming" and their Angular specific blog to "Playful Programming Angular"
Continuing to run the "This is Tech Talks" podcast under Playful Programming
Reposting authors of This is Learning's existing content to opt-into reposting their content to the Playful Programming website

Again, it's that last point that we've spent a considerable amount of time enabling. Twenty TiL authors agreed for us to port hundreds of their posts to our site. This required us to develop many new features for our site, but has resulted in our site having 750+ articles present today!

A note for TiL contributors:

While we've done our best to reach out to all existing contributors to TiL, we acknowledge that it's tough to keep up-to-date with every community we find ourselves in.

As such, if you'd like to have your contents on our site or have feedback regarding this change, reach out to me on any of my social media channels and I'll help migrate your content or address concerns you might have.

Regardless of if you'd like your content reposted onto our site, your Dev.to content will remain fully in-tact and all links to existing content should redirect on Dev.to's site.

Our future

But this isn't all we have planned! We also intend on:

Migrating TiL's RxJS and NgRx courses into Playful Programming's collections feature
Creating topic-specific pages to explore content of (like "This is Angular" provided for the broader "This is Learning" community)
Building out integrations with social media feeds to automatically promote authors' works

With this influx of new content and authors, we want to improve the writing experience. One concern we've heard from authors is challenges with posting to Playful's site. Today, writing a post for our site includes making a pull request to our GitHub repo. While we've tried to reduce friction with that process as much as we can, we know that writing for Dev.to using a GUI is much easier to navigate.

As such, we're working incredibly hard on building out a custom CMS for our site. Here's a small mockup preview of such:

Why build out a custom CMS?

While there's a long and well-researched answer to that question, the long-story short is that we haven't found a CMS that allows our content to be stored in a Git repository with the features we want to support in the long run.

Why do you want to store content in Git?

The biggest reason for wanting to store authors' contents in Git is that it's a systemic answer to our goals of remaining maximally transparent. If our values are ever mismatched from authors', we want an easy way for authors to take their whole dataset with them without needing to access an account or API token.

And while radical transparency is our primary motivator, creating our own CMS allows us to add features in the future like:

Cross-posting to Dev.to instantly
Social media feed promotion of our authors' material
Additional components that markdown doesn't provide out-of-the-box
Revision history from the editor itself
Multi-player editing

And much more.

Join us:

Sound like a project you might want to help build? Come join us and help us build it out!

Thank you

Neither "This is Learning" nor "Playful Programming" would be where we are today without you; the readers.

We're excited by our next chapter as we continue to serve the community with learning materials. There's still a great deal of work for us to accomplish, but we're driven by the northern star of those that we're able to serve.

We appreciate your continued support and hope to see you in our community.

Until next time,

- Corbin Crutchley, Executive Director of Playful Programming

Challenges in writing a programming book

Corbin Crutchley — Mon, 29 Jul 2024 15:00:00 +0000

Have you ever thought about writing a book about software engineering?

I have. I thought about this idea of a book that would teach you React, Angular, and Vue all at once for years and years.

The idea started as a simple blog post series and, as I learned more about each respective framework, I realized that wouldn't cut it.

Finally something cracked. I had been writing blog posts both professionally and not for a while. I had amassed 50 blog posts in my repertoire and thought "How hard could it be?"

This started my journey to write "The Framework Field Guide", a trilogy of programming books that I'm making free for the general public.

While I've only finished one of the books thus far, I want to share with you my learnings around this time.

Writing a book is hard

It took me a little over two years to:

Start writing a book
Realize it was getting too long, even in rough sketches of headings
Re-organize existing content and outline enough rough content to fill a trilogy of books
Develop a high-performance custom-designed marketing site
Redesign and rewrite an entire blogging platform to host the book's contents on

Write the first book
- 95K words
- 16 chapters
Create code samples & embeds for every code block in the book
- 25K lines of code
Do grammar and spelling edits to the book's contents

All while maintaining my day job's duties of leading a software engineering team.

What's more; book sales are rough. While I'm not charging for my content, I've regularly heard from other authors that writing content is challenging to break even with your time spent. Consider your salary, now consider how much time it'd take to do everything I just listed. Are you willing to take home (potentially) a lot less than you might by doing consulting?

Moreover, how are you going to price things? Price too low (like I have) and people tend to devalue your work (even subconsciously). Price too high and your work is inaccessible to many.

All-in-all, you have to:

Be willing to write for yourself
Stay resilient and know that the outcome will be immensely rewarding

Developers glance, not read

This article is going to lose a lot of readers. Why? Well, during my past five years writing for developers I've learned that the content that has the best engagement has:

A shorter in length
Content broken up by images
Bolded and italicized formatting
Lists to break up formatting even further
The article filled with code

You generally want your article to more like this:

And less like this:

Notice how boring this screenshot looks? Nobody's reading all of that. Break it up with formatting, images, emoji - anything to spice it up!

Keep your headings clearly named

As I mentioned previously, most developers will only glance at your articles. If your headings aren't representative of what they'll be learning underneath them, they'll likely gloss over their content.

It may be tempting to have fun headings like this:

Try instead to be more explicit with what's being talked about:

Code will be copy+pasted

Assume your article or book includes JavaScript code that demonstrates some broken code like so:

const test = = 123;

This might be an obvious error to us, it might not be so clear for a newcomer developer.

Instead of this code block on its own, try to annotate it using comments inside the code block itself:

// This is broken code, remove the second `=` to fix it
const test = = 123;

Lean into copy+pasted code; it's how many developers will learn. Force them to tweak code themselves to see the results they want - it encourages learning and interactivity!

Developers seem to prefer video content

You might ask yourself on your journey if a pre-recorded video content is worthwhile making. While editing can be lengthy and recording can be intimidating, the return on investment (ROI) for video content appears to be higher for developers in my experience.

Compare and contrast a reasonably successful article of mine:

To the meteoric rise of, say, Theo over on YouTube:

For what it's worth, I don't recommend investing very heavily in live-streaming on Twitch or YouTube. I've written about this before, but my 1K+ hours on the platform has yielded minimal ROI.

Conclusion

Making content of any kind can be a grueling task. If you choose to write a book about software engineering, you can expect to pour hours and hours into the writing process.

But if you pull it off, you'll have an improved resume, bragging rights, and have likely helped someone along the way learn valuable skills in their career.

There's more to share, which I'll include in a future series, but that's all for now.

And hey, if you wouldn't mind - I'd love you to take a look and share my book, "The Framework Field Guide":

It's free and teaches multiple frameworks at once. Thanks a bunch!

Advice for New Twitch Streamers

Corbin Crutchley — Tue, 23 Jul 2024 09:48:35 +0000

You've spent hours in your favorite streamer's chat. You've gotten to see all the critical moments of their streams live, joined in on community jokes, and even memorized their emote names.

One day, it hits you; If you're having this much fun in someone else's stream, maybe you should give Twitch streaming a shot.

What do you need to know to get started? If only someone could give you advice on what you need to know to make the most of your streaming time.

My name's Corbin and I go by @crutchcorn on Twitch, and I've been there too. After over 1,000 hours of streaming, I've learned a few things that I wish I knew when I first started. Here are a few of the key takeaways:

Streaming Strategy
Essential Equipment
Culminating Community
Managing Moderation
Generating Growth
Branded Broadcasts

Let's go through these items one-by-one and create a solid strategy for our future streams.

Streaming Strategy

Streaming is unlike any other content creation medium. Unlike blog posting, it's multi-faceted and has audio and video. Unlike a YouTube video, it's live. Unlike live TV, it's interactive.

It's these differences that require a different approach to streaming than other content mediums. Here's a few things to keep in mind:

Be yourself; you're not at a job interview.

Livestreaming is meant to be more natural and personal than prerecorded videos or even a live presentation/talk. You can be a bit (or a lot, depending on your comfort level) more casual than you might otherwise. Similarly, verbal slip-ups and hiccups are 10000% expected, especially early on. Just like any other skill, you will improve. ✨
Interact with chat! People watch live content in particular because it's live.

They want to hear your thoughts and opinions on things, they want to have a two-way conversation and have real-time interaction with a person/personality. Remember, most people watch a streamer for their personality - they can't see much of that personality if you're not interacting with your viewers.
Be honest with yourself and your chat - they will be understanding.

If you're streaming programming content, but aren't yet a master at the language you're writing in - tell chat! It's okay to be a bit vulnerable in that way. By being up front with your community, you're able to set the tone of supportiveness and kindness that you'll want to culminate as you grow. Similarly, if you're speed-running a game but aren't towards the top of the leaderboard, maybe show your P.B. on screen so your community can celebrate new P.Bs with you!
Set your boundaries with your community.

While a bit of vulnerability can go a long way to making a safe community, there will always be trolls. However, remember that you have the center stage, not chat; Utilize this to flow your community towards the tone/attitude you want to see in them. Don't want advice on the puzzle game you're playing - make "no back-seating" part of your channel rules and enforce them with your mods. Everyone will want to establish their communities differently - follow your goals.
Ask your friends to tune into early streams!

It's fun, gives you someone to chat with early on when you might otherwise have few/no other viewers, and encourages you to practice how to engage the broader community.

Essential Equipment

While it's always fun to buy new toys for a new hobby, I have some guidance that pertains specifically to streaming:

Don't worry about gear early on.

You don't need a DSLR, green screen, or fancy audio equipment to make good content early on. Start with a cheap microphone, see if you enjoy it, then move on to better gear. If you do want to get better gear, start with audio equipment; it tends to pay the best dividends and is a less messy world than live video quality improvements.
Don't force a facecam.

If you enjoy having a facecam and think it adds production quality you yearn for, add it! But don't feel it's an obligation; you're able to get by perfectly fine without facecam. Even big content creators can go without (see also: GameGrumps, Corpse Husband, and others).
Create a unique and relevant set of branding.

Whether it be overlay customization, Twitch panel graphics, sound effects, emotes, or anything in between - make it yours and make it consistent. Starting out? Don't just use a default unmodified theme. Take a pre-made asset pack and hodgepodge it until it's unique to your brand. Growing and ready to level-up? Hire artists to make something expressly yours - there's hoards of talented creatives that want to work with you.
Avoid spending too much time on your branding.

While we just touched on how unique branding can be a boon to your channel, it can also be a massive time sink. While meta-stream customization (updating your overlay while live) can be loads of fun, they don't tend to have good viewer retension.

In particular, if you're a programmer I generally advise not working on your own overlay unless you have really cool and unique integration ideas. Even if you do, see if they can't be accomplished with StreamElements or custom OBS plugins instead of hand-rolling your own systems from scratch.

Culminating Community

When streaming on Twitch, you're likely to run into unfamiliar terminology that is helpful to know when on the platform. Here are just a few:

Raids: When someone is done with their stream, they can keep the party train going onto someone else's stream.

They're able to "raid" another channel and move all of their live viewers to another channel. They can be as small as 1 viewer to a huge stream with dozens, or even hundreds of viewers.

Bits: A small-sized donation.

Bits are a way to donate to a streamer. Usually, 1 bit is ~$0.10 USD. They can be redeemed to send a highlighted message that your overlay can do special things with (if configured).

Subscriptions: A larger donation with more rewards.

A subscription (or "sub") is a way for someone to donate to your channel every month. There are three different types of subs:

Tier 1: ~$5 USD - Unlock the first set of streamer-specific emotes
Tier 2: ~$10 USD - Unlock the second set of streamer-specific emotes
Tier 3: ~$15 USD - Unlock the third set of streamer-specific emotes

Keep in mind, while you can be raided before becoming an affiliate - you can only get donations through bits and subs by becoming an official affiliate of Twitch. You become an affiliate by reaching certain viewership goals.

Similarly, there are a few global Twitch Emotes that you may want to know ahead of time:

Emote	Name	Description
	`PogChamp`	OMG I can't believe you've managed to pull that off! (Chat is excited)
	`LUL`	A laughing face to express just how funny that "Why did the chicken cross the road" joke was.
	`Kappa`	An emote meant to represent sarcasm or a joke of some kind.
	`NotLikeThis`	I can't believe this has happened. (Chat is jokingly upset by something going on)
	`HeyGuys`	A way to say "Hi" to chat for the first time
	`Kreygasm`	That feeling when you get a 360 no-scope (Chat found something satisfying)
	`WutFace`	What did you just say?! (Chat is confused or upset by what you said)
	`BOP`	A hammer to bonk you with for being silly. (or some other emotion...)
	`BibleThump`	The face says it all; what you said was sad.
	`CoolStoryBob`	Cool story, can you tell it again? (chat doesn't believe you)

In case this isn't enough here are a few other emotes, introduced by Twitch themselves.

Managing Moderation

While streaming can be fun and relaxing at times, there are potential downsides as well. Just like any other platform, Twitch has its fair share of trolls that need to be cut from the stream when they engage.

To help solve this, here's a few tips to follow:

Establish a mod team of friends or frequent chatters that you can trust early on.

They're not only a lifesaver for the instances where you need moderation, but also greatly help with your moral to keep streaming and can encourage chat to stay in the boundaries you've set, even in subtle ways.
Prepare for potential hate raids or follow-botting.

While Twitch has gotten better at filtering out these kinds of negative interactions, it never hurts to be familiar with what tools you have at your disposal ahead-of-time. Just to name a few, Twitch has its built in "Shield" functionality, but there are community efforts like Sery_Bot as well.

Be on guard for your digital security.

Remember, there are bad actors all over the internet. While most links shared with you might be authentic, don't click on any unfamiliar links coming from your chat. This helps prevent hacking or phishing attempts.

Manage your on-stream privacy to avoid accidental self-doxing.

Doxing is when someone shares personal information about another person. However, there are times when you might accidentally dox yourself. To prevent this, use a separate browser from your daily-driver so that you don't accidentally share DMs, location, or other information about yourself. Further, if you're streaming on Windows, make your non-streaming monitor your "primary" monitor, so that new windows, dialog boxes, and notifications don't automatically show on-screen accidentally.

Generating Growth

While not top of mind for everyone, some streamers want to grow their streams to have as many viewers as possible. To help grow your brand, consider:

Schedule consistency is key.

Especially early on in your streams, keep a schedule that you follow religiously. For example, you might try streaming on "Tuesdays and Thursdays at 4PM PST". This will help propel your audience's ability to keep up and catch your content regularly.

Stay on brand with your categories.

While a bit of variety can be good for some streamers, it's generally advised to stay away from multi-focusing your channel's categories. Variety streamers have a much more challenging time trying to garner their foothold. Not only is it harder to make connections in a niche (both with other streamers and viewers alike), but the recommendation algorithm seems to punish you harshly for jumping categories frequently.

Network with fellow streamers.

Like other parts of brand growth, networking is absolutely critical in streamer brand growth. I'd say that 30-40% of your time on Twitch should be as a viewer of other people in your niche. Get to know them; follow them on other social media and make friends. Raids grow the channel significantly faster than organic growth.

Set your expectations realistically.

Becoming a Twitch affiliate is feasible within the first couple of months or first year of streaming, but becoming a Twitch Partner is exceedingly challenging to reach. Especially if your niche is small like mine; in the programming category there are maybe 20-30 partners in the entire category across all languages and regions. Even big brands with a specific investment in Twitch have a hard time breaking into partner.

Recognize the relevant metrics.

While followers are nice to have as a vanity metric, they seldomly represent the health of a channel. I know some partner channels with low thousand followers while some channels have over 10,000 followers and aren't even close to partner. The most relevant metric to see a channel's size is average viewership.

"A body in motion stays in motion."

If you're on an upswing of viewership, add gas to the fire by streaming more regularly/often immediately following. The Twitch recommendation algorithm is a fickle beast, but in my experience absolutely rewards those that are already doing well. Similarly, if you let your viewership drop for a short time, it may take some time growing it back to baseline.

Diversify your audience.

While having a primary audience on Twitch is great, Twitch's notification system may fail to inform your users when you go live. Furthermore, being able to culminate a community outside of Twitch allows your viewers to become more personable with you, which may keep their interest in the channel for longer. Try promoting a Discord or a personal Twitter account to help others stay up-to-date and keep the conversation going with you.

Branded Broadcasts

While this guide has primarily been geared towards individuals looking to become Twitch streamers, I've also had some experience trying to break into the streaming world as a cooperate brand.

Here are my learnings from this time:

I generally do not recommend streaming to almost anyone looking to grow their corporate brand/audience.

The first ~600 hours of personal streaming were exceedingly tough to grow. Not only are you getting used to this awkward new environment, but you have very little traffic to your branded site or content and those that do show up can be a bit dismissive of a brand in a personality-driven environment.

Streaming has among the lowest ROI of any content-creation adjacent activities I've ever done.

Keep in mind that streaming is a huge time investment where your first major hurdle is to grow an audience. From my experience, I found it easier to grow the company's ROI by blogging, attending meetups, or otherwise pre-recording video.

If you get into streaming - I'd generally advice it be seen as an extremely long-term investment and/or an easy content generation method while multi-tasking and doing other things; don't make it your core KPI to grow on streaming platforms.

Conclusion

While I could continue this guide for almost forever, this is a good stopping point for the guidance I'm hoping to provide for others looking to get into streaming.

Hopefully this has been an insightful look into how Twitch streamers can grow and improve their own streams.

Until next time, I hope your streaming career goes well!

How Binary and Hexadecimal Work: An introduction to non-decimal number systems

Corbin Crutchley — Sat, 16 Mar 2024 15:00:00 +0000

Computers, on a very low level, are built upon binary (ones and zeros). Think about that — all of the text you're reading on your screen started life as either a one or a zero in some form. That's incredible! How can it turn something so simple into a sprawling sheet of characters that you can read on your device? Let's find out together!

Decimal

When you or I count, we typically use 10 numbers in some variation of combination to do so: 0, 1, 2, 3, 4, 5, 6, 7, 8, and 9.

When you count to 10, you're really using a combination of 1 and 0 in order to construct a larger number that we cognizantly recognize. The number 10 persists in our minds even when we have it written out; ten.

Knowing that we can separate the number from our thoughts allows us to further categorize the number, mentally breaking it down into smaller groupings. For example, the number 34 can be broken down into three groups: the ones, the tens, and the hundreds.

For the number 34, we break it down into: 0 hundreds, 3 tens, and 4 ones. We can then multiply the higher number with the lower number (the column they're in) to get the numbers 30 (3 tens) and 4 (4 ones). Finally, we add them all together to make the number we all know and love: 34.

This breakdown showcases a limitation with having 10 symbols to represent numbers; with only a single column, the highest number we can represent is 9.
Remember that the number 10 is a combination of 1 and 0? That's due to this limitation. Likewise - with two columns - the highest number we can represent is 99.

Binary

Now this may seem rather simplistic, but it's an important distinction to be made to understand binary. Our typical decimal numeral system is known as the base 10 system. It's called as such because there are 10 symbols used to construct all other numbers (once again, that's: 0, 1, 2, 3, 4, 5, 6, 7, 8, and 9).
Binary, on the other hand, is base two. This means that there are only two symbols that exist in this numeral system.

For the Latin enthusiasts, binary comes from "binarius" meaning "two together". Deca, meaning 10, is where "decimal" comes from.
Additionally, the term "radix" is sometimes used instead of "base" when describing numeral systems, especially in programming.

Instead of using numbers, which can get very confusing very quickly while learning for the first time, let's use X's and O's as our two symbols for our first few examples. An X represents if a number is present and that we should add it to the final sum; an O means that the number is not present and that we should not add it.
Take the following example:

In this example, both 1 and 2 are present, so we add them together to make 3. You'll see that since we can only have a value present or not present — because we only have two symbols in binary — this conversion has fewer steps than using decimal. For example, if you only wanted the number two, you could simply mark the 1 as "not present" using the O:

You can even replace the two symbols with 1 and 0 to get the actual binary number of 10 in order to represent 2:

So, how does this play out when trying to represent the number 50 in binary?

As you can see, we create columns that are powers of 2 for similar reasons as using powers of 10 in decimal; you can't represent 4, 8, 16, or 32 without creating a new column otherwise.

Remember, in this system, a number can only be present or not; there is no 2. This means that only the symbols 1 and 0 are present. Keeping this in mind, it then means that we can only have 11 as the highest represented number without another column. 11 in binary is 3 in decimal. This shows that with only 2 binary digits, only the decimal numbers that can be represented are: 0, 1, 2, and 3. As a result, we need to add a 4 column in order to represent that number in binary.

Continuing on with this pattern: without an 8 column, you can only have a 4, 2, and 1 which would yield a maximum value of 7. It's important to note that these values are always one less than a power of 2.

Once each of these powers is laid out, we can start adding 1s where we have the minimum amount of each value. For example:

Is 64 less than or equal to 50? No. That's a 0.
Is 32 <= 50? Yes, therefore that's a 1.
- 50 - 32 = 18
Moving down the list, is 16 <= 18? Yes, that's a 1. -18 - 16 = 2
Is 8 <= 2? No, that's a 0.
4 <= 2? No, that's a 0 as well.
2 <= 2? Yes, that's a 1.
- 2 - 2 = 0
Now that we're left with 0, we know that the rest of the digits will be 0.

Add up all those numbers:

Column	Value
`64`	`0`
`32`	`1`
`16`	`1`
`8`	`0`
`4`	`0`
`2`	`1`
`1`	`0`

And voilà, you have the binary representation of 50: 0110010.

Author's note:

While there are plenty of ways to find the binary representation of a decimal number, this example uses a "greedy" algorithm. I find this algorithm to flow the best with learning the binary number system, but it's not the only way (or even the best way, oftentimes).

Hexadecimal

Binary isn't the only non-decimal system. You're able to use any number as your base as long as you have enough symbols to represent the digits. Let's look at another example of a non-decimal system: hexadecimal.

Hexadecimal is the base 16 number system.

Hexa means "six" in Latin, and deca means "ten", so these are combined to form "sixteen".

Now you may wonder how you can count to 16 in a single column when we only use 10 symbols to represent numbers. The answer, to many developers, is to fill the remaining last 6 with other symbols: alphabetical letters.

0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, E, F

These are the symbols that make up the hexadecimal numeral system for many developers. A, in this case, represents the number 10; F represents the number 15. In this numeral system, there are the sixteens, the two-hundred fifty sixes (gathered by multiplying 16 by itself — 16²), and other powers of 16.

Given this information, how would we represent the number 50?

Assuming we have a ones column, a sixteens column, and a two-hundred fifty sixes column, we can calculate the number in a similar way to the binary example earlier:

Is 256 less than or equal to 50? No. That's a 0
Is 16 <= 50? Yes. So we know it's at least 1.
- Now, how many times can you put 16 in 50?
  - 16 * 2 = 32 and 32 <= 50, so it's at least 2.
  - 16 * 3 = 48 and 48 <= 50 so it's at least 3.
  - 16 * 4 = 64. However, 64 > 50, therefor the sixteenth place cannot be 4, therefore it must be 3.
- Now that we know the most we can have in the sixteenth place, we can subtract the sum (48) from our result (50).
  - 50 - 48 = 2
Now onto the ones place: how many ones can fit into 2?
- 1 * 1 = 1 and 1 <= 2, so it's at least 1.
- 1 * 2 = 2 and 2 <= 2 and because these numbers are equal, we know that there must be 2 twos.

Now if we add up these numbers:

Column	Value
`256`	`0`
`16`	`3`
`1`	`2`

Why `256`?

While reading through this, you may wonder, "Where did the 256 come from?". Let's take a step back to analyze this question.

If you recall, we use these 15 symbols to represent digits in hexadecimal:

0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, E, F

Using just a single digit (or, phrased in another way: A single number column), the biggest number we can represent is F, or 15 in decimal.

This is similar to how the biggest number we can represent with a single digit in decimal is 9.

In order to add a number larger than 15 in the hexadecimal system, we need to add another digit/column. This column would represent the sixteens place. Having F in both this column and the ones column, the highest number we can represent would be FF, or 255 in decimal. As a result, we need to add a two-hundred-fifty-six column to represent any numbers higher.

For those that have experience in algebra, you'll notice that these are all powers of 16.

Just as 100 is 10² for the decimal system, 256 is 16². We can follow this pattern to the next number in the hexadecimal column: 4096, which is 16³. You can even apply it to 1 which is 16⁰.

Binary works in the same manner. The first 5 columns/digits of binary are: 1, 2, 4, 8, 16. These numbers align respectively to their binary exponents: 2⁰, 2¹, 2², 2³, 2⁴.

It's also worth noting that decimal numbers can be written out the same way.

732 for example, in base 10, can be written as (7 × 10²) + (3 × 10¹) + (2 × 10⁰).

To Binary

Remember that at the end of the day, hexadecimal is just another way to represent a value using a specific set of symbols. Just as we're able to convert from binary to decimal, we can convert from hexadecimal to binary and vice versa.
In binary, the set of symbols is much smaller than in hexadecimal, and as a result, the symbolic representation is longer.

After all, they're just reflections of the numbers that we represent using a specific set of symbols. In binary, those symbols are more restrictive than in hexadecimal, and therefore the symbolic representation is longer.

Applications

CSS Colors

Funnily enough, if you've used a "hex" value in HTML and CSS, you may already be loosely familiar with a similar scenario to what we walked through with the hexadecimal section.

For example, take the color #F33BC6 (a pinkish color). This color is a combination of 3 two-column hexadecimal numbers back-to-back. These numbers are:

F3, 3B, C6

They reflect the amount of red, green, and blue (respectively) in that color. Because these numbers are two-digit hexadecimal numbers, the highest a number can be to reflect one of these colors is 255 (which is FF in hexadecimal).

If you're unfamiliar with how red, green, and blue can combine to make the colors we're familiar with (such as yellow, orange, purple, and much more), it might be worth taking a look at some of the color theory behind it. You can find resources on the topic on Wikipedia and elsewhere.

These numbers, in decimal, are as follows:

Hex	Decimal
`F3`	`243`
`3B`	`59`
`C6`	`196`

And construct the amount of Red, Green, and Blue used to construct that color

Represents	Hex	Decimal
Red	`F3`	`243`
Green	`3B`	`59`
Blue	`C6`	`196`

Even without seeing a visual representation, you can tell that this color likely has a purple hue - since it has a high percentage of red and blue.

Text Encoding

Although hexadecimal has a much more immediately noticeable application with colors, we started this post off with a question: "How does your computer know what letters to display on the screen from only binary?"

The answer to that question is quite complex, but let's answer it in a very simple manner (despite missing a lot of puzzle pieces in a very "draw the owl" kind of way).

Let's take a real way that computers used to (and still do, to some extent) represent letters internally: ASCII. ASCII is an older standard for representing each textual character as a different number inside your computer. Take the following (simplified) chart:

When the user types "This", what the computer interprets (using ASCII) is 84, 104, 105, and 115 for T, h, i, and s, respectively.

You might be wondering, "Why are there a bunch of missing numbers"?

I've removed them to keep the examples simple, but many of them are for symbols (EG: #, /, and more), and some of them are for internal key commands that were used for terminal computing long ago that your computer now does without you noticing.

It's also worth mentioning that ASCII (which does have more characters than what's presented here) was eventually replaced in various applications by Unicode and other text encoding formats as it lacks various functionality we expect of our machines today, such as emoji and non-latin symbols (like Kanji). ASCII still sticks around to some extent though, as the first 255 characters in Unicode are the same as they originally were in ASCII.

While I've used the above chart to reflect A as 65, it'd be more accurate to say that your computer interprets the symbol as 01000001 internally. This is again due to the fact that your computer must interpret every number and letter as binary.

Conclusion

While this has been only a high-level overview of how your computer interprets these non-decimal numbers (and some of their applications), it can provide some basic insights to what your computer is doing every time you make a keystroke or see a color on screen. Under the hood, everything is binary, and now you understand the introduction to how to convert binary to numbers you and I may understand better: to decimal!

TypeScript Intermediates - Type Generics

Corbin Crutchley — Thu, 14 Mar 2024 15:00:00 +0000

While working in various projects, you may come across a weird looking syntax in the codebase: <>. No no, not JSX, we're of course talking about type generics. They'll appear next to function calls (callFn<T>()), TypeScript types (Array<any>), and more.

Type generics are a way to handle abstract types in your function. They act as a variable for types in that they contain information about the way your types will function. They're very powerful in their own right, and their usage is not just restricted to TypeScript. You'll see many of these concepts applied under very similar terminologies in various languages. Enough on that, however. Let's dive into how to use them! 🏊‍

The Problem

Type generics — on the highest level — allow you to accept arbitrary data instead of strict typing, making it possible to broaden a type's scope.

For example, what if you wanted to make a function that took an argument of returnProp and returned the returnProp value itself (the formal name for a function like this is an identity function)? Without type generics, providing a typing for a function like this could be difficult.

Take the following implementation and consider its limitations:

function returnProp(returnProp: string): string {
    return returnProp;
}

returnProp('Test'); // ✅ This is fine
returnProp(4); // ❌ This would fail as `4` is not a string

In this case, we want to make sure that every possible input type is available for the prop type. Let's take a look at a few potential solutions, with their various pros and cons, and see if we can find a solution that fits the requirements for providing typing for a function like this.

Potential Solution 1: Unions

One potential solution to this problem might be TypeScript unions. Unions allow us to define an or condition of sorts for our types. As we want to allow various types for inputs and outputs, perhaps that can help us here!

Using this method, if we wanted to accept numbers, we could add that as a union:

function returnProp(returnProp: string | number): string | number {
    return returnProp;
}

returnProp('Test'); // ✅ This is fine
const shouldBeNumber = returnProp(4); // ✅ This won't show errors now

However, unions have some limitations. You'll find that this doesn't give the example you might want:

// ❌ This will yield an error
// > Operator '+' cannot be applied to types '4' and 'string | number'.
const newNumber = shouldBeNumber + 4;

The reason that the operation shouldBeNumber + 4 yields this error is because you've told TypeScript that shouldBeNumber is either a number or a string by making the output explicitly typed as a union. As a result, TypeScript is unable to do addition between a number and a string (which is one of the potential values) and therefore throws an error.

Potential Solutions Disclaimer

Author's note:

If you were using unions in your property definitions and left your return type blank, TypeScript would be able to infer what the return type should be just fine.

That said, we're trying to build on concepts, so we're trying to provide some examples of where this might be used and what it does. There are also instances, such as type definition files, where this inference might not be available to an author of typings, as well as other limitations with this method that we'll see later.

Potential Solution 2: Function Overloading

In order to get around the issues with explicitly returning a union, you COULD utilize function overloading to provide the proper return typings:

function returnProp(returnProp: number): number;
function returnProp(returnProp: string): string;
// While this seems repetitive, TS requires it.
// Otherwise, it will complain:
// This overload signature is not compatible with its implementation signature.
function returnProp(returnProp: string | number): string | number {
    return returnProp;
}

That said, in addition to having some obnoxious duplicated type information, this method also has its limitations.

For example, if we wanted to pass in an object of some kind (such as {}, a simple empty object), it would be invalid:

returnProp({}) // Argument of type '{}' is not assignable to parameter of type 'string'.

This may seem obvious from the typings, but we ideally want returnProp to accept ANY type because we aren't using any operations that require knowing the type. (no addition or subtraction, requiring a number; no string concatenation that might restrict an object from being passed).

Potential Solution 3: Any

Of course, we could use the any type to force any input and return type. (Goodness knows I've had my fair share of typing frustrations that ended with a few anys in my codebase!)

Although this would allow any input type, we'd also be losing any type information between the input and output. As a result our types would be too loose on the return type:

function returnSelf(returnProp: any): any {
    return returnProp;
}

const returnedObject = returnSelf({objProperty: 12}); // This now works! 🎉

returnedObject.test(); // This will not return an error but should 🙁
returnedObject.objProperty; // This will also (correctly) not throw an error, but TS won't know it's a number ☹️

The Real Solution

So what's the answer? How can we get preserved type data on both the input and the output??

The solution is... Well, you've read the title I'm sure.

Type generics allow us to store loose type data in a type variable. A type variable is a unique kind of variable that's not exposed to JavaScript but is instead handled by TypeScript to provide expected typing data. For example, the above example could be rewritten as:

function returnSelf<T>(returnProp: T): T {
    return returnProp;
}

In this example, we're defining a type variable T, then telling TS that both the property and the return type should be the same type.

This means that you can use the function like this:

const numberVar = returnSelf(2); // T in this instance is `2`, so it's similar to writing `const numberVal: 2 = 2;`

// Likewise, this object is now returned as if it was just placed on the const
const returnedObject = returnSelf({objProperty: 12});

// This will fail, as expected
returnedObject.test();
// This will exist, and TS will know it as a number
returnedObject.objProperty;

Author's note:

The type variable does not need to be called T. In fact, while it seems to be commonplace for the community to use single-letter type variable names (often due to the length and complexity of the typings), there are many reasons why more explicit type names should be used.

Remember, type variables are like other variables in that you need to maintain them and understand what they're doing in your code.

Okay, but Why?

Why might we want to do this? Returning an item as itself in an identity function is cool, but it's not very useful in its current state. That said, there are many, many uses for generics in real-world codebases.

For example, let's say that we had the following JavaScript code that we wanted to use as a logger:

const util = require('util'),
    fs = require('fs');

// Have the `writeFile` return a promise instead of having to use a callback
const writeFileAsync = util.promisify(fs.writeFile);

/**
 * Async functions allows us to use `await` on promises in the function body, try/catch them, and
 * will return their own promise wrapped around the `return` value
 */
async function logTheValue(item) {
    const jsonString = JSON.stringify(item, null, 2);

    let err = undefined;

    try {
        // Attempt to write a new log file. If this fails, save the error to the `err` variable
        await writeFileAsync(`/logs/${Date.now()}`, jsonString);
    // Catch any errors and keep them as the `e` variable to assign to `err` later
    } catch (e) {
        err = e;
    }

    return {
        loggedValue: jsonString,
        original: item,
        // If there was no error, return `undefined` here
        err: err
    }
}

If we wanted to type the logTheValue function, we'd want to make sure to use a type generic for the input parameter item. By doing so, we could use that same generic for the return prop of loggedValue to ensure they both have the same typing. To do this, we could do so inline:

// Because this is an `async` function, we want to wrap the returned type value in a Promise
async function logTheValue<ItemT>(item: ItemT): Promise<{loggedValue: string, original: ItemT, err: Error | undefined}> {
    // ... Function body here
}

Alternatively, we could utilize another feature of generics — the ability to pass the type value of the generic manually — and make an interface with a generic and do so there:

interface LogTheValueReturnType<originalT> {
    loggedValue: string;
    original: originalT;
    err: Error | undefined;
}

// Notice how we're even wrapping that interface in a built-in type with a generic argument for `Promise`!
async function logTheValue<ItemT>(item: ItemT): Promise<LogTheValueReturnType<ItemT>> {
    // ... Function body here
}

With these few features, we're able to utilize much of the functionality of generics.

However, I know I haven't answered what the <> really is for. Well, much like type variables, there's also the ability to pass types as "type arguments" when generics are applied to a function.

An example of this would be a syntax like this:

logTheValue<number>(3);

Non-Function Generics

As you saw before with the LogTheValueReturnType interface — functions aren't the only ones with generics. In addition to using them within functions and interfaces, you can also use them in classes.

Classes with generics can be particularly helpful for data structures like this:

// DataType might want to be a base64 encoded string, a buffer, or an IntArray
class ImageType<DataType> {
    data: DataType;
    height: number;
    width: number;

    constructor(data: DataType, height: number, width: number) {
        this.data = data;
        this.height = height;
        this.width = width
    };
}

function handleImageBuffer(img: ImageType<Buffer>) {}

Type generics in classes can be used as method argument and property types alike.

There's also the ability to use generics within type definitions:

interface ImageType<DataType> {
    data: DataType;
    height: number;
    width: number;  
}

interface ImageConvertMethods<DataType> {
    // This is the typing of a method. It will take a prop of the generic type and return the generic type
    toPNG: (data: DataType) => DataType;
    toJPG: (data: DataType) => DataType;
}


type ImageTypeWithConvertMethods<DataType> = ImageType<DataType> & ImageConvertMethods<DataType>

Okay, but why-er?

My my, you don't seem to take my word for it when I tell you that type generics are useful. That's alright, I suppose; After all, doubt while learning can lead to some great questions! 😉

Type generics enable us to do things like provide typings for polymorphic functions. Polymorphic functions are functions that can accept a myriad of different types and handle them differently.

Polymorphic functions are not unique to TypeScript; the things learned here about polymorphic functions can be applied to other languages as well. They also provide some real-world insight into the usages of generics and when they could be used.

For example, let's take a look at the code for the toPNG:

function toPNG(data: DataType): DataType {
    if (Buffer.isBuffer(data)) {
        return convertBufferToPNG(data);
    } else if (Array.isArray(data)) {
        const imgBuffer = Buffer.from(data);
        const pngBuffer = convertBufferToPNG(imgBuffer);        
        return Buffer.from(pngBuffer);
    // base64 encoded string
    } else if (typeof data === 'string') {
        const imgBuffer = getBufferFromBaseStr(data);
        const pngBuffer = convertBufferToPNG(imgBuffer);
        return bufferToBase64(pngBuffer);   
    } else {
        throw 'toPNG only accepts arrays, buffers, or strings'
    }
}

Even though this function accepts various data types, it handles them differently under the hood! Functions that have this type of "accept many, handle each slightly differently" behavior are called Polymorphic Functions. They're particularly useful in utility libraries.

Restricting The Types

Unfortunately, there's a problem with the above code: we don't know what type DataType is. Why does that matter? Well, if it's not a string, a Buffer, or an Array-like, it will throw an error! That's certainly not behavior to run into at runtime.

Let's fix that typing:

function toPNG<DataType extends (string | Array<number> | Buffer)>(data: DataType): DataType {
    // ...
}

In this example we're using the extends keyword to enforce some level of type restriction in the otherwise broad definition of a type generic. We're using a TypeScript union to say that it can be any one of those types, and we're still able to set the value to the type variable DataType.

Broaden Your Horizons

We're also able to keep that type restriction broad within itself. Let's say we had a function that only cared if an object had a specific property on it:

interface TimestampReturn<T> {
    isPast: boolean;
    isFuture: boolean;
    obj: T
}
const checkTimeStamp = <T extends {time: Date}>(obj: T): TimestampReturn<T> => {
    let returnVal: TimestampReturn<T> = {
        isPast: false,
        isFuture: false,
        obj
    }

    if (obj.time < Date.now()) {
        returnVal.isPast = true;
    } else {
        returnVal.isFuture = true;
    }

    return returnVal;
}

In this case, we can rely on implicit type casting to ensure that we're able to pass {time: new Date()} but not {} as values for obj.

Conclusion

And that's all I have for generics! Their usages are far and wide, and now you're able to apply your knowledge in code! We're hoping to have more posts on TypeScript soon - both more introductory and advanced.

Questions? Feedback? Sound off in the comments below; we'd love to hear from you!

Introduction to TypeScript — What is TypeScript?

Corbin Crutchley — Tue, 12 Mar 2024 10:10:03 +0000

TypeScript's popularity cannot be understated. Either you likely know someone who works with it, you've heard of it, or possibly you've been using it. As the language continues to grow and evolve, it can be helpful to jump into the language and play with it. Other times, however, having a reference for what the language is, what the language is not, and how it can be helpful can be of great resource. We're hoping that this page can be a good starting point for that resource.

If you're more of an auditory learner, there's also a podcast episode that was done on this exact subject matter with the author of this post.

This podcast episode can be found on the Polyglot Developer Podcast's page

What is TypeScript?

TypeScript is a superset of JavaScript, meaning that all valid JavaScript is valid TypeScript, but not all TypeScript is valid JavaScript. Think of it as JavaScript plus some goodies. These goodies allow developers to add type information to their code that is enforced during a TypeScript to JavaScript compilation step.

These goodies are enabled by the TypeScript compiler, which takes your TypeScript source code and output JavaScript source code, capable of running in any JavaScript environment.

Doesn't JavaScript Have Types Already?

While JavaScript does have a loose understanding of types, they're not strictly enforced.

Take the following example:

let numberHere = 0;
numberHere = 'Test';

const newNumber = 10 - numberHere;

In this example, we're expecting 10 - 0 but have accidentally thrown in a new line during a copy + paste session (this always happens to me) that changed the type from a number to a string. As a result of this errant line, instead of newNumber being a number, it's now NaN.

While TypeScript does not restrict the ability to have NaNs and errant copy-pastes (oh how I wish it did), it can make it more obvious that mistakes like this have been made by marking numberHere as a number type explicitly.

let numberHere: number = 0;
// 🛑 Error will be thrown during compilation:
// Type '"Test"' is not assignable to type 'number'.
numberHere = 'Test';

const newNumber = 10 - numberHere;

This point is made even more complex when dealing with how both values are handled internally in JavaScript. Especially when talking about ES6 classes, the type-strict nature of TypeScript types and the "types" that are understood in JavaScript are not the same. While ES6 classes are syntactical sugar on top of JavaScript's prototype system and there are only seven base-types (called primitive types) in JavaScript that every other value is composed of, TypeScript has a much more robust type system.

Author's Note:
While the above mention of primitive types and syntactical sugar are meant as a path for you to learn more, don't feel discouraged from learning more about TypeScript if you're unfamiliar with such concepts.

We're going to try to go at a high-level, and while we may hint at deeper concepts or knowledge, know that we all learn at our own pace. It's more than okay to take your time feeling comfortable before diving into those topics.

Why TypeScript?

You may be asking yourself: "Why use TypeScript if it doesn't change the runtime behavior of your code?" There can be a few reasons you may want to integrate TypeScript in your project, such as the following.

Type Safety

As mentioned before, JavaScript may have rudimentary types, but TypeScript's are far more robust. This robustness is able to lend developers to force their code inputs and outputs to strictly enforce the limitations the developer places on them. Let's look at take the following code for example:

function addFive(input) {
    return input + 5;
}
addFive('5');

Reading through this code quickly, you might be able to spot the problem. Because we passed in a string, rather than a number, we get the result of '55' rather than the (likely) expected result of 10. This is the kind of unintentional code safety concern that TypeScript fixes. Using TypeScript, we are able to check the properties passed into addFive during compile time in order to warn a developer about these mistakes.

// test.ts
function addFive(input: number) {
    return input + 5;
}
addFive('5');

Will now output:

>tsc test.ts
test.ts:5:9 - error TS2345: Argument of type '"5"' is not assignable to parameter of type 'number'.
5 addFive('5');

In a smaller codebase, such as the given example, it can be easy to miss how important type checking is. Detecting the error in this small length of code is often trivial; however, it can be much more difficult to do so in larger, more complex codebases or when utilizing code that might not be from your project, such as a library or framework. In these use cases, it can be much easier to identify an edge case where changing a function's parameters would break another part of the codebase. Likewise, being able to quickly identify implementation errors when using a library is a significant factor in identifying problems effectively.

Developer Quality of Life

While it can be easy to forget in the abstract world of development, developers make the code that we interact with on a daily basis. These developers (yourself included) tend to like enjoying certain experiences while working on their code. TypeScript provides a myriad of such quality-of-life improvements.

Let's go over some of the arguments in favor of TypeScript's developer quality of life improvements.

Improved Tooling Support

Historically, having the ability to make assumptions about code in order to provide developer niceties (such as autocomplete code suggestions) in loosely typed languages such as JavaScript has been incredibly hard to do. As time has gone on, support for these types of actions has gotten better; but due to the nature of JavaScript's type system, there will likely always be limitations on how effectively this can be done. TypeScript's syntax, however, can provide much of the type data about your source code needed for tools to be able to provide those niceties that are otherwise tricky for these tools to build. The TypeScript team even provides a tool to communicate directly to these IDEs so that the work on implementing this syntax data consumption is much more trivial than they otherwise would be. This is why many changelogs for TypeScript releases mention changes to editors such as Visual Studio Code.

3rd Party Library Support

Because of JavaScript's awesome engineering diversity, many widely used projects do not use TypeScript. However, there are ways we can still utilize TypeScript's tooling capabilities without porting the code. If you have a good understanding of the given project's codebase and TypeScript, you can write a definition file that sits separated from the rest of the codebase. These definition files allow you many of the same tooling abilities native TypeScript source code allows.

An example of these typings might look something like this:

// index.js
function aNumberToAString(numProp) {
    if (typeof numProp !== "number") throw "Only numbers are supported";
    return numProp.toString();
}

// index.d.ts
declare function aNumberToAString(numProp: number): string; // Accept a number arg, return a string

Community Hosting

Additionally, because TypeScript has a well established and widely used install-base, there are already many different definition files in the wild for supporting non-TypeScript supporting projects. One of the more extensive collections of these typings lives at the DefinitelyTyped repository, which publishes the package's community typings under the package names @types/your-package-name (where your-package-name is the name of the project you're looking for typings of) that you can look for on your package manager.

Documented Types

Another way TypeScript can help with the workflow while coding is in regard to gaining references to APIs and code.

When working on projects with objects that contain many properties that are used variously across files and functions, it can be difficult to track down what properties and methods are available to you without having to refer to the documentation of that scope in your application. With types present in your code, you're often able to reference that type (often with a "jump to declaration" shortcut feature that is present in many IDEs) to quickly refer to the properties and methods present on a given value or class.

Type Information

However, developer quality of life changes and type safety aren't the only positive for utilizing TypeScript in your projects!

Although it's a much more complex and highly experimental feature of TypeScript, you are also able to use the typing data from your program to do other operations without explicitly duplicating the type data.

What do I mean by this? Take the following code:

function HandleUserInput(inputProp: number, functionToHandle: Function): string {
...
}

What if you had a way to mutate or modify this function? What if this way of mutating this function allowed you the ability to see that the first parameter is a number, the second is a function, and the return type is a string? While this may not seem to have any immediate advantages, this meta-type info allows us to do powerful things. It can be used in a situation where you might want to generate a JSON schema based on a class declaration in a TypeScript file or when using ORMs and mapping TypeScript types to the databases' native type. By doing something like this with your ORM, you could preserve both the database typing and the TypeScript compile type within the same file so that you don't have to do duplicate checks against either.

Author's note:
An ORM is an "Object Relational Model". An ORM is a library that helps developers keep database schemas mapped in their code, often by having classes reflect the shape of their (typically) SQL server schema.

As always, feel free to search more on them (the terms "JavaScript ORM" might help) and always know that not knowing a thing is always okay 🤗

Here's an example from a library built to do just that that allows you to preserve the TypeScript type to save data in specified field types in your database:

import {Entity, PrimaryGeneratedColumn, Column} from "typeorm";

@Entity()
export class User {

    @PrimaryGeneratedColumn()
    id: number;

    @Column()
    firstName: string;

    @Column()
    lastName: string;

    @Column()
    age: number;
}

And this feature doesn't have an API dissimilar to standards-based APIs; it's being built with and on top of features proposed for a future version of JavaScript (commonly referred to as ESNext).

What isn't TypeScript

Now that we've covered a bit of what TypeScript is, it might be a good idea to quickly synopsis what it isn't. After all, to know what something is not is oftentimes just as powerful as knowing what something is.

It's Not the Tower You Think It Is

One of the things TypeScript is not is a transpiler. What this means is that TypeScript (alone) will not take TypeScript source code that contains syntax from newer JavaScript versions (ES6+) and output older versions of JavaScript (ES5) in order to improve browser compatibility (IE11).

For anyone who's used TypeScript, this may confuse you, as there are various flags and config options for the output version of JavaScript it compiles to. What's really happening under-the-hood is that TypeScript hands off your source code to Babel after it compiles down to JavaScript. With Babel 7 this is even harder to notice, but be aware that any transpilation you expect to occur when using TypeScript may force you to use and understand Babel tools.

However, this does mean that you can utilize the entire arsenal of Babel tooling to your disposal, such as Babel plugins.

Logic != Typings

TypeScript will not find all your typing errors on its own. This is because TypeScript is only as useful as your typings are. Let's look back at an earlier example:

function addFive(input) {
    return input + 5;
}

If you keep addFive's input parameter without an explicit type, it will try to do its best to detect the type based on the operations you run on the value. While these inferred types are often very useful, it often has difficulty doing so in an accurate manner. This is why manually assigning types is almost always preferred to leaving them as inferred. If it couldn't properly detect a type for the value in this example, it does nothing to prevent strings from being passed as the parameter value.

Although examples like this are simple, strict typings can also become fairly complex to maintain maximum type strictness. See the Advanced section of the official handbook for examples that illustrate this.
Also, because typings do nothing to test against the logic of your program, they should not be seen as a replacement for testing, but rather a companion to them. With strict typings and proper testing, regressions can be severely limited and improve code quality of life.

Typing Mishaps Happen

Remember, because typings are kept separately from the project's logic code, typings can be misleading, incomplete, or otherwise incorrect. While this can also happen with TypeScript logic code, it tends to be more actively mitigated as a project's ability to compile (and therefore distribute) relies on that typing information. This isn't to say that you should immediately mistrust typings, but this is simply a reminder that they too may have their flaws — just as any other part of a codebase.

Don't Forget To Document

Just as typings shouldn't replace tests, typings should also not replace documentation or comments. Typings can help understand what inputs and outputs you're expecting, but just the same as with testing; it doesn't explain what the logic does or provide context as to why the data types have specific properties, what the properties are used for, and so forth. Additionally, typings often do little to help explain how to contribute in the larger scale when talking about documentation. For example, in a large-scale application, there may be come complex data patterns or order-of-operations that are required to do a task. Typings alone will not effectively communicate these design principles that are integral to the usage of the code.

Essentially, I just want to make sure to iterate that while there may be tools that can let you auto-document the properties and the property type from TypeScript annotations, hand-done documentation is still extremely important.

Conclusion

And with that, we have a better understanding of what TypeScript is! I hope this has been informative and helpful for those that may be new to the language in particular. What'd you learn, let us know!

Now that you're more familiar with TypeScript, maybe you'd like to play around with one of their more experienced functionality: Type generics? We have a whole post around that concept as well, you can find that here.

Thanks for reading! Leave any questions or feedback in the comments below.

What is React's useFormState and useFormStatus?

Corbin Crutchley — Mon, 04 Mar 2024 16:00:00 +0000

Thus far in our article series, we've taken a look at how React handles reactivity, server rendering, and how to send data back and forth between our React-based server and our client.

In particular, our last article outlined how we can send data from the server down to the client and back:

This is a great almost bi-directional communication from React Server Components and back.

Why do you say "almost"? What's missing?

Well, once you send an action back to the server, how do you get a response back from the server? What happens if the server action needs to inform you of some status?

Well, this is where useFormStatus and useFormState come into play:

What is `useFormStatus`?

useFormStatus allows developers to listen for state changes on their React Server Actions. IE: When a server action is pending or not.

While useFormStatus isn't directly a way to listen for changes from the server (instead it relies on the information on the client to show its metadata) it allows us to make a nicer user experience by showing a loading indicator while the server is taking its action.

Let's start with a client-side actions demo:

import { useFormStatus } from 'react-dom';

function Submit() {
  const status = useFormStatus();
  return (
    <button disabled={status.pending}>
      {status.pending ? 'Sending...' : 'Send'}
    </button>
  );
}

function App() {
  async function waitASecond() {
    await new Promise((resolve) => {
      setTimeout(() => {
        resolve();
      }, 1000);
    });
  }

  return (
    <form action={waitASecond}>
      <Submit />
    </form>
  );
}

Here, we're using the pending field on useFormStatus to tell us when our form is being submitted.

A note about useFormStatus:
You might be wondering why I've extracted the Submit component into its own function. This is because useFormStatus is a hook that implicitly gathers its state from the parent <form> element.

If you were to use useFormStatus inside of the App component, it would not work as expected. This is because the App component is not a child of the <form> element.

For example, the following code would not work as expected:
// This code does not work, as `useFormStatus` is not a child of the <form> element
function App() {
  async function waitASecond() {
    await new Promise((resolve) => {
      setTimeout(() => {
        resolve();
      }, 1000);
    });
  }

  const status = useFormStatus();

  return (
    <form action={waitASecond}>
      <button disabled={status.pending}>
       {status.pending ? 'Sending...' : 'Send'}
      </button>
    </form>
  );
}

`useFormStatus` usage with server actions

But of course it works with server actions as well. Let's adapt our todo list example from our last article:

// page.jsx
import { Todo } from "./client";
import { addTodoToDatabase, getTodos } from "./todos";

export default async function Home() {
    const todos = await getTodos();

    async function addTodo(formData) {
        "use server";
        const todo = formData.get("todo");
        await addTodoToDatabase(todo);
    }

    return <Todo todos={todos} addTodo={addTodo} />;
}

// client.jsx
"use client";
import { useCallback } from "react";
import { useFormStatus } from "react-dom";

function TodoFormInner() {
    const status = useFormStatus();
    return (
        <>
            {status.pending && <p>Adding todo...</p>}
            <input disabled={status.pending} name="todo" />
            <button disabled={status.pending} type="submit">
                Add Todo
            </button>
        </>
    );
}

export function Todo({ todos, addTodo }) {
    const addTodoAndRefresh = useCallback(async (formData) => {
        await addTodo(formData);
        window.location.reload();
    }, []);

    return (
        <>
            <form action={addTodoAndRefresh}>
                <TodoFormInner />
            </form>
            <ul>
                {todos.map((todo) => {
                    return <li key={todo.id}>{todo.value}</li>;
                })}
            </ul>
        </>
    );
}

What is `useFormState`?

useFormState allows us to get a response from a React Server Action and handle the results any way we might want to; including (but not limited to) displaying the contents of the response to the client.

This is a simple example of what useFormState looks like on client-side form actions:

function App() {
  async function sayHi() {
    await new Promise((resolve) => {
      setTimeout(() => {
        resolve();
      }, 1000);
    });
    return 'Value from the action';
  }

  // State will be updated when `sayHi` returns a value
  const [state, action] = useFormState(sayHi, 'Initial value');

  return (
    // Pass the action from `useFormState`
    <form action={action}>
      <p>{state}</p>
      <button>Submit</button>
    </form>
  );
}

We can even implement a simple counter by utilizing the previous state (or initial value if there is no previous state):

async function increment(previousState, formData) {
  return previousState + 1;
}

function App() {
  const [state, action] = useFormState(increment, 0);
  return (
    <form action={action}>
      <p>{state}</p>
      <button>Increment</button>
    </form>
  )
}

This increment example comes from the React docs for the Hook.

`useFormState` usage with server actions

While useFormState works on the client-side, it's the most useful in conjuncture with server actions.

Let's add some form validation to our todo list application so that the user can't submit an empty field:

// page.jsx
import { Todo } from "./client";
import { addTodoToDatabase, getTodos } from "./todos";
import { redirect } from "next/navigation";

export default async function Home() {
    const todos = await getTodos();

    async function addTodo(previousState, formData) {
        "use server";
        const todo = formData.get("todo");
        if (!todo) return "Please enter a todo";
        await addTodoToDatabase(todo);
        redirect("/");
    }

    return <Todo todos={todos} addTodo={addTodo} />;
}

// client.jsx
"use client";
import { useFormState } from "react-dom";

export function Todo({ todos, addTodo }) {
    const [state, action] = useFormState(addTodo, "")

    return (
        <>
            <form action={action}>
                {state && <p>{state}</p>}
                <input name="todo" />
                <button type="submit">
                    Add Todo
                </button>
            </form>
            <ul>
                {todos.map((todo) => {
                    return <li key={todo.id}>{todo.value}</li>;
                })}
            </ul>
        </>
    );
}

Don't forget the API changes:

Don't forget that useFormState requires you to change your server action to include a new first argument for previousState. Otherwise you'll get the following error:
 ⨯ app\page.jsx (10:24) @ get
 ⨯ TypeError: formData.get is not a function

`useFormState` usage without client-side JavaScript

Because useFormState utilizes the <form> element's native action attribute under-the-hood, it works even without JavaScript enabled.

Assume you have the above sample code, but you have JavaScript disabled. When you click the submit button, the form will submit to the action attribute, and the page will refresh with the new information for the user.

https://unicorn-utterances.com/content/blog/what-is-use-form-state-and-status/nextjs-use-state-js-disabled.mp4

Keep in mind that any client-side React code will not run if JavaScript is disabled. This includes the useEffect Hook among others.

How to use `useFormState` and `useFormStatus` together

You may have noticed that useFormState doesn't provide us the same pending information that useFormStatus does. Let's combine them for the ultimate user experience:

// page.jsx
import { Todo } from "./client";
import { addTodoToDatabase, getTodos } from "./todos";
import { redirect } from "next/navigation";

export default async function Home() {
    const todos = await getTodos();

    async function addTodo(previousState, formData) {
        "use server";
        const todo = formData.get("todo");
        if (!todo) return "Please enter a todo";
        await addTodoToDatabase(todo);
        redirect("/");
    }

    return <Todo todos={todos} addTodo={addTodo} />;
}

// client.jsx
"use client";
import { useFormState, useFormStatus } from "react-dom";

function TodoFormInner() {
    const status = useFormStatus();
    return (
        <>
            {status.pending && <p>Adding todo...</p>}
            <input disabled={status.pending} name="todo" />
            <button disabled={status.pending} type="submit">
                Add Todo
            </button>
        </>
    );
}

export function Todo({ todos, addTodo }) {
    const [state, action] = useFormState(addTodo, "");

    return (
        <>
            <form action={action}>
                {state && <p>{state}</p>}
                <TodoFormInner />
            </form>
            <ul>
                {todos.map((todo) => {
                    return <li key={todo.id}>{todo.value}</li>;
                })}
            </ul>
        </>
    );
}

Conclusion

And with that, that's our article series! We've covered a lot of ground; everything from how React's most fundamental values like reactivity works to advanced bi-directional data flow from the server and back!

Want to keep learning React from lil' ole' me? Well shucks; first thank you for reading!

But I can oblige! I've written a book called "The Framework Field Guide" that teaches React, Angular, and Vue all-at-once, in-depth, and for free. Check it out and let me know what you think.

What are React Server Actions?

Corbin Crutchley — Sat, 02 Mar 2024 16:00:00 +0000

In our last article, we talked about React's use hook and Async Server Components; both means to handle async operations to display in a render.

In the conclusion of that article, I hinted that there was going to be more to the Server Components story. Well, sure enough there is in the form of React Server Actions.

First though, let's talk about the client-side once again.

What are React `<form>` actions?

Let's say that we're building a todo list application:

function App() {
    const id = useRef(0);
    const [todos, setTodos] = useState([]);
    const [todoInput, setTodoInput] = useState("");

    function addTodo(e) {
        e.preventDefault();
        setTodos([...todos, { value: todoInput, id: ++id.current }]);
    }

    return (
        <>
            <ul>
                {todos.map((todo) => {
                    return <li key={todo.id}>{todo.value}</li>;
                })}
            </ul>
            <form onSubmit={addTodo}>
                <input
                    name="todo"
                    value={todoInput}
                    onChange={(e) => setTodoInput(e.target.value)}
                />
                <button type="submit">Add Todo</button>
            </form>
        </>
    );
}

This works, but notice how we're having to preventDefault here. This is because we're sidestepping <form>'s native submit event's behavior; submitting a form using the action property.

Luckily, the React core team has noticed this and introduced a means to passing a function in the action property in our client-side React applications:

function App() {
    const id = useRef(0);
    const [todos, setTodos] = useState([]);

    async function addTodo(formData) {
        const todo = formData.get("todo");
        setTodos([...todos, { value: todo, id: ++id.current }]);
    }

    return (
        <>
            <ul>
                {todos.map((todo) => {
                    return <li key={todo.id}>{todo.value}</li>;
                })}
            </ul>
            <form action={addTodo}>
                <input name="todo" />
                <button type="submit">Add Todo</button>
            </form>
        </>
    );
}

A note on API versioning:

This feature is only currently available in React Canary releases. This won't work with the current stable release.

This allows us to write less code and focus less on default DOM behavior and shift our efforts to shipping code.

Now that we've seen how <form> actions work on the client, let's move back to the server and look at React server actions:

What are React Server Actions?

In short; React Server Actions are a way to call server-side code in React's client-side rendering. If asynchronous server components with await in them allow you to pass server data to the client, server actions enable you to pass data back from the client to the server.

However, to pass a function from a server component down to the client we must designate our functions we want to pass with a special boundary string.

What is `"use server"`?

"use server" is the boundary string in React server apps that allows us to mark a function as "ready to pass to the client".

Let's take our previous todo list and migrate the state to the server. This way all of our friends can see our shopping list!

We'll start by using async server components to pass our todo list in from the server's database:

// Theoretical API from a database wrapper
import { getTodos } from "./todos";

export default async function Todo() {
    const todos = await getTodos();
    return (
        <>
            <ul>
                {todos.map((todo) => {
                    return <li key={todo.id}>{todo.value}</li>;
                })}
            </ul>
            <!-- This form doesn't work yet -->
            <form>
                <input name="todo" />
                <button type="submit">Add Todo</button>
            </form>
        </>
    );
}

Now we have a way to pass data to the client, but not a way to get the user's input back. Let's fix that by passing a server action to the client and using <form action={}/> to call this function for us:

import { addTodoToDatabase, getTodos } from "./todos";
import { redirect } from "next/navigation";

export default async function Todo() {
    const todos = await getTodos();
    async function addTodo(formData) {
        "use server";
        const todo = formData.get("todo");
        await addTodoToDatabase(todo);
        // Refresh the page to see the new todo
        redirect("/");
    }
    return (
        <>
            <ul>
                {todos.map((todo) => {
                    return <li key={todo.id}>{todo.value}</li>;
                })}
            </ul>
            <form action={addTodo}>
                <input name="todo" />
                <button type="submit">Add Todo</button>
            </form>
        </>
    );
}

Now if we:

Type something in the <input/>
Click "Add Todo"
Wait a moment

We'll see the todo we typed show up for all of our users on the page.

Keep in mind, this is using REST APIs, so it won't auto-refresh the page for all users, just the user who added the todo.

Adding in client-side components

Notice that we're only exclusively using a server-component in the example above. Because of this, we don't have any loading indicator for the time the server is adding our todo.

Let's add a useState in our client-component to solve this user experience problem:

import { Todo } from "./client";
import { addTodoToDatabase, getTodos } from "./todos";

export default async function Home() {
    const todos = await getTodos();

    async function addTodo(formData) {
        "use server";
        const todo = formData.get("todo");
        await addTodoToDatabase(todo);
    }

    return <Todo todos={todos} addTodo={addTodo} />;
}

// client.jsx
"use client";

import { useCallback, useState } from "react";

export function Todo({ todos, addTodo }) {
    const [isLoading, setIsLoading] = useState(false);

    const addTodoAndRefresh = useCallback(async (formData) => {
        await addTodo(formData);
        window.location.reload();
    }, []);

    return (
        <>
            {isLoading && <p>Adding todo...</p>}
            <ul>
                {todos.map((todo) => {
                    return <li key={todo.id}>{todo.value}</li>;
                })}
            </ul>
            <form
                action={addTodoAndRefresh}
                onSubmit={() => {
                    // We're using onSubmit so that we don't have to wait for the server
                    // to get the request before we set isLoading to true
                    setIsLoading(true);
                }}
            >
                <input disabled={isLoading} name="todo" />
                <button disabled={isLoading} type="submit">
                    Add Todo
                </button>
            </form>
        </>
    );
}

Instead of passing a server action from a server component, we could also mark a whole file as "use server" and import it from there;

// server-actions.js
"use server";

import { addTodoToDatabase } from "./todos";

export async function addTodo(formData) {
    const todo = formData.get("todo");
    await addTodoToDatabase(todo);
}

// client.jsx
"use client";

import { addTodo } from "./server-actions";
import { useCallback, useState } from "react";

export function Todo({ todos, addTodo }) {
    const [isLoading, setIsLoading] = useState(false);

    const addTodoAndRefresh = useCallback(async (formData) => {
        await addTodo(formData);
        window.location.reload();
    }, []);

    return (
        // ...
    );
}

Be careful what you export:

Don't mark your whole database API file as "use server", otherwise it makes it easier to accidentally cause a security issue by exposing functions you might not wanted to've done otherwise.

What happens if you don't mark a function with `"use server"`?

If you forget to mark your server action with the "use server" string, like so;

// Server component
import { Todo } from "./client";
import { getTodos } from "./todos";

export default async function Home() {
    const todos = await getTodos();
    const addTodo = () => {
        // ...
    };
    return <Todo todos={todos} addTodo={addTodo} />;
}

You get the following error, reminding you to explicitly mark your function as being ready to pass to the client:

⨯ Error: Functions cannot be passed directly to Client Components unless you explicitly expose it by marking it with "use server".
<... todos={[...]} addTodo={function}>
^^^^^^^^^^

This is a safety feature so you don't end up enabling the client to call functions that aren't allowed.

Are synchronous functions allows in React server actions?

No. Only async functions are allowed in server actions. If you forget to mark your action as async;

// Server component
import { Todo } from "./client";
import { getTodos } from "./todos";

export default async function Home() {
    const todos = await getTodos();
    const addTodo = () => {
        "use server"
        console.log("Testing");
    };
    return <Todo todos={todos} addTodo={addTodo} />;
}

You'll receive the following error:

Error:
  × Server actions must be async functions

Can you define server actions in a client component file?

No. You cannot mix-and-match server action definitions within your client component files. If you do the following:

"use client"

export function Todo({ todos }) {
  // ...

  export async function addTodo(formData) {
    "use server";
    // ...
  }

  return (
    <>
      {/* ... */}
      <form
        action={addTodo}
      >
        {/* ... */}
      </form>
    </>
  );
}

You'll see an error that looks like:

Error:
  × It is not allowed to define inline "use server" annotated Server Actions in Client Components.
  │ To use Server Actions in a Client Component, you can either export them from a separate file with "use server" at the top, or pass them down through props from a Server Component.
  │
  │ Read more: https://nextjs.org/docs/app/api-reference/functions/server-actions#with-client-components

Remember where to place your server actions:
Server actions can only be defined in a file with "use server" at the top or passed in via a server component marked with "use server" at the top of the function definition.

Why are React Server Actions significant?

React Server Actions not only make it easier to call data from the server from the client, but they play an important role in providing your applications "progressive enhancement"; they enable your server actions to call a server's function even when the user has JavaScript disabled in their browser.

Keep in mind that while your server action will go through, any client-ran React code (IE useEffect) will still fail to execute when JavaScript is disabled.

For example, assume you're building a payment form:

This payment card graphic comes from shadcn/ui's examples

You want this payment form to be bulletproof. Any user having to attempt a re-purchase will likely not return to your site; leading to lost sales.

If your user doesn't have JavaScript enabled but you've implemented Server Actions; no problem. The user's purchase will still go through.

But this seems a bit like an edge-case, doesn't it? After all, according to a survey from WebAIM showed that 99.7% of users have JavaScript enabled and I can't imagine many folks that would intentionally turn it off.

While that may be true for some use-cases, consider the following examples:

A user in a developing country where data is expensive, disabling JavaScript could save money.
A user on a subway train with limited cellular network; able to download the HTML but failed the JavaScript bundle download.
A user with haywire browser extensions that has disabled the JavaScript on your page due to interference; either due to a bug or adblock.
A user that works at a business that has strict security requirements and limits the loading of JavaScript on their network.

All of these are possible scenarios for your users. The more users you account for, the more money your organization can make.

Conclusion

React Server Actions make for a wonderful way of intermingling server and client state. It's never been easier to write code for React applications that span between both the frontend and backend alike. Moreover, it's only going to get better with time.

But there's one more thing I still want to cover about React Server Components left... Let's look at useFormState and useFormStatus next time!

Until then, drop by our Discord server and tell us what you think of React Server Actions - we'd love to hear your thoughts!

What is React Suspense and Async Rendering?

Corbin Crutchley — Thu, 29 Feb 2024 16:00:00 +0000

In our last article, I introduced React Server Components (RSC) as a primitive to enable more efficient server-side React usage.

I also hinted in the conclusion of that article that due to the nature of RSCs we'd be able to add on to our knowledge and utilize data fetching.

Let's talk about data fetching, first by putting server-side behavior to the side, then we'll reintroduce the server-APIs soon after.

To do this, I want to introduce you to three new APIs: the use Hook, the <Suspense> component, and Async React Server Components.

What is the React `use` Hook?

The React use Hook enables you to load data asynchronously in your components where data fetching is mission-critical.

Let's say that you're in a traditional client-side rendered app and want to fetch data from the server. If you're not using a library like TanStack Query (which you should be), you might have something like this:

const [data, setData] = useState({
    loading: true,
    result: null,
    error: null,
});

// Please use TanStack Query
useEffect(() => {
    fetchUser()
        .then((serverData) => {
            setData({ error: null, loading: false, result: serverData });
        })
        .catch((err) => {
            setData({ error: err, loading: false, result: null });
        });
}, []);

While this works and useEffect can be used this way, useEffect is not a built-in mechanism for asynchronous data loading.

Instead, React 18.3 (in canary release at the time of writing) introduces a new Hook: use.

This hook allows you to pass a promise to it to load data:

import {use, cache} from "react";

const UserDisplay = () => {
    const result = use(fetchUser());

    return <p>Hello {result.name}</p>;
};

// Without `cache`, a new instance of a promise would
// be returned to `use` on every render. That's bad.
const fetchUser = cache(() => {
    // ...
});

Here, we're using use in tandem with React's cache function to avoid having to run useMemo on fetchUser.

Now React will treat the result as if it were not a promise, so that you can access properties and render them directly inside of your JSX. Effectively use acts as an await for promises in your client components.

If your only objective is to load data on the client, I'd still highly suggest using TanStack Query or something similar. After all, even with use you likely want to take into consideration the following:

Caching results

Refetching with new inputs

Abort signals to avoid timing issues

What is the `<Suspense>` component?

The React <Suspense> component allows you to add a loading state to your components needing to use asynchronous APIs; such as the new use Hook.

Take the <UserDisplay> component from before. To add a loading indicator to the <UserDisplay> component, add a <Suspense> component in the parent component alongside a fallback={} property:

function App() {
    return (
        <Suspense fallback={<p>Loading...</p>}>
            <UserDisplay promise={promise} />
        </Suspense>
    );
}

Reusing Loading Indicators

Loading indicators may be important to show in-progress data fetching, but users don't often like seeing a dashboard with 30 different loading spinners.

Because of this, React has made handling multiple data sources easy using <Suspense>; just wrap multiple use Hook components inside of a single <Suspense> component:

const UserDisplay = ({timeout}) => {
    const result = use(fetchUser({ timeout }));

    return <p>Hello {result.name}</p>;
};

function App() {
    return (
        <Suspense fallback={<p>Loading...</p>}>
            <UserDisplay timeout={1500} />
            <UserDisplay timeout={3000} />
        </Suspense>
    );
}

// Pretend this is fetching data from the server
const fetchUser = cache(({ timeout }) => {
    return new Promise((resolve) => {
        setTimeout(() => {
            resolve({
                name: "John Doe",
                age: 34,
            });
        }, timeout ?? 1000);
    });
});

To sidestep this behavior, wrap each <UserDisplay> in their own <Suspense>:

function App() {
    return (
        <>
            {/* Will show "Loading..." for 3 seconds while
                waiting for BOTH promises to resolve */}
            <Suspense fallback={<p>Loading...</p>}>
                <UserDisplay timeout={1500} />
            </Suspense>
            <Suspense fallback={<p>Loading...</p>}>
                <UserDisplay timeout={3000} />
            </Suspense>
        </>
    );
}

How do I handle rejected promises in `<Suspense>`?

While use and <Suspense> handle resolved promises just fine, they alone will not handle rejected promises passed to the use Hook.

To handle rejected promises in Suspense, you'll need to use an <ErrorBoundary> class-based component which utilizes the getDerivedStateFromError lifecycle method.

Let's see how we can do this ourselves:

const UserDisplay = () => {
    const result = use(fetchUser());

    return <p>Hello {result.name}</p>;
};

function App() {
    return (
        <ErrorBoundary>
            <Suspense fallback={<p>Loading...</p>}>
                <UserDisplay />
            </Suspense>
        </ErrorBoundary>
    );
}

class ErrorBoundary extends Component {
    state = { error: null };

    static getDerivedStateFromError(error) {
        return { error };
    }

    render() {
        if (this.state.error) {
            return <p>There was an error: {JSON.stringify(this.state.error)}</p>;
        }

        return this.props.children;
    }
}

Using `use` on the server

Now let's move back to server-land

We know that we can make server-only components, that don't reinitialize on the client, right? Now what if we could load the data on the server and not have it passed to the client either?

Well, luckily for us - we already have a mechanism for loading data in React that's async:

const ServerComp = () => {
    /* This works, but is not the best way of doing
       things on the server */
    const data = use(fetchData())

    return <ChildComp data={data}/>
}

const Parent = () => {
    /* We don't need a Suspense component here, since
       the server will wait for the promise to resolve before
       sending data to the client */
    return <ServerComp/>;
}

Here, we're seeing an imaginary ChildComp rendered with data passed from the server - this data is never fetched on the client thanks to how React Server Components work.

But wait a moment - we're on the server. use accepts any promise... What if... What if we just polled our database directly?

const ServerComp = () => {
    /* This also works, but is still not the best way
        of doing things in server components */
    const data = use(fetchOurUserFromTheDatabase())

    return <ChildComp data={data}/>
}

// Still using cache... For now...
const fetchOurUserFromTheDatabase = cache(() => {
    // ...
})

This works!

What are React Async Server Components?

While use is undoubtably useful for client apps, server components have a better option available to us: async components.

Here, we mark our component as being async and simply await the promise function to resolve it prior to reaching our JSX:

// No need for `cache`!
async function fetchOurUserFromTheDatabase() {
    // ...
};

async function UserDetails() {
  const user = await fetchOurUserFromTheDatabase();
  return <p>{user.name}</p>;
}

We can then use it as if it were any other server component:

export default function Home() {
  return <UserDetails />;
}

Not only is the developer experience for this component authoring better, but it's drastically more performant due to how its internals work.

If that's the case why don't we use async components on the client as well?

According to the React team, there are technical limitations around using async components on the client that make it infeasible to use on the client.

A note about async server components:
Something to keep in mind is that while normal React Server Components can use some Hooks (useId, useSearchParams, etc) async server components cannot use any hooks of any kind.

Conclusion

In this article, we took a look at React's official solutions for async rendering behavior. This is great to see the team make strides
in this area; I think most apps are going to end up utilizing these heavily.

However, this is only half of the story for React's async support. Next up, we'll talk about React Server Actions, which enables the client to
make RPC-like calls back to the server and execute server code for us.

Can't wait to talk about what you learned about? Join our Discord and tell us what you think about the Suspense API!

What are React Server Components (RSCs)?

Corbin Crutchley — Tue, 27 Feb 2024 16:00:00 +0000

In our last article in the series, we talked about how React is able to pre-generate HTML from JSX on the server (or developer's machine) prior to being shipped to the end-user. This process is called "SSR" and can be mission-critical in getting your applications as performant as possible.

I originally wrote that article in early 2020. At this point in React's development lifecycle, there was an inherent problem to using SSR; it would lead to duplicate effort between the server and the client.

See, up to that point Next.js and other React SSR solutions had one way of doings things:

1) Render the VDOM on the server
2) Generate HTML from the server's VDOM
3) Ship HTML and all of the React code to the client
4) Re-generate the VDOM from scratch on the client
5) Wipe away the old DOM and re-render all components from the new client's VDOM instance

This process is called "Hydration" and while it worked the way it did before, it introduced a new performance problem. Hydration could be needlessly expensive if most of your content coming from the server was going to be static anyway. This was a huge problem that the React team had to solve.

Later in the same year of my article (December 2020), they had the answer: React Server Components.

What is a React Server Component (RSC)?

In short; React Server components allow you to designate which React components render on the server and which components re-initialize on the client. This is done using a special syntax in your components and allows for special server-only data loading patterns when implemented properly.

For example, take the following:

function App() {
    return <>
        {/* Render parts on the client */}
        <Header/>
        {/* Render all of it on the client */}
        <Dashboard/>
        {/* Render all of it on the server */}
        <Footer/>
    </>
}

When executed, it might look something like the following process:

Here, we can see that <ProfilePicture>, <Dashboard/>, and all of their children will be re-initialized on the client. Meanwhile the <Footer> and <Header> components will not re-initialize on the client.

Keep in mind, client-components will still pre-generate HTML on the server by default. The difference here is that the client re-initialization is now informed by the VDOM constructed on the server, allowing for drastically reduced required execution.

What is `"use client"`?

In React Server Components, "use client" is a string at the top of the file or function that indicates that React should also render the component on the client. Rendering on the client side allows you to use state and rerender reactively. Without "use client", the component will be treated as a server component.

Let's use this "use client" syntax to build out the example from the image in the previous section, distinguishing which type of component is which along the way:

// page.jsx
import {ProfilePicture, Dashboard} from "./client-components"

export function App() {
    return <>
        <Header/>
        <Dashboard/>
        <Footer/>
    </>
}

function Footer() {
    // ...
}

function Header() {
    return (
        <>
            <SearchBar/>
            <ProfilePicture/>
        </>
    )
}


function SearchBar() {
    // ...
}

"use client"
// client-components.jsx
export function Dashboard() {
    return (
        <Chart/>
    )
}


function Chart() {
    // ...
}

export function profilePicture() {
    // ...
}

Limitations of Server Components

Because a server component runs entirely on the server, there are a few limitations you should be aware of:

No usage of React Hooks that contain client-side state (useState, useReducer, etc)
- This includes importing code that lazily uses these React Hooks, although library authors have found a way around this for their needs.
- Some Hooks that do not require client-side state are okay to use (useId, Next.js' useSearchParams, etc)
<Context.Provider> usage
No usage of browser APIs (localstorage, querySelector, etc)
You cannot pass the following property values from a server component to a client component:
- React Elements/JSX (component={<Component/>} or component={Component})
- Functions (unless it's a Server Action - more on that in a future article)
- Classes
- Instances of Custom Classes
- Custom Symbols
Cannot be called inside a Client component. IE:

  const ClientComponent = () => {
    return <ServerComponent/>
  }

Is not allowed but:

  const ClientComponent = ({children}) => {
    return <div>{children}</div>
  }

  const App = () => {
    return <ClientComponent><ServerComponent/></ClientComponent>
  }

Is allowed.

Conclusion

React Server Components have been a huge topic of discussion lately. So much so that while the fixes to hydration are useful, you may be left wondering:

Is that all there is to RSCs?

Luckily, it's not!

See, by providing a primitive for server behavior in React, the team has unlocked a great deal of potential in regards to data loading.

But that's a story for next time. Next up? React's Suspense APIs!

What is Server Side Rendering (SSR) and Static Site Generation (SSG)?

Corbin Crutchley — Sun, 25 Feb 2024 16:00:00 +0000

In recent years, projects like Vercel's NextJS and Gatsby have garnered acclaim and higher and higher usage numbers. Not only that, but their core concepts of Server Side Rendering (SSR) and Static Site Generation (SSG) have been seen in other projects and frameworks such as Angular Universal, ScullyIO, and NuxtJS. Why is that? What is SSR and SSG? How can I use these concepts in my applications?

We'll walk through all of these questions and provide answers for each. First, we have to have an understanding of how a typical HTML site is able to serve content to your user.

Vanilla HTML Sites

While many sites today are built using a component-based framework like Angular, React, or Vue, there's nothing wrong with good ole' HTML. For sites like this, you typically provide an HTML file for each of the routes of your site. When the user requests one of the routes, your server will return the HTML for it. From there, your browser parses that code and provides the content directly to the user. All in all, the process looks something like this:

1) You build HTML, CSS, JS
2) You put it on a server
3) The client downloads the HTML, CSS, JS from server
4) The client immediately sees content on screen

This is a reasonably straightforward flow once you get the hang of it. Let's take a look at what happens when you throw a component-based framework into the fray.

Client Side Rendering

While you may not be familiar with this term, you're more than likely familiar with how you'd implement one of these; After all, this is the default when building an Angular, React, or Vue site. Let's use a React site as an example. When you build a typical React SPA without utilizing a framework like NextJS or Gatsby, you'd:

1) You build the React code
2) You put it on a server
3) The client downloads the React code from the server
4) The React code runs and generates the HTML/CSS on the client's computer
5) The user then sees the content on screen after React runs

This is because React's code has to initialize to render the components on screen before it can spit out HTML for the browser to parse. Sure, there's an initial HTML file that might have loading spinner, but until your components have time to render, that's hardly useful content for your user. While these load times can be sufficient for smaller applications, if you have many components loading on-screen, you may be in trouble if you want to keep your time-to-interactive (TTI) low. That scenario is where SSR often comes into play.

Server Side Rendering (SSR)

Because React has to initialize somewhere, what if we were to move the initial rendering off to the server? Imagine - for each request the user sends your way, you spin up an instance of React. Then, you're able to serve up the initial render (also called "fully hydrated") HTML and CSS to the user, ready to roll. That's just what server-side rendering is!

1) You build the React code
2) You put it on a server
3) The client requests data
4) The server runs the React code on the server to generate the HTML/CSS
5) The server then sends the generated HTML/CSS on screen
6) The user then sees the content on screen. React doesn't have to run on their computer

There are more improvements than there might initially see, however! Because you're hosting from a server - which has better network connectivity than a user's machine - you're able to make much faster network requests to perform that initial render.

Say you need to grab data from the database to populate the screen's data, you're able to do that much faster as a result. Instead of displaying the user a loading screen while you wait to grab the data, you can simply tell your client, "don't show anything until I send you HTML that I've generated from React." Due to the speed of your network, you can typically ship down a hydrated UI from database data as quickly as you'd typically be able to display a spinner.

Moreover, if you have your server and database in the same hosting location, you're even able to avoid out-of-intranet calls, which would provide faster, more reliable connectivity for your initial render.

That said because you're relying on server functionality to do this rendering, you have to have a custom server setup. No simple CDN hosting here - your server has to initialize and render each user's page on request.

Static Site Generation (SSG)

If SSR is "passing the buck" to the server to generate the initial page, then SSG is passing the buck to you - the developer.

While the industry widely recognizes the term "Static Site Generation," I prefer the term "compile-side rendering" or "compile-time server-side rendering." This is because I feel they outline a better explanation of the flow of displaying content to the user. On an SSG site, you'd:

1) You build the React code
2) You generate the HTML and CSS on your development machine before deploying to a server (run build)
3) You put the generated built code on a server
4) The client downloads the HTML, CSS, JS from the built code on the server
5) The client immediately sees content on screen

This simply extends the existing build process that many front-end frameworks have. After Babel's done with its transpilation, it merely executes code to compile your initial screen into static HTML and CSS. This isn't entirely dissimilar from how SSR hydrates your initial screen, but it's done at compile-time, not at request time.

Since you're only hosting HTML and CSS again, you're able to host your site as you would a client-side rendered app: Using a CDN. This means that you can geo-sparse your hosting much more trivially but comes with the caveat that you're no longer to do rapid network queries to generate the UI as you could with SSR.

Pros and Cons

It may be tempting to look through these options, find one that you think is the best, and overfit yourself into a conclusion that one is superior to all the others. That said, each of these methods has its strengths and weaknesses.

Tool	Pros	Cons
Vanilla HTM	Fast	Hard to scale
Client Side Rendering (CSR)	Easy to scale Ease of engineering	Slow JS initialization SEO concerns
Server Server Render (SSR)	Query based optimization Better SEO handling Usable without client JS enabled	Heavier server load Needs specific server More dev effort than CSR
Compile Time Rendering (SSG)	Layout based optimization Better SEO handling Usable without client JS enabled CDN hostable	No access to query data More dev effort than CSR

Consider each of these utilities a tool in your toolbox. You may be working on a landing page for a client where SSG would fit best — working on an internal SPA that only has a limited budget allocated to it? Client-side rendering might be your best bet there! Are you working on a public-facing app that highly depends on real-time data? SSR's for you! Each of these has its utility in their problem-space. It's good to keep that in mind when selecting one for your next project.

In fact, if you're using a framework that supports more than one of these methods (like NextJS does as-of version 9.3), knowing which of these utilities to use for which pages can be critical for optimizing your app.

A Note Regarding Performance Benchmarks

I was once tasked with migrating a landing page with an associated blog from CSR to use SSG. Once I had done so, however, I noticed that my Lighthouse score had gone down despite my page rendering a much more useful initial page significantly faster than it'd taken for my app's spinner to go away.

"Why did my lighthouse scores go down when using SSG?"

I wasn't able to find an answer quickly, but eventually, I found out. Lighthouse scores based on many factors. One of those factors is "time until fully loaded." Here's where my problems came into play:

When doing server-side rendering or static site generation, you're shipped HTML and CSS. Then, to ensure your app fully works and is interactive after the intial load, it will preload the framework you built your site in. Once your framework preloads, it will oftentimes re-render the initial page that was shipped with HTML/CSS. Because the page is both pre-hydrated and responsible for initializing the framework afterwards on the client machine, your benchmarks may potentially suffer, despite the experience being better.

While it's technically possible to do things like compile React entirely out of an exported NextJS site, it's far from trivial and doesn't fit most usage very well. It's certainly a harder mental model at the very least.

Here's an anecdote that was told to me by Aaron Frost (the creator of the SSG utility Scully) about this scenario:

There once was an airport that had low ratings from an audit company that rated an airport's speed and quality. The biggest complaint from the rating was that the time it took to get un-boarded and to the baggage claim was too long. One of the reasons for this was due to how the planes were landing. When the planes landed, they were far away from the baggage claim, forcing their customers to walk a long distance before getting to the baggage claim.

The airport decided to re-arrange how their planes landed in the future. While the customers seemed to be much happier overall, they received a lower rating on their next audit. This clearly contradicted the claims of their fliers. It turns out that the way the auditor was rating the airport was how much downtime they had before receiving a bag. While the others enjoyed reading articles on their phones during the downtime, the auditor was able to start their timer sooner as a result of walking for a shorter period of time.

All in all, while lighthouse might score you lower, you can rest assured that your customers will be happier knowing that you have a much more useful interaction on first glance than a site that doesn't use something like SSG.

Conclusion

As mentioned previously, having SSR and SSG in your toolbox are incredibly useful to have at your disposal. While not appropriate for every application, those that are tend to see great advantages from the concepts. Hopefully we've been able to provide a bit of insight that'll spark further learning and research into them.

Now you have familiarity with what SSR and SSG are, maybe you want to take a stab at implementing it? We took a look recently at creating a blog using an Angular SSG solution called Scully.

As always, let us know what you think down in the comments below or in our community Discord.

What is Reconciliation and the Virtual DOM (VDOM)?

Corbin Crutchley — Fri, 23 Feb 2024 16:00:00 +0000

In our last post we introduced how a modern frontend framework like React, Angular, or Vue are able to make your JavaScript state easier to sync to the DOM using "Reactivity".

Towards the end of that post, I touched on how each of these frameworks' mechanisms for reactivity work under-the-hood through external links.

One of those mechanisms used by frameworks like React and Vue is called the "Virtual DOM" (Also known as the "VDOM") and use a process called "Reconciliation" to reflect the changes made to this "VDOM" to the real DOM.

Let's take a look at how this works in practical terms.

What is the Virtual DOM (VDOM)?

In a broad stroke, the virtual DOM (VDOM) is a reflection of the code you've written in your framework that eventually gets mirrored to the DOM. This is in order to make sure that updates to your JavaScript state are duplicated into the DOM via reactivity.

Too terminology heavy? No problem, here's an example.

Let's say that you have a bit of HTML:

<ul>
    <li><p>One</p></li>
    <li><p>One</p></li>
    <li><p>One</p></li>
</ul>

This might create a DOM tree that looks similar to the following:

If you need a refresher on how the DOM works, check out our post on the topic.

Similarly, if you write the following JSX:

const App = () => {
    return (
        <ul>
            <li><p>One</p></li>
            <li><p>One</p></li>
            <li><p>One</p></li>
        </ul>
    )
}

You'll end up with a VDOM that mirrors the markup you've written in JSX. This JSX is then reflected to the DOM itself:

The process of how these changes are mirrored is called "Reconciliation".

What is "Reconciliation"?

Reconciliation is the process of reflecting changes from a frameworks' virtual DOM into the DOM via a three-step process:

1) Listening for changes to the state
2) Diffing the changes made to the VDOM
3) Committing the changes from the VDOM to the DOM

What is the `key` property?

While this process of reconciliation might seem simple at first, it can get quite complex. For example, consider how a list might be handled:

import { useState } from 'react';

const fakeNames = [
  'Gulgowski',
  'Johnston',
  'Nader',
  'Flatley',
  'Lemke',
  'Stokes',
  'Simonis',
  'Little',
  'Baumbach',
  'Spinka',
];

let id = 0;

function createPerson() {
  return {
    id: ++id,
    name: fakeNames[Math.floor(Math.random() * fakeNames.length)],
  };
}

export default function App() {
  const [list, setList] = useState([
    createPerson(),
    createPerson(),
    createPerson(),
  ]);

  function addPersonToList() {
    const newList = [...list];
    // Insert new friend at random location
    newList.splice(
      Math.floor(Math.random() * newList.length),
      0,
      createPerson()
    );
    setList(newList);
  }

  return (
    <div>
      <h1>My friends</h1>
      <button onClick={addPersonToList}>Add friend</button>
      <ul>
        {list.map((person) => (
          <li>
            <label>
              <div>{person.name} notes</div>
              <input />
            </label>
          </li>
        ))}
      </ul>
    </div>
  );
}

Here, we're storing a list of our friends and allowing the user to add to this list by pressing a button. We even have a little place to store notes about your friends!

But notice what happens to those notes when someone gets added to the start of the list:

https://unicorn-utterances.com/content/blog/what-is-reconciliation-and-the-vdom/incorrect-user.mp4

See how the note about Little is now assigned to the wrong person.

This is because React needs some way to identify which element is which in a list. By default, this is the index of the list item - which is why our note about Little (whom was originally at the top of the list) is still at the top of the list when someone else is added, despite that not being correct.

Without this default behavior, the inputs inside of the list would all disappear every time the user added to the list, as it wouldn't know to avoid re-rendering the contents of the DOM on existing items:

To fix this, we just need to explicitly tell React which user is which in the list using a special key property:

<ul>
    {list.map((person) => (
      <li key={person.id}>
        <label>
          <div>{person.name} notes</div>
          <input />
        </label>
      </li>
    ))}
</ul>

Conclusion

In this series, we've explored how React handles reactivity and how it uses the Virtual DOM and reconciliation to make reactivity work.

These two combined build the foundation for how React works behind the scenes. In the next few posts, starting with "What is server-side rendering (SSR) and static site generation (SSG)", we'll explore how React has gradually evolved past the typical client-side rendering process and into the server.

Eventually, this series will show you how to use React Server Actions in-depth and how you can utilize your React knowledge to become a full-stack developer.

Sound like fun? We hope so! Join us in our Discord and let us know what other topics you'd like to see on the site.

DEV Community: Corbin Crutchley

Merging the "This Is" Community into "Playful Programming"

Introducing "This is Learning" (TiL)

Introducing "Playful Programming" (PFP)

Details about the merger

Our future

Thank you

Challenges in writing a programming book

Writing a book is hard

Developers glance, not read

Keep your headings clearly named

Code will be copy+pasted

Developers seem to prefer video content

Conclusion

Advice for New Twitch Streamers

Streaming Strategy

Essential Equipment

Culminating Community

Managing Moderation

Generating Growth

Branded Broadcasts

Conclusion

How Binary and Hexadecimal Work: An introduction to non-decimal number systems

Decimal

Binary

Hexadecimal

Why 256?

To Binary

Applications

CSS Colors

Text Encoding

Conclusion

TypeScript Intermediates - Type Generics

The Problem

Potential Solution 1: Unions

Potential Solutions Disclaimer

Potential Solution 2: Function Overloading

Potential Solution 3: Any

The Real Solution

Okay, but Why?

Non-Function Generics

Okay, but why-er?

Restricting The Types

Broaden Your Horizons

Conclusion

Introduction to TypeScript — What is TypeScript?

What is TypeScript?

Doesn't JavaScript Have Types Already?

Why TypeScript?

Type Safety

Developer Quality of Life

Improved Tooling Support

3rd Party Library Support

Community Hosting

Documented Types

Type Information

What isn't TypeScript

It's Not the Tower You Think It Is

Logic != Typings

Typing Mishaps Happen

Don't Forget To Document

Conclusion

What is React's useFormState and useFormStatus?

What is useFormStatus?

useFormStatus usage with server actions

What is useFormState?

useFormState usage with server actions

useFormState usage without client-side JavaScript

How to use useFormState and useFormStatus together

Conclusion

What are React Server Actions?

What are React <form> actions?

What are React Server Actions?

What is "use server"?

Adding in client-side components

What happens if you don't mark a function with "use server"?

Are synchronous functions allows in React server actions?

Can you define server actions in a client component file?

Why are React Server Actions significant?

Conclusion

Why `256`?

What is `useFormStatus`?

`useFormStatus` usage with server actions

What is `useFormState`?

`useFormState` usage with server actions

`useFormState` usage without client-side JavaScript

How to use `useFormState` and `useFormStatus` together

What are React `<form>` actions?

What is `"use server"`?

What happens if you don't mark a function with `"use server"`?

What is the React `use` Hook?

What is the `<Suspense>` component?

How do I handle rejected promises in `<Suspense>`?

Using `use` on the server

What is `"use client"`?

What is the `key` property?