From 6d4361308ccf1d83c59687335f2671b491401d60 Mon Sep 17 00:00:00 2001 From: Chris Date: Tue, 10 Dec 2024 12:01:32 +0100 Subject: [PATCH] chore: update readme --- README.md | 151 ++++++++++++++++-------------------------------------- 1 file changed, 43 insertions(+), 108 deletions(-) diff --git a/README.md b/README.md index 4ef987c..073f1f1 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -

Social Card of this repo

+

Social Card of this repo

[![npm version][npm-version-src]][npm-version-href] [![GitHub Actions][github-actions-src]][github-actions-href] @@ -8,148 +8,83 @@ # A Better Developer Experience -> A zero-config reverse proxy for local development with SSL support, custom domains, and more. +> A zero-config local tunnel that's simple, lightweight, and secure. ## Features -- Simple, lightweight Reverse Proxy -- Custom Domains _(with wildcard support)_ -- Zero-Config Setup -- SSL Support _(HTTPS by default)_ -- Auto HTTP-to-HTTPS Redirection -- Self `/etc/hosts` Management +- Simple, lightweight local tunnel +- Security built-in, including HTTPS +- IAC, self-hostable _(via AWS)_ +- Custom subdomains +- CLI & Library ## Install ```bash -bun install -d @stacksjs/rpx +bun install -d localtunnels ``` ## Get Started -There are two ways of using this reverse proxy: _as a library or as a CLI._ +There are two ways of using this local tunnel: _as a library or as a CLI._ ### Library Given the npm package is installed: ```ts -import type { TlsConfig } from '@stacksjs/rpx' -import { startProxy } from '@stacksjs/rpx' - -export interface ReverseProxyConfig { - from: string // domain to proxy from, defaults to localhost:3000 - to: string // domain to proxy to, defaults to stacks.localhost - cleanUrls?: boolean // removes the .html extension from URLs, defaults to false - https: boolean | TlsConfig // automatically uses https, defaults to true, also redirects http to https - etcHostsCleanup?: boolean // automatically cleans up /etc/hosts, defaults to false - verbose: boolean // log verbose output, defaults to false -} +import type { LocalTunnelConfig } from 'localtunnels' +import { startLocalTunnel } from 'localtunnels' -const config: ReverseProxyOptions = { - from: 'localhost:3000', - to: 'my-docs.localhost', - cleanUrls: true, - https: true, - etcHostsCleanup: true, +const config: LocalTunnelConfig = { + from: 'localhost:5173', + domain: 'stacksjs.dev', // optional, defaults to the stacksjs.dev domain + subdomain: 'test', // optional, uses a random subdomain by default + verbose: true, // optional, defaults to false } -startProxy(config) +startLocalTunnel(config) ``` -In case you are trying to start multiple proxies, you may use this configuration: +You may als use a configuration file: ```ts -// reverse-proxy.config.{ts,js} -import type { ReverseProxyOptions } from '@stacksjs/rpx' -import os from 'node:os' -import path from 'node:path' - -const config: ReverseProxyOptions = { - https: { // https: true -> also works with sensible defaults - caCertPath: path.join(os.homedir(), '.stacks', 'ssl', `stacks.localhost.ca.crt`), - certPath: path.join(os.homedir(), '.stacks', 'ssl', `stacks.localhost.crt`), - keyPath: path.join(os.homedir(), '.stacks', 'ssl', `stacks.localhost.crt.key`), - }, - - etcHostsCleanup: true, - - proxies: [ - { - from: 'localhost:5173', - to: 'my-app.localhost', - cleanUrls: true, - }, - { - from: 'localhost:5174', - to: 'my-api.local', - }, - ], - - verbose: true, +// tunnel.config.{ts,js} +import type { LocalTunnelConfig } from '@stacksjs/localtunnels' + +const config: LocalTunnelConfig = { + from: 'localhost:5173', + domain: 'stacksjs.dev', // optional, defaults to the stacksjs.dev domain + subdomain: 'test', // optional, uses a random subdomain by default + verbose: true, // optional, defaults to false } export default config ``` -### CLI - -```bash -rpx --from localhost:3000 --to my-project.localhost -rpx --from localhost:8080 --to my-project.test --keyPath ./key.pem --certPath ./cert.pem -rpx --help -rpx --version -``` - -## Configuration - -The Reverse Proxy can be configured using a `reverse-proxy.config.ts` _(or `reverse-proxy.config.js`)_ file and it will be automatically loaded when running the `reverse-proxy` command. -```ts -// reverse-proxy.config.{ts,js} -import type { ReverseProxyOptions } from '@stacksjs/rpx' -import os from 'node:os' -import path from 'node:path' - -const config: ReverseProxyOptions = { - from: 'localhost:5173', - to: 'stacks.localhost', - https: { - domain: 'stacks.localhost', - hostCertCN: 'stacks.localhost', - caCertPath: path.join(os.homedir(), '.stacks', 'ssl', `stacks.localhost.ca.crt`), - certPath: path.join(os.homedir(), '.stacks', 'ssl', `stacks.localhost.crt`), - keyPath: path.join(os.homedir(), '.stacks', 'ssl', `stacks.localhost.crt.key`), - altNameIPs: ['127.0.0.1'], - altNameURIs: ['localhost'], - organizationName: 'stacksjs.org', - countryName: 'US', - stateName: 'California', - localityName: 'Playa Vista', - commonName: 'stacks.localhost', - validityDays: 180, - verbose: false, - }, - verbose: false, -} +_Then run:_ -export default config +```bash +./localtunnels start ``` -_Then run:_ +### CLI ```bash -./rpx start +localtunnels start --from localhost:5173 --subdomain test --verbose +localtunnels --help +localtunnels --version ``` -To learn more, head over to the [documentation](https://reverse-proxy.sh/). +To learn more, head over to the [documentation](https://localtunnels.sh/). ## Testing @@ -159,7 +94,7 @@ bun test ## Changelog -Please see our [releases](https://github.com/stacksjs/stacks/releases) page for more information on what has changed recently. +Please see our [releases](https://github.com/stacksjs/localtunnels/releases) page for more information on what has changed recently. ## Contributing @@ -200,10 +135,10 @@ The MIT License (MIT). Please see [LICENSE](https://github.com/stacksjs/stacks/t Made with 💙 -[npm-version-src]: https://img.shields.io/npm/v/@stacksjs/rpx?style=flat-square -[npm-version-href]: https://npmjs.com/package/@stacksjs/rpx -[github-actions-src]: https://img.shields.io/github/actions/workflow/status/stacksjs/rpx/ci.yml?style=flat-square&branch=main -[github-actions-href]: https://github.com/stacksjs/rpx/actions?query=workflow%3Aci +[npm-version-src]: https://img.shields.io/npm/v/localtunnels?style=flat-square +[npm-version-href]: https://npmjs.com/package/localtunnels +[github-actions-src]: https://img.shields.io/github/actions/workflow/status/stacksjs/localtunnels/ci.yml?style=flat-square&branch=main +[github-actions-href]: https://github.com/stacksjs/localtunnels/actions?query=workflow%3Aci - +