browser-sync.d.ts

// 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/borisyankov/DefinitelyTyped

/// <reference path="../chokidar/chokidar.d.ts"/>
/// <reference path="../node/node.d.ts" />

declare module "browser-sync" {
    import chokidar = require("chokidar");
    import fs = require("fs");
    import http = require("http");

    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;
        /**
         * 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[];
        /**
         * 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?: ChokidarOptions;
        /**
         * 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;
    }

    interface Hash<T> {
        [path: string]: T;
    }

    interface ChokidarOptions {
        interval?: number;
        debounceDelay?: number;
        mode?: string;
        cwd?: string;
    }
    
    interface UIOptions { 
        /** set the default port */
        port?: number;
        /** set the default weinre port */
        weinre?: { 
            port?: number;
        }; 
    }

    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[];
    }
    
    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 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 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;
    }

    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: {once: boolean}): 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: BrowserSyncStatic;

    export = browserSync;
}