deno.land / x / manual@v1.28.2 / getting_started / first_steps.md
This page contains some examples to teach you about the fundamentals of Deno.
This document assumes that you have some prior knowledge of JavaScript,
especially about async
/await
. If you have no prior knowledge of JavaScript,
you might want to follow a guide
on the basics of JavaScript
before attempting to start with Deno.
Deno is a runtime for JavaScript/TypeScript which tries to be web compatible and use modern features wherever possible.
Browser compatibility means a Hello World
program in Deno is the same as the
one you can run in the browser.
Create file locally called first_steps.ts
and copy and paste the code line
below:
console.log("Welcome to Deno!");
Now to run the program from the terminal:
deno run first_steps.ts
Deno also has the ability to execute scripts from URLs. Deno
hosts a library of example code, one
of which is a Hello World
program. To run that hosted code, do:
deno run https://deno.land/std@0.103.0/examples/welcome.ts
Many programs use HTTP requests to fetch data from a webserver. Let's write a
small program that fetches a file and prints its contents out to terminal. Just
like in the browser you can use the web standard
fetch
API to
make HTTP calls.
In the first_steps.ts
file you created above, paste the code below:
const url = Deno.args[0];
const res = await fetch(url);
const body = new Uint8Array(await res.arrayBuffer());
await Deno.stdout.write(body);
Let's walk through what this application does:
url
constant.res
constant.ArrayBuffer
,
await the response, and convert it into a
Uint8Array
to store in the body
constant.body
constant to stdout
.Try it out:
deno run first_steps.ts https://yirenlu.com/
or, from URL:
deno run https://deno.land/std@$STD_VERSION/examples/curl.ts https://example.com
You will see this program returns an error regarding network access so what did we do wrong? You might remember from the introduction that Deno is a runtime which is secure by default. This means you need to explicitly give programs the permission to do certain 'privileged' actions, such as access the network.
Try it out again with the correct permission flag:
deno run --allow-net=yirenlu.com first_steps.ts https://yirenlu.com/
or, from URL:
deno run --allow-net=example.com https://deno.land/std@$STD_VERSION/examples/curl.ts https://example.com
Deno also provides APIs which do not come from the web. These are all contained
in the Deno
global. You can find documentation for these built-in APIs here at
/api
.
Filesystem APIs for example do not have a web standard form, so Deno provides its own API.
In this program each command-line argument is assumed to be a filename, the file is opened, and printed to stdout.
import { copy } from "https://deno.land/std@$STD_VERSION/streams/conversion.ts";
const filenames = Deno.args;
for (const filename of filenames) {
const file = await Deno.open(filename);
await copy(file, Deno.stdout);
file.close();
}
The copy()
function here actually makes no more than the necessary
kernel→userspace→kernel copies. That is, the same memory from which data is read
from the file, is written to stdout. This illustrates a general design goal for
I/O streams in Deno.
Again, here, we need to give --allow-read access to the program.
Try the program:
# macOS / Linux
deno run --allow-read https://deno.land/std@$STD_VERSION/examples/cat.ts /etc/hosts
# Windows
deno run --allow-read https://deno.land/std@$STD_VERSION/examples/cat.ts "C:\Windows\System32\Drivers\etc\hosts"
One of the most common usecases for Deno is building an HTTP Server.
http_server.ts
import { serve } from "https://deno.land/std@0.157.0/http/server.ts";
const port = 8080;
const handler = async (request: Request): Promise<Response> => {
const resp = await fetch("https://api.github.com/users/denoland", {
// The init object here has an headers object containing a
// header that indicates what type of response we accept.
// We're not specifying the method field since by default
// fetch makes a GET request.
headers: {
accept: "application/json",
},
});
return new Response(resp.body, {
status: resp.status,
headers: {
"content-type": "application/json",
},
});
};
console.log("Listening on http://localhost:8000");
serve(handler);
Let's walk through what this program does.
std/http
(standard library)url_join
, which is hosted at
deno.land/x. (Since it can be unwieldy to import URLs
everywhere, best practice is actually to import and re-export your external
libraries into a central deps.ts
file. For more details read
here).Response
. The handler function can
be asynchronous (it may return a Promise
).url_join
to join together a complex Github
url.fetch
to fetch the url.serve
with the
handler.Now run the server. Note that you need to give both network and write permissions.
deno run --allow-net --allow-write http_server.ts
With the server listening on port 8000
, make a GET request to that endpoint.
curl http://localhost:8000
You will see a JSON response from the Deno Github page.
You can find more examples in the Examples chapter and at Deno by Example.
Version Info