sindresorhus/wait-for-localhost

Wait for localhost to be ready

wait-for-localhost

Wait for localhost to be ready

Useful if you need a local server to be ready to accept requests before doing other things.

Install

npm install wait-for-localhost

Usage

import waitForLocalhost from 'wait-for-localhost';

await waitForLocalhost({port: 8080});
console.log('Server is ready');

API

waitForLocalHost(options?)

Returns a Promise<object> that settles when localhost is ready.

The object contains a ipVersion property with a value of either 6 or 4 depending on the IP version that was used.

options

Type: object

port

Type: number
Default: 80

path

Type: string
Default: '/'

Use a custom path.

For example, /health for a health-check endpoint.

useGet

Type: boolean
Default: false

Use the GET HTTP-method instead of HEAD to check if the server is running.

statusCodes

Type: number[]
Default: [200]

HTTP status codes to consider as successful responses.

Related

• wait-for-localhost-cli - CLI for this module
• delay - Delay execution for a given amount of seconds

wait-for-localhost's Issues

npm not in sync with master

Hi @sindresorhus,

I noticed version 3.2.0 on npm doesn't reflect current master which includes options.path. Are there any plans to push an update?

Thanks

Unused `meow` dependency

Hello! 👋

Was poking around and noticed that meow is being installed via dependencies without being used anywhere. Assume it's a leftover from the pre wait-for-localhost-cli days.

Support timeout for request

With the current system, a req is retried infinitely until we get a success response. Accepting a timeout would be good to break the loop of retrying.

Faced this recently when writing a few jest tests, where I wanted the request to succeed but only wait for a certain time and let the request timeout after that.

Something like this?

    const main = () => {
      const request = http.request(
        { method, port: options.port, path: options.path, timeout: 5000 },
        (response) => {
          if (response.statusCode === 200) {
            return resolve({ started: true });
          }

          return main();
        },
      );

      request.on('error', main);
      request.on('timeout', () => {
        request.destroy();
        return resolve({ started: false });
      });
      request.end();
    };

    main();

Add `path` option

Idea from #10.

http2 option

I have a local server that doesn't accept http1 requests.

Host & Path Support

Hey @sindresorhus, hope you're doing well. I'm in need of a very similar ( super simple ) package, but with support for providing host and path. My use case is for a CI pipeline to wait for a service to become healthy upon deployment by pinging a health-check endpoint.

The naming of this module locks it into localhost, but I wanted to surface this for consideration before creating a new module. This module is a spread operator on the options object away from supporting hosts and paths.

If you want to keep this focused on local development, I'll proceed with publishing the updates to wait-for-host and wait-for-host-cli. Maybe this could consume and provide default values for localhost?

How does this differ from wait-on?

Hi @sindresorhus , thanks for your commitment to open source code.
This is not a bug-related issue, only a genuine curiosity of mine, I guess.

How does this package differ from wait-on?
e.g., If I wanted to wait for something in localhost on the port 3000, I could do:

• [wait-on] $ wait-on http://localhost:3000
• [wait-for-localhost] $ wait-for-localhost 3000

API mode

Hi, would you be willing to add (or accept a PR for) an API mode? Basically just return a promise that resolves once the server is available (I want to use this in a CLI tool).

const waitForLocalhost = require('wait-for-localhost');

(async () => {
  await waitForLocalhost({ port });

  // ready to do some stuff, e. g. access served files
})();

Edit: whoops, just saw that someone already submitted PR #2 for that 🙈