Frequently Asked Questions

Where can I find full API documentation?

One of the advantages of Deno (and TypeScript) is that it is quite easy to inline documentation in the code. The doc.deno.land site provides all the documentation directly from the source code. The documentation for oak’s mod.ts contains all the APIs that are considered “public”. You can also get an output of the documentation directly via deno doc https://deno.land/x/oak/mod.ts to your console.

How do I use the native HTTP server in Deno?

As of Deno 1.9, Deno has a native HTTP server versus the std/http previously. oak is designed to automatically use the native HTTP server if it detects it. Currently the native HTTP server APIs are unstable and therefore require the --unstable flag on the command line, for example:

> deno run --allow-net --unstable server.ts

Where is ctx.host, ctx.path, ctx.querystring, etc.?

Instead of creating “aliases” to lots of different parts of the requested URL, oak provides a ctx.request.url which is a browser standard instance of URL which contains all of the parts of the requested URL in a single object.

How do I close a server?

Oak uses the browser standard AbortController for closing a server. You pass the .signal of the controller as one of the listen options, and you would then .abort() on the controller when you want the server to close. For example:

import { Application } from "https://deno.land/x/oak/mod.ts";

const app = new Application();

const controller = new AbortController();
const { signal } = controller;

app.use((ctx) => {
  // after first request, the server will be closed
  controller.abort();
});

await app.listen({ port: 8000, signal });
console.log("Server closed.");

How to get access to the “raw” request body?

When requesting a body, use ctx.request.body({ type: "reader" }). This will resolve with the Deno.Reader interface in the value property of the response. You can then read from this interface the “raw” body content.

How to perform a redirect?

In the ctx.response call the .redirect() method. For example:

import { Application } from "https://deno.land/x/oak/mod.ts";

const app = new Application();

app.use((ctx) => {
  ctx.response.redirect("https://deno.land/");
});

await app.listen({ port: 8000 });

The symbol REDIRECT_BACK can be used to redirect the requestor back to the to the referrer (if the request’s Referer header has been set), and the second argument can be used to provide a “backup” if there is no referrer. For example:

import { Application, REDIRECT_BACK } from "https://deno.land/x/oak/mod.ts";

const app = new Application();

app.use((ctx) => {
  ctx.response.redirect(REDIRECT_BACK, "/home");
});

await app.listen({ port: 8000 });

How do I pass custom properties/state around?

The Application and the Context share an object property named .state. This is designed for making custom application state available when processing requests.

It can also be strongly typed in TypeScript by using generics.

For example, if you wanted to create middleware that set a user ID in requests, you would do something like this:

import { Application } from "https://deno.land/x/oak/mod.ts";

interface MyState {
  userId: number;
}

const app = new Application<MyState>();

app.use(async (ctx, next) => {
  // do whatever checks to determine the user ID
  ctx.state.userId = userId;
  await next();
  delete ctx.state.userId; // cleanup
});

app.use(async (ctx, next) => {
  // now the state.userId will be set for the rest of the middleware
  ctx.state.userId;
  await next();
});

await app.listen();