declarations
Version:
[](https://www.npmjs.com/package/declarations)
434 lines (415 loc) • 16.9 kB
TypeScript
// Type definitions for browser-sync
// Project: http://www.browsersync.io/
// Definitions by: Asana <https://asana.com>, Joe Skeen <http://github.com/joeskeen>
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
/// <reference path="../chokidar/chokidar.d.ts"/>
/// <reference path="../node/node.d.ts" />
/// <reference path="../micromatch/micromatch.d.ts" />
declare module "browser-sync" {
import * as chokidar from "chokidar";
import * as fs from "fs";
import * as http from "http";
import * as mm from "micromatch";
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.
*
* port - Default: 3001
* weinre.port - Default: 8080
* Note: requires at least version 2.0.0
*/
ui?: UIOptions | boolean;
/**
* 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. See anymatch for more information on glob
* patterns.
* Default: false
*/
files?: string | (string | FileCallback)[];
/**
* File watching options that get passed along to Chokidar. Check their docs for available options
* Default: undefined
* Note: requires at least version 2.6.0
*/
watchOptions?: chokidar.WatchOptions;
/**
* Use the built-in static server for basic HTML/JS/CSS websites.
* Default: false
*/
server?: ServerOptions;
/**
* Proxy an EXISTING vhost. Browsersync will wrap your vhost with a proxy URL to view your site.
* target - Default: undefined
* ws - Default: undefined
* middleware - Default: undefined
* reqHeaders - Default: undefined
* proxyRes - Default: undefined
*/
proxy?: string | boolean | ProxyOptions;
/**
* Use a specific port (instead of the one auto-detected by Browsersync)
* Default: 3000
*/
port?: number;
/**
* Add additional directories from which static files should be served.
* Should only be used in proxy or snippet mode.
* Default: []
* Note: requires at least version 2.8.0
*/
serveStatic?: string[];
/**
* Enable https for localhost development.
* Note - this is not needed for proxy option as it will be inferred from your target url.
* Note: requires at least version 1.3.0
*/
https?: boolean;
/**
* Clicks, Scrolls & Form inputs on any device will be mirrored to all others.
* clicks - Default: true
* scroll - Default: true
* forms - Default: true
*/
ghostMode?: GhostOptions | boolean;
/**
* Can be either "info", "debug", "warn", or "silent"
* Default: info
*/
logLevel?: string;
/**
* Change the console logging prefix. Useful if you're creating your own project based on Browsersync
* Default: BS
* Note: requires at least version 1.5.1
*/
logPrefix?: string;
/**
* Whether or not to log connections
* Default: false
*/
logConnections?: boolean;
/**
* Whether or not to log information about changed files
* Default: false
*/
logFileChanges?: boolean;
/**
* Log the snippet to the console when you're in snippet mode (no proxy/server)
* Default: true
* Note: requires at least version 1.5.2
*/
logSnippet?: boolean;
/**
* 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.
* Note: requires at least version 2.0.0
*/
snippetOptions?: SnippetOptions;
/**
* Add additional HTML rewriting rules.
* Default: false
* Note: requires at least version 2.4.0
*/
rewriteRules?: boolean | RewriteRules[];
/**
* Tunnel the Browsersync server through a random Public URL
* Default: null
*/
tunnel?: string | boolean;
/**
* 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
*/
online?: boolean;
/**
* Default: true
* 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
*/
open?: string | boolean;
/**
* The browser(s) to open
* Default: default
*/
browser?: string | string[];
/**
* Requires an internet connection - useful for services such as Typekit as it allows you to configure
* domains such as *.xip.io in your kit settings
* Default: false
*/
xip?: boolean;
/**
* Reload each browser when Browsersync is restarted.
* Default: false
*/
reloadOnRestart?: boolean;
/**
* The small pop-over notifications in the browser are not always needed/wanted.
* Default: true
*/
notify?: boolean;
/**
* scrollProportionally: false // Sync viewports to TOP position
* Default: true
*/
scrollProportionally?: boolean;
/**
* How often to send scroll events
* Default: 0
*/
scrollThrottle?: number;
/**
* Decide which technique should be used to restore scroll position following a reload.
* Can be window.name or cookie
* Default: 'window.name'
*/
scrollRestoreTechnique?: string;
/**
* Sync the scroll position of any element on the page. Add any amount of CSS selectors
* Default: []
* Note: requires at least version 2.9.0
*/
scrollElements?: string[];
/**
* Default: []
* Note: requires at least version 2.9.0
* 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
*/
scrollElementMapping?: string[];
/**
* Time, in milliseconds, to wait before instructing the browser to reload/inject following a file
* change event
* Default: 0
*/
reloadDelay?: number;
/**
* Restrict the frequency in which browser:reload events can be emitted to connected clients
* Default: 0
* Note: requires at least version 2.6.0
*/
reloadDebounce?: number;
/**
* User provided plugins
* Default: []
* Note: requires at least version 2.6.0
*/
plugins?: any[];
/**
* Whether to inject changes (rather than a page refresh)
* Default: true
*/
injectChanges?: boolean;
/**
* The initial path to load
*/
startPath?: string;
/**
* Whether to minify the client script
* Default: true
*/
minify?: boolean;
/**
* Override host detection if you know the correct IP to use
*/
host?: string;
/**
* Send file-change events to the browser
* Default: true
*/
codeSync?: boolean;
/**
* Append timestamps to injected files
* Default: true
*/
timestamps?: boolean;
/**
* 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.
* Note: requires at least version 1.5.0
*/
scriptPath?: (path: string) => string;
/**
* 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
* Note: requires at least version 1.6.2
*/
socket?: SocketOptions;
middleware?: MiddlewareHandler | PerRouteMiddleware | (MiddlewareHandler | PerRouteMiddleware)[];
}
interface Hash<T> {
[path: string]: T;
}
interface UIOptions {
/** set the default port */
port?: number;
/** set the default weinre port */
weinre?: {
port?: number;
};
}
interface FileCallback {
match?: string | string[];
fn: (event: string, file: string) => any;
options?: chokidar.WatchOptions;
}
interface ServerOptions {
/** set base directory */
baseDir?: string | string[];
/** enable directory listing */
directory?: boolean;
/** set index filename */
index?: string;
/**
* 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>;
/** configure custom middleware */
middleware?: (MiddlewareHandler | PerRouteMiddleware)[];
}
interface ProxyOptions {
target?: string;
middleware?: MiddlewareHandler;
ws: boolean;
reqHeaders: (config: any) => Hash<any>;
proxyRes: (res: http.ServerResponse, req: http.ServerRequest, next: Function) => any;
}
interface MiddlewareHandler {
(req: http.ServerRequest, res: http.ServerResponse, next: Function): any;
}
interface PerRouteMiddleware {
route: string;
handle: MiddlewareHandler;
}
interface GhostOptions {
clicks?: boolean;
scroll?: boolean;
forms?: boolean;
}
interface SnippetOptions {
ignorePaths?: string;
rule?: { match?: RegExp; fn?: (snippet: string, match: string) => any };
}
interface SocketOptions {
path?: string;
clientPath?: string;
namespace?: string;
domain?: string;
port?: number;
clients?: { heartbeatTimeout?: number; };
}
interface RewriteRules {
match: RegExp;
fn: (match: string) => string;
}
interface StreamOptions {
once?: boolean;
match?: mm.Pattern | mm.Pattern[];
}
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: Object) => any): BrowserSyncInstance;
/**
* Create a Browsersync instance
* @param name an identifier that can used for retrieval later
*/
create(name?: string): 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;
}
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: Object) => any): BrowserSyncInstance;
/**
* 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;
/**
* 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;
/**
* This method will close any running server, stop file watching & exit the current process.
*/
exit(): void;
/**
* 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;
/**
* Method to pause file change events
*/
pause(): void;
/**
* Method to resume paused watchers
*/
resume(): void;
/**
* 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;
}
}
const browserSync: browserSync.BrowserSyncStatic;
export = browserSync;
}