@types/browser-sync

/// <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;