@types/browser-sync
Version:
TypeScript definitions for browser-sync
696 lines (668 loc) • 23.9 kB
TypeScript
/// <reference types="node" />
/// <reference types="serve-static" />
import * as chokidar from "chokidar";
import * as fs from "fs";
import * as http from "http";
import * as mm from "micromatch";
import { ServeStaticOptions } from "serve-static";
declare namespace browserSync {
interface Options {
/**
* Browsersync includes a user-interface that is accessed via a separate port.
* The UI allows to controls all devices, push sync updates and much more.
* @default false
*/
ui?: UIOptions | boolean | undefined;
/**
* Browsersync can watch your files as you work. Changes you make will either
* be injected into the page (CSS & images) or will cause all browsers to do
* a full-page refresh.
* @default false
*/
files?: string | Array<string | FileCallback | object> | undefined;
/**
* Specify which file events to respond to.
* Available events: `add`, `change`, `unlink`, `addDir`, `unlinkDir`
* @default ["change"]
* @since 2.18.8
*/
watchEvents?: WatchEvents | string[] | undefined;
/**
* Watch files automatically - this should be used as an
* alternative to the `files` option. When this option is used, some directories
* will be ignored automatically such as `node_modules` `bower_components` `.sass-cache`
* `.vscode` `.git` `.idea`
* @default false
* @since 2.23.0
*/
watch?: boolean | undefined;
/**
* Patterns for any watchers to ignore. Anything provided here
* will end up inside `watchOptions.ignored`
* @default []
* @since 2.23.0
*/
ignore?: string[] | undefined;
/**
* Serve an index.html file for all non-asset routes. Useful
* when using client-routers
* @default false
* @since 2.23.0
*/
single?: boolean | undefined;
/**
* File watching options that get passed along to [Chokidar](https://github.com/paulmillr/chokidar).
* Check their docs for available options
* @default undefined
* @since 2.6.0
*/
watchOptions?: chokidar.WatchOptions | undefined;
/**
* Use the built-in static server for basic HTML/JS/CSS websites.
* @default false
*/
server?: string | boolean | string[] | ServerOptions | undefined;
/**
* Proxy an EXISTING vhost. Browsersync will wrap your vhost with a proxy URL to view your site.
* @default false
*/
proxy?: string | ProxyOptions | undefined;
/**
* Use a specific port (instead of the one auto-detected by Browsersync)
* @default 3000
*/
port?: number | undefined;
/**
* Functions or actual plugins used as middleware.
* @default false
*/
middleware?: MiddlewareHandler | PerRouteMiddleware | Array<MiddlewareHandler | PerRouteMiddleware> | undefined;
/**
* Add additional directories from which static
* files should be served. Should only be used in `proxy` or `snippet`
* mode.
* @default []
* @since 2.8.0
*/
serveStatic?: StaticOptions[] | string[] | undefined;
/**
* Options that are passed to the serve-static middleware
* when you use the string[] syntax: eg: `serveStatic: ['./app']`. Please see
* [serve-static](https://github.com/expressjs/serve-static) for details
* @since 2.17.0
*/
serveStaticOptions?: ServeStaticOptions | undefined;
/**
* Enable https for localhost development. **Note** - this is not needed for proxy
* option as it will be inferred from your target url.
* @default undefined
* @since 1.3.0
*/
https?: boolean | HttpsOptions | undefined;
/**
* Override http module to allow using 3rd party server modules (such as http2)
* *Note*: these modules are not included in the Browsersync package - you need
* to 'npm install' any that you'd like to use.
* @default undefined
* @since 2.18.0
*/
httpModule?: string | undefined;
/**
* Current working directory
* @since 2.23.0
*/
cwd?: string;
/**
* Register callbacks via a regular option - this can be used
* to get access the Browsersync instance in situations where you
* cannot provide a callback via the normal API (for example, in a Gruntfile)
*
* **Note**: Only the `ready` callback is currently supported here.
*/
callbacks?: CallbacksOptions;
/**
* Clicks, Scrolls & Form inputs on any device will be mirrored to all others.
* clicks - Default: true
* scroll - Default: true
* forms - Default: {
submit: true,
inputs: true,
toggles: true
}
*/
ghostMode?: GhostOptions | boolean | undefined;
/**
* Can be either "info", "debug", "warn", or "silent"
* @default "info"
*/
logLevel?: LogLevel | undefined;
/**
* Change the console logging prefix. Useful if you're creating your
* own project based on Browsersync
* @default "Browsersync"
* @since 1.5.1
*/
logPrefix?: string | undefined;
/**
* Whether or not to log connections
* @default false
*/
logConnections?: boolean | undefined;
/**
* Whether or not to log information about changed files
* @default true
*/
logFileChanges?: boolean | undefined;
/**
* Log the snippet to the console when you're in snippet mode (no proxy/server)
* @default true
* @since 1.5.2
*/
logSnippet?: boolean | undefined;
/**
* You can prevent Browsersync from injecting the connection snippet
* by passing `snippet: false`.
* @default undefined
*/
snippet?: boolean | undefined;
/**
* You can control how the snippet is injected
* onto each page via a custom regex + function.
* You can also provide patterns for certain urls
* that should be ignored from the snippet injection.
* @since 2.0.0
*/
snippetOptions?: SnippetOptions | undefined;
/**
* Add additional HTML rewriting rules.
* @since 2.4.0
* @default false
*/
rewriteRules?: boolean | RewriteRules[] | undefined;
/**
* Tunnel the Browsersync server through a random Public URL
* @default null
*/
tunnel?: string | boolean | undefined;
/**
* Some features of Browsersync (such as `xip` & `tunnel`) require an internet connection, but if you're
* working offline, you can reduce start-up time by setting this option to `false`
* @default undefined
*/
online?: boolean | undefined;
/**
* Decide which URL to open automatically when Browsersync starts. Defaults to "local" if none set.
* Can be `true`, `local`, `external`, `ui`, `ui-external`, `tunnel` or `false`
* @default true
*/
open?: OpenOptions | boolean | undefined;
/**
* The browser(s) to open
* @default "default"
*/
browser?: string | string[] | undefined;
/**
* Add HTTP access control (CORS) headers to assets served by Browsersync.
* @default false
* @since 2.16.0
*/
cors?: boolean | undefined;
/**
* Requires an internet connection - useful for services such as [Typekit](https://typekit.com/)
* as it allows you to configure domains such as `*.xip.io` in your kit settings
* @default false
*/
xip?: boolean | undefined;
/**
* ¯\_(ツ)_/¯
* @default false
*/
hostnameSuffix?: boolean | undefined;
/**
* Reload each browser when Browsersync is restarted.
* @default false
*/
reloadOnRestart?: boolean | undefined;
/**
* The small pop-over notifications in the browser are not always needed/wanted.
* @default true
*/
notify?: boolean | undefined;
/**
* scrollProportionally: false // Sync viewports to TOP position
* @default true
*/
scrollProportionally?: boolean | undefined;
/**
* How often to send scroll events
* @default 0
*/
scrollThrottle?: number | undefined;
/**
* Decide which technique should be used to restore
* scroll position following a reload.
* Can be `window.name` or `cookie`
* @default "window.name"
*/
scrollRestoreTechnique?: string | undefined;
/**
* Sync the scroll position of any element
* on the page. Add any amount of CSS selectors
* @default []
* @since 2.9.0
*/
scrollElements?: string[] | undefined;
/**
* Sync the scroll position of any element
* on the page - where any scrolled element
* will cause all others to match scroll position.
* This is helpful when a breakpoint alters which element
* is actually scrolling
* @default []
* @since 2.9.0
*/
scrollElementMapping?: string[] | undefined;
/**
* Time, in milliseconds, to wait before
* instructing the browser to reload/inject following a
* file change event
* @default 0
*/
reloadDelay?: number | undefined;
/**
* Wait for a specified window of event-silence before
* sending any reload events.
* @default 500
* @since 2.6.0
*/
reloadDebounce?: number | undefined;
/**
* Emit only the first event during sequential time windows
* of a specified duration.
* @default 0
* @since 2.13.0
*/
reloadThrottle?: number | undefined;
/**
* User provided plugins
* @default []
* @since 2.6.0
*/
plugins?: any[] | undefined;
/**
* Whether to inject changes (rather than a page refresh)
* @default true
*/
injectChanges?: boolean | undefined;
/**
* The initial path to load
* @default null
*/
startPath?: string | undefined | null;
/**
* Whether to minify the client script
* @default true
*/
minify?: boolean | undefined;
/**
* Override host detection if you know the correct IP to use
* @default null
*/
host?: string | undefined | null;
/**
* Specify a host to listen on. Use this if you want to
* prevent binding to all interfaces.
*
* **Note**: When you specify this option, it overrides the 'host' option
* @default undefined
*/
listen?: string;
/**
* Support environments where dynamic hostnames are not required
* (ie: electron)
* @default false
* @since 2.14.0
*/
localOnly?: boolean | undefined;
/**
* Send file-change events to the browser
* @default true
*/
codeSync?: boolean | undefined;
/**
* Append timestamps to injected files
* @default true
*/
timestamps?: boolean | undefined;
/**
* When ghostMode is setup the events
* listed here will be emitted and able to hook into.
* @default [
* "scroll",
* "scroll:element",
* "input:text",
* "input:toggles",
* "form:submit",
* "form:reset",
* "click"
* ]
*/
clientEvents?: string[] | undefined;
/**
* Alter the script path for complete control over where the Browsersync
* Javascript is served from. Whatever you return from this function
* will be used as the script path.
* @default undefined
* @since 1.5.0
*/
scriptPath?: ((path: string) => string) | undefined;
/**
* Configure the Socket.IO path and namespace & domain to avoid collisions.
* path - Default: "/browser-sync/socket.io"
* clientPath - Default: "/browser-sync"
* namespace - Default: "/browser-sync"
* domain - Default: undefined
* port - Default: undefined
* clients.heartbeatTimeout - Default: 5000
* @since 1.6.2
*/
socket?: SocketOptions | undefined;
/**
* Configure the script domain
* @since 2.14.0
*/
script?: ScriptOptions | undefined;
tagNames?: TagNamesOptions | undefined;
/**
* @default ["css", "png", "jpg", "jpeg", "svg", "gif", "webp", "map"]
*/
injectFileTypes?: string[] | undefined;
/**
* @default false
*/
injectNotification?: boolean | undefined;
/**
* @default [
* "js",
* "css",
* "pdf",
* "map",
* "svg",
* "ico",
* "woff",
* "json",
* "eot",
* "ttf",
* "png",
* "jpg",
* "jpeg",
* "webp",
* "gif",
* "mp4",
* "mp3",
* "3gp",
* "ogg",
* "ogv",
* "webm",
* "m4a",
* "flv",
* "wmv",
* "avi",
* "swf",
* "scss"
* ]
*/
excludeFileTypes?: string[] | undefined;
}
type WatchEvents = "add" | "change" | "unlink" | "addDir" | "unlinkDir";
type LogLevel = "info" | "debug" | "warn" | "silent";
type OpenOptions = "local" | "external" | "ui" | "ui-external" | "tunnel";
interface Hash<T> {
[path: string]: T;
}
interface UIOptions {
/** set the default port */
port?: number | undefined;
/** set the default weinre port */
weinre?: {
port?: number | undefined;
} | undefined;
}
interface FileCallback {
match?: string | string[] | undefined;
fn: (event: string, file: string) => any;
options?: chokidar.WatchOptions | undefined;
}
interface ServerOptions {
/** set base directory */
baseDir?: string | string[] | undefined;
/** enable directory listing */
directory?: boolean | undefined;
/** set index filename */
index?: string | undefined;
/**
* key-value object hash, where the key is the url to match,
* and the value is the folder to serve (relative to your working directory)
*/
routes?: Hash<string> | undefined;
/** configure custom middleware */
middleware?: Array<MiddlewareHandler | PerRouteMiddleware> | undefined;
serveStaticOptions?: ServeStaticOptions | undefined;
}
interface ProxyOptions {
target?: string | undefined;
middleware?: MiddlewareHandler | undefined;
ws?: boolean | undefined;
reqHeaders?: ((config: object) => Hash<object>) | undefined;
proxyRes?: ProxyResponseMiddleware | ProxyResponseMiddleware[] | undefined;
proxyReq?: Array<(res: http.IncomingMessage) => void> | ((res: http.IncomingMessage) => void) | undefined;
error?: ((err: NodeJS.ErrnoException, req: http.IncomingMessage, res: http.ServerResponse) => void) | undefined;
}
interface ProxyResponseMiddleware {
(
proxyRes: http.ServerResponse | http.IncomingMessage,
res: http.ServerResponse,
req: http.IncomingMessage,
): void;
}
interface HttpsOptions {
key?: string | undefined;
cert?: string | undefined;
}
interface StaticOptions {
route: string | string[];
dir: string | string[];
}
interface MiddlewareHandler {
(req: http.IncomingMessage, res: http.ServerResponse, next: () => void): any;
}
interface PerRouteMiddleware {
id?: string | undefined;
route: string;
handle: MiddlewareHandler;
}
interface CallbacksOptions {
ready: (err: Error, bs: BrowserSyncInstance) => void;
}
interface GhostOptions {
clicks?: boolean | undefined;
scroll?: boolean | undefined;
forms?: FormsOptions | boolean | undefined;
}
interface FormsOptions {
inputs: boolean;
submit: boolean;
toggles: boolean;
}
interface SnippetOptions {
async?: boolean | undefined;
whitelist?: string[] | undefined;
blacklist?: string[] | undefined;
rule?: {
match?: RegExp | undefined;
fn?: ((snippet: string, match: string) => any) | undefined;
} | undefined;
}
interface SocketOptions {
path?: string | undefined;
clientPath?: string | undefined;
namespace?: string | undefined;
domain?: string | undefined;
port?: number | undefined;
clients?: { heartbeatTimeout?: number | undefined } | undefined;
}
interface ScriptOptions {
domain?: string | undefined;
}
interface TagNamesOptions {
less?: string | undefined;
scss?: string | undefined;
css?: string | undefined;
jpg?: string | undefined;
jpeg?: string | undefined;
png?: string | undefined;
svg?: string | undefined;
gif?: string | undefined;
js?: string | undefined;
}
interface RewriteRules {
match: RegExp;
replace?: string | undefined;
fn?: ((req: http.IncomingMessage, res: http.ServerResponse, match: string) => string) | undefined;
}
interface StreamOptions {
once?: boolean | undefined;
match?: mm.Pattern | mm.Pattern[] | undefined;
}
interface BrowserSyncStatic extends BrowserSyncInstance {
/**
* Start the Browsersync service. This will launch a server, proxy or start the snippet mode
* depending on your use-case.
*/
(config?: Options, callback?: (err: Error, bs: BrowserSyncInstance) => any): BrowserSyncInstance;
/** */
instances: BrowserSyncInstance[];
/**
* Create a Browsersync instance
* @param name an identifier that can used for retrieval later
*/
create(name?: string, emitter?: NodeJS.EventEmitter): BrowserSyncInstance;
/**
* Get a single instance by name. This is useful if you have your build scripts in separate files
* @param name the identifier used for retrieval
*/
get(name: string): BrowserSyncInstance;
/**
* Check if an instance has been created.
* @param name the name of the instance
*/
has(name: string): boolean;
/**
* Reset the state of the module.
* (should only be needed for test environments)
*/
reset(): void;
}
interface BrowserSyncInstance {
/** the name of this instance of browser-sync */
name: string;
/**
* Start the Browsersync service. This will launch a server, proxy or start the snippet mode
* depending on your use-case.
*/
init(config?: Options, callback?: (err: Error, bs: BrowserSyncInstance) => any): BrowserSyncInstance;
/**
* This method will close any running server, stop file watching & exit the current process.
*/
exit(): void;
/**
* Helper method for browser notifications
* @param message Can be a simple message such as 'Connected' or HTML
* @param timeout How long the message will remain in the browser. @since 1.3.0
*/
notify(message: string, timeout?: number): void;
/**
* Method to pause file change events
*/
pause(): void;
/**
* Method to resume paused watchers
*/
resume(): void;
/**
* Reload the browser
* The reload method will inform all browsers about changed files and will either cause the browser
* to refresh, or inject the files where possible.
*/
reload(): void;
/**
* Reload a single file
* The reload method will inform all browsers about changed files and will either cause the browser
* to refresh, or inject the files where possible.
*/
reload(file: string): void;
/**
* Reload multiple files
* The reload method will inform all browsers about changed files and will either cause the browser
* to refresh, or inject the files where possible.
*/
reload(files: string[]): void;
/**
* The reload method will inform all browsers about changed files and will either cause the browser
* to refresh, or inject the files where possible.
*/
reload(options: { stream: boolean }): NodeJS.ReadWriteStream;
/**
* The stream method returns a transform stream and can act once or on many files.
* @param opts Configuration for the stream method
*/
stream(opts?: StreamOptions): NodeJS.ReadWriteStream;
/**
* Instance Cleanup.
*/
cleanup(fn?: (error: NodeJS.ErrnoException, bs: BrowserSyncInstance) => void): void;
/**
* Register a plugin.
* Must implement at least a 'plugin' property that returns
* callable function.
*
* @method use
* @param {object} module The object to be `required`.
* @param {object} options The
* @param {any} cb A callback function that will return any errors.
*/
use(
module: { "plugin:name"?: string | undefined; plugin: (opts: object, bs: BrowserSyncInstance) => any },
options?: object,
cb?: any,
): void;
/**
* Callback helper to examine what options have been set.
* @param {string} name The key to search options map for.
*/
getOption(name: string): any;
/**
* Stand alone file-watcher. Use this along with Browsersync to create your own, minimal build system
*/
watch(
patterns: string,
opts?: chokidar.WatchOptions,
fn?: (event: string, file: fs.Stats) => any,
): NodeJS.EventEmitter;
/**
* The internal Event Emitter used by the running Browsersync instance (if there is one). You can use
* this to emit your own events, such as changed files, logging etc.
*/
emitter: NodeJS.EventEmitter;
/**
* A simple true/false flag that you can use to determine if there's a currently-running Browsersync instance.
*/
active: boolean;
/**
* A simple true/false flag to determine if the current instance is paused
*/
paused: boolean;
}
}
declare const browserSync: browserSync.BrowserSyncStatic;
export = browserSync;