How to use top-level await in Node.js

Hey friends. I just learned something cool about Node.js and I thought I'm going to share it with you. If you were riding Node.js, you might've come across situations in which you're writing in Node.js script to maybe batch rename some files or do some image processing or fetch some data from an API asynchronously.

Let's have a look at an example, and then I'm going to show you what I learned, what you see here is a quick and easy project that uses the got npm package, which you can use to do HTTP requests. And then it's fetching some data from the dog.ceo API, and then it's logging this out. So let's run this script very, very quickly.

So you see here that, that it returns a status and a message and a random dog picture. So, but now we have to 2021 and you see here that I'm using the then syntax when dealing with promises. Usually these days, everybody is all about async and await. So how could you use async and await in a function or in a script like this?

Let's just refactor that for a moment. So what we could do is we could do data and we await the got function with the json method, and then we're gonna do console log and log out data. So let's give that a try. When I now run this. You will see that Node.js is throwing an error because await is only valid in an proper async function.

What you had to do usually is to write a function, let's call it main and let's make that async and let's move these kinds of things around to have them in there and let's run main. So let's give that another try and let's see what happens. Cool. So we get, again, our asynchronous promise-based HTTP response.

The problem here now is that we really, we include now, a function that it's only job is to enable us to use await and today I learned that in Node.js since version 14, there's actually top-level await available, which means that we can drop these lines and can make our scripts a little bit more straightforward.

Let me show you how that works. I just removed the async function, wrapping everything. So now when we run this script again, you will see that, well, we are still having the same error. Obviously. So the thing is that top-level await in Node.js is only available in ECMAScript modules. There are two ways to do that.

What we can do is we can, first of all, rename this file to use the file extension mjs, which stands for module JavaScript. So, if you're now dealing with the JavaScript module, we have to first, change our require statements. These are not available in ECMAScript modules, and we're changing this to import got from "got".

And let's now give that a try. And right. It's not called index.js anymore. So let's call that index.mjs and you see there that top-level await. So calling await without having an asynchronous function wrapper is now available. And I think that is pretty, pretty sweet. Let me show you another way to do that.

Let's rename this file back again to JavaScript, and let's just see if it still throws an error. It does. What we can do, additionally, is we could also go if you're having a project that includes a package.json, and we can also go in here and we can define a type of this whole package or of this whole repository here.

And we can say "type": "module". These are the two ways on how to enable ECMAScript modules in Node.js. So when we now run "node index.js", we see that this file, our index.js file is now treated as an ECMAScript module. And I think this is pretty, pretty sweet. If you want to learn more about that, I wrote a quick blog post that you can find in the description below.

YouTubers does have to do that. Let me know what you think about that and see you next time.