npm package: @o-town/local.dev
Description: Expose your local website to the internet instantly — no config, no signup.
Author: local.dev contributors
Latest version: 1.2.0

# local.dev

> Expose your local website to the internet — instantly. No signup, no config.

```
npx local.dev 3000
```

---

## Install

```bash
npm install -g @o-town/local.dev
```

Or use without installing:

```bash
npx @o-town/local.dev 3000
```

---

## CLI Usage

```
npx local.dev [port] [options]
```

### Arguments

| Argument | Description              | Default |
|----------|--------------------------|---------|
| `port`   | Local port to expose     | `3000`  |

### Options

| Flag                  | Alias | Description                              |
|-----------------------|-------|------------------------------------------|
| `--subdomain`         | `-s`  | Request a custom subdomain               |
| `--host`              | `-H`  | Local host to tunnel (default: localhost)|
| `--qr`                | `-q`  | Show QR code for the public URL          |
| `--open`              | `-o`  | Open tunnel URL in your browser          |
| `--print-requests`    | `-r`  | Log incoming HTTP requests               |
| `--help`              | `-h`  | Show help                                |
| `--version`           | `-v`  | Show version number                      |

### Examples

```bash
# Expose port 3000
npx local.dev 3000

# Expose port 8080 with a custom subdomain
npx local.dev 8080 --subdomain myapp

# Show QR code (great for mobile testing)
npx local.dev 3000 --qr

# Open tunnel URL in browser + log requests
npx local.dev 3000 --open --print-requests

# Expose a non-localhost server
npx local.dev 3000 --host 192.168.1.10
```

---

## Programmatic API

You can also use `local.dev` as a Node.js library:

```js
const { tunnel } = require('@o-town/local.dev');

async function main() {
  // Simple: just pass a port
  const t = await tunnel(3000);
  console.log('Public URL:', t.url);

  // Stop the tunnel when done
  t.close();
}

main();
```

### With options

```js
const t = await tunnel({
  port: 8080,
  subdomain: 'myapp',
  host: 'localhost',
  printRequests: true,
});

console.log(t.url); // https://myapp.loca.lt

t.on('request', (info) => {
  console.log(info.method, info.path, info.statusCode);
});

t.on('close', () => {
  console.log('Tunnel closed');
});
```

### API Reference

#### `tunnel(port, [options])` → `Promise<TunnelHandle>`
#### `tunnel(options)` → `Promise<TunnelHandle>`

**Options:**

| Property        | Type    | Description                          |
|-----------------|---------|--------------------------------------|
| `port`          | number  | **Required.** Local port to expose   |
| `host`          | string  | Local host (default: `'localhost'`)  |
| `subdomain`     | string  | Requested subdomain                  |
| `printRequests` | boolean | Log requests (default: `false`)      |

#### `TunnelHandle`

| Property/Method | Description                  |
|-----------------|------------------------------|
| `.url`          | The public HTTPS URL         |
| `.close()`      | Close the tunnel             |
| `.on('request', cb)` | Fired on each HTTP request |
| `.on('close', cb)` | Fired when tunnel closes   |
| `.on('error', cb)` | Fired on tunnel errors     |

---

## How it works

`local.dev` creates a secure tunnel from a public URL to your local machine using the [localtunnel](https://github.com/localtunnel/localtunnel) protocol. Incoming requests hit the public URL and are proxied through to your local server — no port forwarding or firewall changes needed.

---

## License

MIT

---

## Publishing

```bash
npm install
npm login
npm publish --access public
```

> Scoped packages require `--access public` to be visible on the npm registry.