{"id":26093858,"url":"https://github.com/ngrok/ngrok-javascript","last_synced_at":"2025-04-06T16:09:54.222Z","repository":{"id":65728150,"uuid":"598334001","full_name":"ngrok/ngrok-javascript","owner":"ngrok","description":"Embed ngrok secure ingress into your Node.js apps with a single line of code.","archived":false,"fork":false,"pushed_at":"2025-03-27T00:24:16.000Z","size":2537,"stargazers_count":110,"open_issues_count":5,"forks_count":15,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-04-03T01:44:38.741Z","etag":null,"topics":["networking","ngrok","nodejs","reverse-proxy"],"latest_commit_sha":null,"homepage":"https://ngrok.com","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ngrok.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-APACHE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-02-06T22:17:47.000Z","updated_at":"2025-03-27T00:24:18.000Z","dependencies_parsed_at":"2024-01-04T22:40:38.132Z","dependency_job_id":"c8a9fbb0-853b-4504-b581-b413f4ef5f4f","html_url":"https://github.com/ngrok/ngrok-javascript","commit_stats":null,"previous_names":["ngrok/ngrok-js","ngrok/ngrok-javascript","ngrok/ngrok-nodejs"],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ngrok%2Fngrok-javascript","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ngrok%2Fngrok-javascript/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ngrok%2Fngrok-javascript/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ngrok%2Fngrok-javascript/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ngrok","download_url":"https://codeload.github.com/ngrok/ngrok-javascript/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246922232,"owners_count":20855343,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["networking","ngrok","nodejs","reverse-proxy"],"created_at":"2025-03-09T12:05:53.194Z","updated_at":"2025-04-06T16:09:54.204Z","avatar_url":"https://github.com/ngrok.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Javascript SDK for ngrok\n\n[![npm.rs][npm-badge]][npm-url]\n[![MIT licensed][mit-badge]][mit-url]\n[![Apache-2.0 licensed][apache-badge]][apache-url]\n[![Continuous integration][ci-badge]][ci-url]\n\n[npm-badge]: https://img.shields.io/npm/v/@ngrok/ngrok.svg\n[npm-url]: https://www.npmjs.com/package/@ngrok/ngrok\n[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg\n[mit-url]: https://github.com/ngrok/ngrok-rust/blob/main/LICENSE-MIT\n[apache-badge]: https://img.shields.io/badge/license-Apache_2.0-blue.svg\n[apache-url]: https://github.com/ngrok/ngrok-rust/blob/main/LICENSE-APACHE\n[ci-badge]: https://github.com/ngrok/ngrok-javascript/actions/workflows/ci.yml/badge.svg\n[ci-url]: https://github.com/ngrok/ngrok-javascript/actions/workflows/ci.yml\n\n`ngrok-javascript` is the official Node.js SDK for ngrok that requires no binaries. Quickly enable secure production-ready connectivity to your applications and services directly from your code.\n\n[ngrok](https://ngrok.com) is a globally distributed gateway that provides secure connectivity for applications and services running in any environment.\n\n# Installation\n\nUsing npm:\n\n```shell\nnpm install @ngrok/ngrok\n```\n\nUsing yarn:\n\n```shell\nyarn add @ngrok/ngrok\n```\n\nUsing pnpm:\n\n```shell\npnpm add @ngrok/ngrok\n```\n\n# Quickstart\n\n1. [Install `@ngrok/ngrok`](#installation)\n2. Export your [authtoken from the ngrok dashboard](https://dashboard.ngrok.com/get-started/your-authtoken) as `NGROK_AUTHTOKEN` in your terminal\n3. Add the following code to your application to establish connectivity via the [forward method](https://github.com/ngrok/ngrok-javascript/blob/main/examples/ngrok-forward-minimal.js) through port `8080` over `localhost`:\n\n    ```jsx\n    // Require ngrok javascript sdk\n    const ngrok = require(\"@ngrok/ngrok\");\n    // import ngrok from '@ngrok/ngrok' // if inside a module\n    \n    (async function() {\n      // Establish connectivity\n      const listener = await ngrok.forward({ addr: 8080, authtoken_from_env: true });\n    \n      // Output ngrok url to console\n      console.log(`Ingress established at: ${listener.url()}`);\n    })();\n\n    process.stdin.resume();\n    ```\n\nThat's it! Your application should now be available through the url output in your terminal. \n\n\u003e **Note**\n\u003e You can find more examples in [the examples directory](https://github.com/ngrok/ngrok-javascript/tree/main/examples).\n\n# Documentation\n\nA quickstart guide and a full API reference are included in the [ngrok-javascript documentation](https://ngrok.github.io/ngrok-javascript/).\n\n### Authorization\n\nTo use ngrok you'll need an authtoken. To obtain one, sign up for free at [ngrok.com](https://dashboard.ngrok.com/signup) and retrieve it from the [authtoken page of your ngrok dashboard](https://dashboard.ngrok.com/get-started/your-authtoken). Once you have copied your authtoken, you can reference it in several ways.\n\nYou can set it in the `NGROK_AUTHTOKEN` environment variable and pass `authtoken_from_env: true` to the [forward](https://ngrok.github.io/ngrok-javascript/functions/forward.html) method:\n\n```jsx\nawait ngrok.forward({ authtoken_from_env: true, ... });\n```\n\nOr pass the authtoken directly to the [forward](https://ngrok.github.io/ngrok-javascript/functions/forward.html) method:\n\n```jsx\nawait ngrok.forward({ authtoken: token, ... });\n```\n\nOr set it for all connections with the [authtoken](https://ngrok.github.io/ngrok-javascript/functions/authtoken.html) method:\n\n```jsx\nawait ngrok.authtoken(token);\n```\n\n### Connection\n\nThe [forward](https://ngrok.github.io/ngrok-javascript/functions/forward.html) method is the easiest way to start an ngrok session and establish a listener to a specified address. The [forward](https://ngrok.github.io/ngrok-javascript/functions/forward.html) method returns a promise that resolves to the public URL of the listener.\n\nWith no arguments the [forward](https://ngrok.github.io/ngrok-javascript/functions/forward.html) method will start an HTTP listener to `localhost` port `80`:\n\n```jsx\nconst ngrok = require(\"@ngrok/ngrok\");\n// import ngrok from '@ngrok/ngrok' // if inside a module\n\n(async function() {\n  console.log( (await ngrok.forward()).url() );\n})();\n```\n\nYou can pass the port number to forward on `localhost`:\n\n```jsx\nconst listener = await ngrok.forward(4242);\n```\n\nOr you can specify the host and port via a string:\n\n```jsx\nconst listener = await ngrok.forward(\"localhost:4242\");\n```\n\nMore options can be passed to the `forward` method to customize the connection:\n\n```jsx\nconst listener = await ngrok.forward({ addr: 8080, basic_auth: \"ngrok:online1line\" });\nconst listener = await ngrok.forward({ addr: 8080, oauth_provider: \"google\", oauth_allow_domains: \"example.com\" });\n```\n\nThe (optional) `proto` parameter is the listener type, which defaults to `http`. To create a TCP listener:\n\n```jsx\nconst listener = await ngrok.forward({ proto: 'tcp', addr: 25565 });\n```\n\nSee [Full Configuration](#full-configuration) for the list of possible configuration options.\n\n### Disconnection\n\nThe [close](https://ngrok.github.io/ngrok-javascript/classes/Listener.html#close) method on a listener will shut it down, and also stop the ngrok session if it is no longer needed. This method returns a promise that resolves when the listener is closed.\n\n```jsx\nconst listener = await ngrok.getListenerByUrl(url);\nawait listener.close();\n```\n\nOr use the [disconnect](https://ngrok.github.io/ngrok-javascript/functions/disconnect.html) method with the `url()` of the listener to close (or id() for a Labeled Listener):\n\n```jsx\nawait ngrok.disconnect(listener.url());\n```\n\nOr omit the `url()` to close all listeners:\n\n```jsx\nawait ngrok.disconnect();\n```\n\n### Listing Listeners\n\nTo list all current non-closed listeners use the [listeners](https://ngrok.github.io/ngrok-javascript/functions/listeners.html) method:\n\n```jsx\nconst listeners = await ngrok.listeners();\n```\n\n### Builders\n\nFor more control over Sessions and Listeners, the builder classes can be used.\n\nA minimal example using the builder class looks like [the following](https://github.com/ngrok/ngrok-javascript/blob/main/examples/ngrok-http-minimum.js):\n\n```jsx\nasync function create_listener() {\n  const session = await new ngrok.NgrokSessionBuilder().authtokenFromEnv().connect();\n  const listener = await session.httpEndpoint().listen();\n  console.log(\"Ingress established at:\", listener.url());\n  listener.forward(\"localhost:8081\");\n}\n```\n\nSee here for a [Full Configuration Example](https://github.com/ngrok/ngrok-javascript/blob/main/examples/ngrok-http-full.js)\n\n### TLS Backends\n\nAs of version `0.7.0` there is backend TLS connection support, validated by a filepath specified in the `SSL_CERT_FILE` environment variable, or falling back to the host OS installed trusted certificate authorities. So it is now possible to do this to forward:\n\n```jsx\nawait ngrok.forward({ addr: \"https://127.0.0.1:3000\", authtoken_from_env: true });\n```\n\nIf the service is using certs not trusted by the OS, such as self-signed certificates, add an environment variable like this before running: `SSL_CERT_FILE=/path/to/ca.crt`. There is also a `verify_upstream_tls: false` option to disable certification verification.\n\n### Async Programming\n\nAll methods return a `Promise` and are suitable for use in asynchronous\nprogramming. You can use callback chaining with `.then()` and `.catch()` syntax\nor the `await` keyword to wait for completion of an API call.\n\n#### Error Handling\n\nAll asynchronous functions will throw an error on failure to set up a session or listener,\nwhich can be caught and dealt with using try/catch or then/catch statements:\n\n```jsx\nnew ngrok.NgrokSessionBuilder().authtokenFromEnv().connect()\n    .then((session) =\u003e {\n        session.httpEndpoint().listen()\n            .then((tun) =\u003e {})\n            .catch(err =\u003e console.log('listener setup error: ' + err))\n    })\n    .catch(err =\u003e console.log('session setup error: ' + err))\n    .await;\n```\n\n### Full Configuration\n\nThis example shows [all the possible configuration items of ngrok.forward](https://github.com/ngrok/ngrok-javascript/blob/main/examples/ngrok-forward-full.js):\n\n```jsx\nconst listener = await ngrok.forward({\n  // session configuration\n  addr: `localhost:8080`, // or `8080` or `unix:${UNIX_SOCKET}`\n  authtoken: \"\u003cauthtoken\u003e\",\n  authtoken_from_env: true,\n  on_status_change: (addr, error) =\u003e {\n    console.log(`disconnected, addr ${addr} error: ${error}`);\n  },\n  session_metadata: \"Online in One Line\",\n  // advanced session connection configuration\n  server_addr: \"example.com:443\",\n  root_cas: \"trusted\",\n  session_ca_cert: fs.readFileSync(\"ca.pem\", \"utf8\"),  \n  // listener configuration\n  metadata: \"example listener metadata from javascript\",\n  domain: \"\u003cdomain\u003e\",\n  proto: \"http\",\n  proxy_proto: \"\", // One of: \"\", \"1\", \"2\"\n  schemes: [\"HTTPS\"],\n  labels: \"edge:edghts_2G...\",  // Along with proto=\"labeled\"\n  app_protocol: \"http2\",\n  // module configuration\n  basic_auth: [\"ngrok:online1line\"],\n  circuit_breaker: 0.1,\n  compression: true,\n  allow_user_agent: \"^mozilla.*\",\n  deny_user_agent: \"^curl.*\",\n  ip_restriction_allow_cidrs: [\"0.0.0.0/0\"],\n  ip_restriction_deny_cidrs: [\"10.1.1.1/32\"],\n  crt: fs.readFileSync(\"crt.pem\", \"utf8\"),\n  key: fs.readFileSync(\"key.pem\", \"utf8\"),\n  mutual_tls_cas: [fs.readFileSync('ca.crt', 'utf8')],\n  oauth_provider: \"google\",\n  oauth_allow_domains: [\"\u003cdomain\u003e\"],\n  oauth_allow_emails: [\"\u003cemail\u003e\"],\n  oauth_scopes: [\"\u003cscope\u003e\"],\n  oauth_client_id: \"\u003cid\u003e\",\n  oauth_client_secret: \"\u003csecret\u003e\",\n  oidc_issuer_url: \"\u003curl\u003e\",\n  oidc_client_id: \"\u003cid\u003e\",\n  oidc_client_secret: \"\u003csecret\u003e\",\n  oidc_allow_domains: [\"\u003cdomain\u003e\"],\n  oidc_allow_emails: [\"\u003cemail\u003e\"],\n  oidc_scopes: [\"\u003cscope\u003e\"],\n  pooling_enabled: false,\n  traffic_policy: \"\u003cpolicy_json\u003e\",\n  request_header_remove: [\"X-Req-Nope\"],\n  response_header_remove: [\"X-Res-Nope\"],\n  request_header_add: [\"X-Req-Yup:true\"],\n  response_header_add: [\"X-Res-Yup:true\"],\n  verify_upstream_tls: false,\n  verify_webhook_provider: \"twilio\",\n  verify_webhook_secret: \"asdf\",\n  websocket_tcp_converter: true,\n});\n```\n\nThe [Config](https://ngrok.github.io/ngrok-javascript/interfaces/Config.html) interface also shows all the available options.\n\n# Examples\n\nDegit can be used for cloning and running an example directory like this:\n```bash\nnpx degit github:ngrok/ngrok-javascript/examples/\u003cexample\u003e \u003cfolder-name\u003e\ncd \u003cfolder-name\u003e\nnpm i\n```\nFor example:\n```bash\nnpx degit github:ngrok/ngrok-javascript/examples/express express \u0026\u0026 cd express \u0026\u0026 npm i\n```\n\n#### Frameworks\n- [AWS App Runner](https://github.com/ngrok/ngrok-sdk-serverless-example)\n- [Express](https://github.com/ngrok/ngrok-javascript/blob/main/examples/express)\n- [Fastify Example](https://github.com/ngrok/ngrok-javascript/blob/main/examples/fastify)\n- [Hapi Example](https://github.com/ngrok/ngrok-javascript/blob/main/examples/hapi)\n- [Koa Example](https://github.com/ngrok/ngrok-javascript/blob/main/examples/koa)\n- [Nest.js](https://github.com/ngrok/ngrok-javascript/blob/main/examples/nestjs)\n- [Next.js](https://github.com/ngrok/ngrok-javascript/blob/main/examples/nextjs)\n- [Remix](https://github.com/ngrok/ngrok-javascript/blob/main/examples/remix)\n- [Svelte](https://github.com/ngrok/ngrok-javascript/blob/main/examples/svelte)\n- [Typescript](https://github.com/ngrok/ngrok-javascript/blob/main/examples/ngrok-typescript.ts)\n- [Vue](https://github.com/ngrok/ngrok-javascript/blob/main/examples/vue)\n- [Winston (Logging)](https://github.com/ngrok/ngrok-javascript/blob/main/examples/ngrok-winston.js)\n\n#### Listeners\n* [ngrok.forward (minimal)](https://github.com/ngrok/ngrok-javascript/blob/main/examples/ngrok-forward-minimal.js)\n* [ngrok.forward (full)](https://github.com/ngrok/ngrok-javascript/blob/main/examples/ngrok-forward-full.js)\n* [HTTP (ngrok.listener)](https://github.com/ngrok/ngrok-javascript/blob/main/examples/ngrok-listen.js)\n* [HTTP (SessionBuilder minimal)](https://github.com/ngrok/ngrok-javascript/blob/main/examples/ngrok-http-minimum.js)\n* [HTTP (SessionBuilder full)](https://github.com/ngrok/ngrok-javascript/blob/main/examples/ngrok-http-full.js)\n* [Labeled](https://github.com/ngrok/ngrok-javascript/blob/main/examples/ngrok-labeled.js)\n* [TCP](https://github.com/ngrok/ngrok-javascript/blob/main/examples/ngrok-tcp.js)\n* [TLS](https://github.com/ngrok/ngrok-javascript/blob/main/examples/ngrok-tls.js)\n* [Windows Pipe](https://github.com/ngrok/ngrok-javascript/blob/main/examples/ngrok-windows-pipe.js)\n\n# Platform Support\n\nPre-built binaries are provided on NPM for the following platforms:\n\n| OS         | i686 | x64 | aarch64 | arm |\n| ---------- | -----|-----|---------|-----|\n| Windows    |   ✓  |  ✓  |    ✓    |     |\n| MacOS      |      |  ✓  |    ✓    |  ✓  |\n| Linux      |      |  ✓  |    ✓    |  ✓  |\n| Linux musl |      |  ✓  |    ✓    |     |\n| FreeBSD    |      |  ✓  |         |     |\n| Android    |      |     |    ✓    |  ✓  |\n\n\u003e **Note**\n\u003e `ngrok-javascript`, and [ngrok-rust](https://github.com/ngrok/ngrok-rust/) which it depends on, are open source, so it may be possible to build them for other platforms.\n\u003e \n\u003e On Windows, ensure you have [Microsoft Visual C++ Redistributable](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170#latest-microsoft-visual-c-redistributable-version) installed.\n\u003e\n\u003e  We currently support MacOS 10.13+. \n\n# Dependencies\n\n- [NAPI-RS](https://napi.rs/), an excellent system to ease development and building of Rust plugins for NodeJS.\n\n# Changelog\n\nChanges to `ngrok-javascript` are tracked under [CHANGELOG.md](https://github.com/ngrok/ngrok-javascript/blob/main/CHANGELOG.md).\n\n\n# Join the ngrok Community\n\n- Check out [our official docs](https://docs.ngrok.com)\n- Read about updates on [our blog](https://blog.ngrok.com)\n- Open an [issue](https://github.com/ngrok/ngrok-javascript/issues) or [pull request](https://github.com/ngrok/ngrok-javascript/pulls)\n- Join our [Slack community](https://ngrok.com/slack)\n- Follow us on [X / Twitter (@ngrokHQ)](https://twitter.com/ngrokhq)\n- Subscribe to our [Youtube channel (@ngrokHQ)](https://www.youtube.com/@ngrokhq)\n\n# License\n\nThis work is dual-licensed under [Apache, Version 2.0](LICENSE-APACHE) and [MIT](LICENSE-MIT).\nYou can choose between one of them if you use this work.\n\n### Contributions\n\nUnless you explicitly state otherwise, any contribution intentionally submitted\nfor inclusion in `ngrok-javascript` by you, as defined in the Apache-2.0 license, shall be\ndual licensed as above, without any additional terms or conditions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fngrok%2Fngrok-javascript","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fngrok%2Fngrok-javascript","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fngrok%2Fngrok-javascript/lists"}