Location API

Deno supports the location global from the web. Please read on.

Location flag

There is no “web page” whose URL we can use for a location in a Deno process. We instead allow users to emulate a document location by specifying one on the CLI using the --location flag. It can be a http or https URL.

// deno run --location https://example.com/path main.ts

console.log(location.href);
// "https://example.com/path"

You must pass --location <href> for this to work. If you don’t, any access to the location global will throw an error.

// deno run main.ts

console.log(location.href);
// error: Uncaught ReferenceError: Access to "location", run again with --location <href>.

Setting location or any of its fields will normally cause navigation in browsers. This is not applicable in Deno, so it will throw in this situation.

// deno run --location https://example.com/path main.ts

location.pathname = "./foo";
// error: Uncaught NotSupportedError: Cannot set "location.pathname".

Extended usage

On the web, resource resolution (excluding modules) typically uses the value of location.href as the root on which to base any relative URLs. This affects some web APIs adopted by Deno.

Fetch API

// deno run --location https://api.github.com/ --allow-net main.ts

const response = await fetch("./orgs/denoland");
// Fetches "https://api.github.com/orgs/denoland".

The fetch() call above would throw if the --location flag was not passed, since there is no web-analogous location to base it onto.

Worker modules

// deno run --location https://example.com/index.html --allow-net main.ts

const worker = new Worker("./workers/hello.ts", { type: "module" });
// Fetches worker module at "https://example.com/workers/hello.ts".

Only use if necessary

For the above use cases, it is preferable to pass URLs in full rather than relying on --location. You can manually base a relative URL using the URL constructor if needed.

The --location flag is intended for those who have some specific purpose in mind for emulating a document location and are aware that this will only work at application-level. However, you may also use it to silence errors from a dependency which is frivolously accessing the location global.