@webcontainer/env

> ⚠️ Important ⚠️
>
> We strongly recommend that you update to version 1.1.0 or greater as we
> recently introduced a breaking change in WebContainer, making older versions of
> @webcontainer/api generate invalid HostURL.href and HostURL.hostname
> when those methods are called inside a WebContainer.

Set of environment utilities for WebContainers.

Install

``shell
$ npm install @webcontainer/env
`

API

$3

Returns a boolean indicating whether the program runs in a WebContainer.

$3

The HostURL class represents a host specific URL. It can be used to parse a regular URL, such as
http://localhost:1234, into a HostURL. Only if the program is executed in a WebContainer,
the hostname is resolved to a WebContainer hostname, e.g. http://blitz--1234.local.webcontainer.io.
This can be useful to create platform-dependent OAuth callback URLs.

#### HostURL.port(): string (getter)

#### HostURL.hash(): string (getter)

#### HostURL.host(): string (getter)

#### HostURL.hostname(): string (getter)

#### HostURL.href(): string (getter)

#### HostURL.origin(): string (getter)

#### HostURL.username(): string (getter)

#### HostURL.password(): string (getter)

#### HostURL.pathname(): string (getter)

#### HostURL.protocol(): string (getter)

#### HostURL.search(): string (getter)

#### HostURL.searchParams(): URLSearchParams (getter)

#### HostURL.parse(url: string | URL): HostURL (static method)

Parses a url into a HostURL. On local this is a no-op but when running in a WebContainer it resolves localhost
to a WebContainer hostname.

Example

`js
import { HostURL, isWebContainer } from '@webcontainer/env';

const hostURL = HostURL.parse('http://localhost:1234');

/**
* Note that this branching would not be necessary as the host URL gets parsed
* and resolved automatically through HostURL.parse() (see above). So href
* will return a different value depending on the environment. This is illustrated
* with the following if statement.
*/
if (isWebContainer()) {
console.log(hostURL.href); // http://blitz--1234.local.webcontainer.io
} else {
console.log(hostURL.href); // http://localhost:1234
}
`

#### HostURL.update(change: Partial): HostURL (method)

Updates the HostURL.

##### change

Object containing the URL changes. Note that some properties are immutable (read-only), e.g. origin or searchParams. When updating the port it automatically updates the host.

Type: Partial

`js
interface UpdateableURLProperties {
hash: string;
host: string;
hostname: string;
href: string;
password: string;
pathname: string;
port: string;
protocol: string;
search: string;
username: string;
}
`

#### HostURL.toString(): string (method)

Stringifies the HostURL. It is effectively a read-only version of HostURL.href.

#### HostURL.toJSON(): string (method)

Returns a string containing a serialized version of the HostURL`.