1 | // Type definitions for browser-sync 2.26
|
2 | // Project: http://www.browsersync.io/
|
3 | // Definitions by: Asana <https://asana.com>,
|
4 | // Joe Skeen <https://github.com/joeskeen>
|
5 | // Thomas "Thasmo" Deinhamer <https://thasmo.com/>
|
6 | // Kiyotoshi Ichikawa <https://github.com/aznnomness>
|
7 | // Yuma Hashimoto <https://github.com/yuma84>
|
8 | // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
|
9 | // TypeScript Version: 2.3
|
10 |
|
11 | /// <reference types="node" />
|
12 | /// <reference types="serve-static" />
|
13 |
|
14 | import * as chokidar from "chokidar";
|
15 | import * as fs from "fs";
|
16 | import * as http from "http";
|
17 | import * as mm from "micromatch";
|
18 | import { ServeStaticOptions } from "serve-static";
|
19 |
|
20 | declare namespace browserSync {
|
21 | interface Options {
|
22 | /**
|
23 | * Browsersync includes a user-interface that is accessed via a separate port. The UI allows to controls
|
24 | * all devices, push sync updates and much more.
|
25 | *
|
26 | * port - Default: 3001
|
27 | * weinre.port - Default: 8080
|
28 | * Note: Requires at least version 2.0.0.
|
29 | */
|
30 | ui?: UIOptions | boolean | undefined;
|
31 | /**
|
32 | * Browsersync can watch your files as you work. Changes you make will either be injected into the page (CSS
|
33 | * & images) or will cause all browsers to do a full-page refresh. See anymatch for more information on glob
|
34 | * patterns.
|
35 | * Default: false
|
36 | */
|
37 | files?: string | (string | FileCallback | object)[] | undefined;
|
38 | /**
|
39 | * Specify which file events to respond to.
|
40 | * Available events: `add`, `change`, `unlink`, `addDir`, `unlinkDir`
|
41 | */
|
42 | watchEvents?: WatchEvents | string[] | undefined;
|
43 | /**
|
44 | * Watch files automatically.
|
45 | */
|
46 | watch?: boolean | undefined;
|
47 | /**
|
48 | * Patterns for any watchers to ignore.
|
49 | * Anything provided here will end up inside 'watchOptions.ignored'.
|
50 | */
|
51 | ignore?: string[] | undefined;
|
52 | /**
|
53 | * Serve an index.html file for all non-asset routes.
|
54 | * Useful when using client-routers.
|
55 | */
|
56 | single?: boolean | undefined;
|
57 | /**
|
58 | * File watching options that get passed along to Chokidar. Check their docs for available options
|
59 | * Default: undefined
|
60 | * Note: Requires at least version 2.6.0.
|
61 | */
|
62 | watchOptions?: chokidar.WatchOptions | undefined;
|
63 | /**
|
64 | * Use the built-in static server for basic HTML/JS/CSS websites.
|
65 | * Default: false
|
66 | */
|
67 | server?: string | boolean | string[] | ServerOptions | undefined;
|
68 | /**
|
69 | * Proxy an EXISTING vhost. Browsersync will wrap your vhost with a proxy URL to view your site.
|
70 | * Passing only a URL as a string equates to passing only target property of ProxyOptions type.
|
71 | * target - Default: undefined
|
72 | * ws - Default: undefined
|
73 | * middleware - Default: undefined
|
74 | * reqHeaders - Default: undefined
|
75 | * proxyRes - Default: undefined (http.ServerResponse if expecting single parameter)
|
76 | * proxyReq - Default: undefined
|
77 | */
|
78 | proxy?: string | ProxyOptions | undefined;
|
79 | /**
|
80 | * Use a specific port (instead of the one auto-detected by Browsersync)
|
81 | * Default: 3000
|
82 | */
|
83 | port?: number | undefined;
|
84 | /**
|
85 | * Functions or actual plugins used as middleware.
|
86 | */
|
87 | middleware?: MiddlewareHandler | PerRouteMiddleware | (MiddlewareHandler | PerRouteMiddleware)[] | undefined;
|
88 | /**
|
89 | * Add additional directories from which static files should be served.
|
90 | * Should only be used in proxy or snippet mode.
|
91 | * Default: []
|
92 | * Note: Requires at least version 2.8.0.
|
93 | */
|
94 | serveStatic?: StaticOptions[] | string[] | undefined;
|
95 | /**
|
96 | * Options that are passed to the serve-static middleware when you use the
|
97 | * string[] syntax: eg: `serveStatic: ['./app']`.
|
98 | * Please see [serve-static](https://github.com/expressjs/serve-static) for details.
|
99 | */
|
100 | serveStaticOptions?: ServeStaticOptions | undefined;
|
101 | /**
|
102 | * Enable https for localhost development.
|
103 | * Note: This may not be needed for proxy option as it will try to infer from your target url.
|
104 | * Note: If privacy error is encountered please see HttpsOptions below, setting those will resolve.
|
105 | * Note: Requires at least version 1.3.0.
|
106 | */
|
107 | https?: boolean | HttpsOptions | undefined;
|
108 | /**
|
109 | * Override http module to allow using 3rd party server modules (such as http2).
|
110 | */
|
111 | httpModule?: string | undefined;
|
112 | /**
|
113 | * Clicks, Scrolls & Form inputs on any device will be mirrored to all others.
|
114 | * clicks - Default: true
|
115 | * scroll - Default: true
|
116 | * forms - Default: true
|
117 | */
|
118 | ghostMode?: GhostOptions | boolean | undefined;
|
119 | /**
|
120 | * Can be either "info", "debug", "warn", or "silent"
|
121 | * Default: info
|
122 | */
|
123 | logLevel?: LogLevel | undefined;
|
124 | /**
|
125 | * Change the console logging prefix. Useful if you're creating your own project based on Browsersync
|
126 | * Default: BS
|
127 | * Note: Requires at least version 1.5.1.
|
128 | */
|
129 | logPrefix?: string | undefined;
|
130 | /**
|
131 | * Whether or not to log connections
|
132 | * Default: false
|
133 | */
|
134 | logConnections?: boolean | undefined;
|
135 | /**
|
136 | * Whether or not to log information about changed files
|
137 | * Default: false
|
138 | */
|
139 | logFileChanges?: boolean | undefined;
|
140 | /**
|
141 | * Log the snippet to the console when you're in snippet mode (no proxy/server)
|
142 | * Default: true
|
143 | * Note: Requires at least version 1.5.2.
|
144 | */
|
145 | logSnippet?: boolean | undefined;
|
146 | /**
|
147 | * You can control how the snippet is injected onto each page via a custom regex + function.
|
148 | * You can also provide patterns for certain urls that should be ignored from the snippet injection.
|
149 | * Note: Requires at least version 2.0.0.
|
150 | */
|
151 | snippetOptions?: SnippetOptions | undefined;
|
152 | /**
|
153 | * Add additional HTML rewriting rules.
|
154 | * Default: false
|
155 | * Note: Requires at least version 2.4.0.
|
156 | */
|
157 | rewriteRules?: boolean | RewriteRules[] | undefined;
|
158 | /**
|
159 | * Tunnel the Browsersync server through a random Public URL
|
160 | * Default: null
|
161 | */
|
162 | tunnel?: string | boolean | undefined;
|
163 | /**
|
164 | * Some features of Browsersync (such as xip & tunnel) require an internet connection, but if you're
|
165 | * working offline, you can reduce start-up time by setting this option to false
|
166 | */
|
167 | online?: boolean | undefined;
|
168 | /**
|
169 | * Default: true
|
170 | * Decide which URL to open automatically when Browsersync starts. Defaults to "local" if none set.
|
171 | * Can be true, local, external, ui, ui-external, tunnel or false
|
172 | */
|
173 | open?: OpenOptions | boolean | undefined;
|
174 | /**
|
175 | * The browser(s) to open
|
176 | * Default: default
|
177 | */
|
178 | browser?: string | string[] | undefined;
|
179 | /**
|
180 | * Add HTTP access control (CORS) headers to assets served by Browsersync.
|
181 | * Default: false
|
182 | * Note: Requires at least version 2.16.0.
|
183 | */
|
184 | cors?: boolean | undefined;
|
185 | /**
|
186 | * Requires an internet connection - useful for services such as Typekit as it allows you to configure
|
187 | * domains such as *.xip.io in your kit settings
|
188 | * Default: false
|
189 | */
|
190 | xip?: boolean | undefined;
|
191 | /**
|
192 | * Reload each browser when Browsersync is restarted.
|
193 | * Default: false
|
194 | */
|
195 | reloadOnRestart?: boolean | undefined;
|
196 | /**
|
197 | * The small pop-over notifications in the browser are not always needed/wanted.
|
198 | * Default: true
|
199 | */
|
200 | notify?: boolean | undefined;
|
201 | /**
|
202 | * scrollProportionally: false // Sync viewports to TOP position
|
203 | * Default: true
|
204 | */
|
205 | scrollProportionally?: boolean | undefined;
|
206 | /**
|
207 | * How often to send scroll events
|
208 | * Default: 0
|
209 | */
|
210 | scrollThrottle?: number | undefined;
|
211 | /**
|
212 | * Decide which technique should be used to restore scroll position following a reload.
|
213 | * Can be window.name or cookie
|
214 | * Default: 'window.name'
|
215 | */
|
216 | scrollRestoreTechnique?: string | undefined;
|
217 | /**
|
218 | * Sync the scroll position of any element on the page. Add any amount of CSS selectors
|
219 | * Default: []
|
220 | * Note: Requires at least version 2.9.0.
|
221 | */
|
222 | scrollElements?: string[] | undefined;
|
223 | /**
|
224 | * Default: []
|
225 | * Note: Requires at least version 2.9.0.
|
226 | * Sync the scroll position of any element on the page - where any scrolled element will cause
|
227 | * all others to match scroll position. This is helpful when a breakpoint alters which element
|
228 | * is actually scrolling
|
229 | */
|
230 | scrollElementMapping?: string[] | undefined;
|
231 | /**
|
232 | * Time, in milliseconds, to wait before instructing the browser to reload/inject following a file
|
233 | * change event
|
234 | * Default: 0
|
235 | */
|
236 | reloadDelay?: number | undefined;
|
237 | /**
|
238 | * Restrict the frequency in which browser:reload events can be emitted to connected clients
|
239 | * Default: 0
|
240 | * Note: Requires at least version 2.6.0.
|
241 | */
|
242 | reloadDebounce?: number | undefined;
|
243 | /**
|
244 | * Emit only the first event during sequential time windows of a specified duration.
|
245 | * Note: Requires at least version 2.13.0.
|
246 | */
|
247 | reloadThrottle?: number | undefined;
|
248 | /**
|
249 | * User provided plugins
|
250 | * Default: []
|
251 | * Note: Requires at least version 2.6.0.
|
252 | */
|
253 | plugins?: any[] | undefined;
|
254 | /**
|
255 | * Whether to inject changes (rather than a page refresh)
|
256 | * Default: true
|
257 | */
|
258 | injectChanges?: boolean | undefined;
|
259 | /**
|
260 | * The initial path to load
|
261 | */
|
262 | startPath?: string | undefined;
|
263 | /**
|
264 | * Whether to minify the client script
|
265 | * Default: true
|
266 | */
|
267 | minify?: boolean | undefined;
|
268 | /**
|
269 | * Override host detection if you know the correct IP to use
|
270 | */
|
271 | host?: string | undefined;
|
272 | /**
|
273 | * Support environments where dynamic hostnames are not required (ie: electron).
|
274 | */
|
275 | localOnly?: boolean | undefined;
|
276 | /**
|
277 | * Send file-change events to the browser
|
278 | * Default: true
|
279 | */
|
280 | codeSync?: boolean | undefined;
|
281 | /**
|
282 | * Append timestamps to injected files
|
283 | * Default: true
|
284 | */
|
285 | timestamps?: boolean | undefined;
|
286 | /**
|
287 | * ¯\_(ツ)_/¯
|
288 | * Best guess, when ghostMode (or SocketIO?) is setup the events
|
289 | * listed here will be emitted and able to hook into.
|
290 | */
|
291 | clientEvents?: string[] | undefined;
|
292 | /**
|
293 | * Alter the script path for complete control over where the Browsersync Javascript is served
|
294 | * from. Whatever you return from this function will be used as the script path.
|
295 | * Note: Requires at least version 1.5.0.
|
296 | */
|
297 | scriptPath?: ((path: string) => string) | undefined;
|
298 | /**
|
299 | * Configure the Socket.IO path and namespace & domain to avoid collisions.
|
300 | * path - Default: "/browser-sync/socket.io"
|
301 | * clientPath - Default: "/browser-sync"
|
302 | * namespace - Default: "/browser-sync"
|
303 | * domain - Default: undefined
|
304 | * port - Default: undefined
|
305 | * clients.heartbeatTimeout - Default: 5000
|
306 | * Note: Requires at least version 1.6.2.
|
307 | */
|
308 | socket?: SocketOptions | undefined;
|
309 | /**
|
310 | * ¯\_(ツ)_/¯
|
311 | */
|
312 | tagNames?: TagNamesOptions | undefined;
|
313 | /**
|
314 | * ¯\_(ツ)_/¯
|
315 | */
|
316 | injectFileTypes?: string[] | undefined;
|
317 | /**
|
318 | * ¯\_(ツ)_/¯
|
319 | */
|
320 | excludeFileTypes?: string[] | undefined;
|
321 | }
|
322 |
|
323 | type WatchEvents = "add" | "change" | "unlink" | "addDir" | "unlinkDir";
|
324 |
|
325 | type LogLevel = "info" | "debug" | "warn" | "silent";
|
326 |
|
327 | type OpenOptions = "local" | "external" | "ui" | "ui-external" | "tunnel";
|
328 |
|
329 | interface Hash<T> {
|
330 | [path: string]: T;
|
331 | }
|
332 |
|
333 | interface UIOptions {
|
334 | /** set the default port */
|
335 | port?: number | undefined;
|
336 | /** set the default weinre port */
|
337 | weinre?: {
|
338 | port?: number | undefined;
|
339 | } | undefined;
|
340 | }
|
341 |
|
342 | interface FileCallback {
|
343 | match?: string | string[] | undefined;
|
344 | fn: (event: string, file: string) => any;
|
345 | options?: chokidar.WatchOptions | undefined;
|
346 | }
|
347 |
|
348 | interface ServerOptions {
|
349 | /** set base directory */
|
350 | baseDir?: string | string[] | undefined;
|
351 | /** enable directory listing */
|
352 | directory?: boolean | undefined;
|
353 | /** set index filename */
|
354 | index?: string | undefined;
|
355 | /**
|
356 | * key-value object hash, where the key is the url to match,
|
357 | * and the value is the folder to serve (relative to your working directory)
|
358 | */
|
359 | routes?: Hash<string> | undefined;
|
360 | /** configure custom middleware */
|
361 | middleware?: (MiddlewareHandler | PerRouteMiddleware)[] | undefined;
|
362 | serveStaticOptions?: ServeStaticOptions | undefined;
|
363 | }
|
364 |
|
365 | interface ProxyOptions {
|
366 | target?: string | undefined;
|
367 | middleware?: MiddlewareHandler | undefined;
|
368 | ws?: boolean | undefined;
|
369 | reqHeaders?: ((config: object) => Hash<object>) | undefined;
|
370 | proxyRes?: ProxyResponseMiddleware | ProxyResponseMiddleware[] | undefined;
|
371 | proxyReq?: ((res: http.IncomingMessage) => void)[] | ((res: http.IncomingMessage) => void) | undefined;
|
372 | error?: ((err: NodeJS.ErrnoException, req: http.IncomingMessage, res: http.ServerResponse) => void) | undefined;
|
373 | }
|
374 |
|
375 | interface ProxyResponseMiddleware {
|
376 | (proxyRes: http.ServerResponse | http.IncomingMessage, res: http.ServerResponse, req: http.IncomingMessage): void;
|
377 | }
|
378 |
|
379 | interface HttpsOptions {
|
380 | key?: string | undefined;
|
381 | cert?: string | undefined;
|
382 | }
|
383 |
|
384 | interface StaticOptions {
|
385 | route: string | string[],
|
386 | dir: string | string[]
|
387 | }
|
388 |
|
389 | interface MiddlewareHandler {
|
390 | (req: http.IncomingMessage, res: http.ServerResponse, next: () => void): any;
|
391 | }
|
392 |
|
393 | interface PerRouteMiddleware {
|
394 | id?: string | undefined;
|
395 | route: string;
|
396 | handle: MiddlewareHandler;
|
397 | }
|
398 |
|
399 | interface GhostOptions {
|
400 | clicks?: boolean | undefined;
|
401 | scroll?: boolean | undefined;
|
402 | forms?: FormsOptions | boolean | undefined;
|
403 | }
|
404 |
|
405 | interface FormsOptions {
|
406 | inputs: boolean,
|
407 | submit: boolean,
|
408 | toggles: boolean
|
409 | }
|
410 |
|
411 | interface SnippetOptions {
|
412 | async?: boolean | undefined;
|
413 | whitelist?: string[] | undefined,
|
414 | blacklist?: string[] | undefined,
|
415 | rule?: {
|
416 | match?: RegExp | undefined;
|
417 | fn?: ((snippet: string, match: string) => any) | undefined
|
418 | } | undefined;
|
419 | }
|
420 |
|
421 | interface SocketOptions {
|
422 | path?: string | undefined;
|
423 | clientPath?: string | undefined;
|
424 | namespace?: string | undefined;
|
425 | domain?: string | undefined;
|
426 | port?: number | undefined;
|
427 | clients?: { heartbeatTimeout?: number | undefined; } | undefined;
|
428 | }
|
429 |
|
430 | interface TagNamesOptions {
|
431 | less?: string | undefined;
|
432 | scss?: string | undefined;
|
433 | css?: string | undefined;
|
434 | jpg?: string | undefined;
|
435 | jpeg?: string | undefined;
|
436 | png?: string | undefined;
|
437 | svg?: string | undefined;
|
438 | gif?: string | undefined;
|
439 | js?: string | undefined;
|
440 | }
|
441 |
|
442 | interface RewriteRules {
|
443 | match: RegExp;
|
444 | replace?: string | undefined;
|
445 | fn?: ((req: http.IncomingMessage, res: http.ServerResponse, match: string) => string) | undefined;
|
446 | }
|
447 |
|
448 | interface StreamOptions {
|
449 | once?: boolean | undefined;
|
450 | match?: mm.Pattern | mm.Pattern[] | undefined;
|
451 | }
|
452 |
|
453 | interface BrowserSyncStatic extends BrowserSyncInstance {
|
454 | /**
|
455 | * Start the Browsersync service. This will launch a server, proxy or start the snippet mode
|
456 | * depending on your use-case.
|
457 | */
|
458 | (config?: Options, callback?: (err: Error, bs: BrowserSyncInstance) => any): BrowserSyncInstance;
|
459 | /**
|
460 | *
|
461 | */
|
462 | instances: Array<BrowserSyncInstance>;
|
463 | /**
|
464 | * Create a Browsersync instance
|
465 | * @param name an identifier that can used for retrieval later
|
466 | */
|
467 | create(name?: string, emitter?: NodeJS.EventEmitter): BrowserSyncInstance;
|
468 | /**
|
469 | * Get a single instance by name. This is useful if you have your build scripts in separate files
|
470 | * @param name the identifier used for retrieval
|
471 | */
|
472 | get(name: string): BrowserSyncInstance;
|
473 | /**
|
474 | * Check if an instance has been created.
|
475 | * @param name the name of the instance
|
476 | */
|
477 | has(name: string): boolean;
|
478 | /**
|
479 | * Reset the state of the module.
|
480 | * (should only be needed for test environments)
|
481 | */
|
482 | reset(): void;
|
483 | }
|
484 |
|
485 | interface BrowserSyncInstance {
|
486 | /** the name of this instance of browser-sync */
|
487 | name: string;
|
488 | /**
|
489 | * Start the Browsersync service. This will launch a server, proxy or start the snippet mode
|
490 | * depending on your use-case.
|
491 | */
|
492 | init(config?: Options, callback?: (err: Error, bs: BrowserSyncInstance) => any): BrowserSyncInstance;
|
493 | /**
|
494 | * This method will close any running server, stop file watching & exit the current process.
|
495 | */
|
496 | exit(): void;
|
497 | /**
|
498 | * Helper method for browser notifications
|
499 | * @param message Can be a simple message such as 'Connected' or HTML
|
500 | * @param timeout How long the message will remain in the browser. @since 1.3.0
|
501 | */
|
502 | notify(message: string, timeout?: number): void;
|
503 | /**
|
504 | * Method to pause file change events
|
505 | */
|
506 | pause(): void;
|
507 | /**
|
508 | * Method to resume paused watchers
|
509 | */
|
510 | resume(): void;
|
511 | /**
|
512 | * Reload the browser
|
513 | * The reload method will inform all browsers about changed files and will either cause the browser
|
514 | * to refresh, or inject the files where possible.
|
515 | */
|
516 | reload(): void;
|
517 | /**
|
518 | * Reload a single file
|
519 | * The reload method will inform all browsers about changed files and will either cause the browser
|
520 | * to refresh, or inject the files where possible.
|
521 | */
|
522 | reload(file: string): void;
|
523 | /**
|
524 | * Reload multiple files
|
525 | * The reload method will inform all browsers about changed files and will either cause the browser
|
526 | * to refresh, or inject the files where possible.
|
527 | */
|
528 | reload(files: string[]): void;
|
529 | /**
|
530 | * The reload method will inform all browsers about changed files and will either cause the browser
|
531 | * to refresh, or inject the files where possible.
|
532 | */
|
533 | reload(options: { stream: boolean }): NodeJS.ReadWriteStream;
|
534 | /**
|
535 | * The stream method returns a transform stream and can act once or on many files.
|
536 | * @param opts Configuration for the stream method
|
537 | */
|
538 | stream(opts?: StreamOptions): NodeJS.ReadWriteStream;
|
539 | /**
|
540 | * Instance Cleanup.
|
541 | */
|
542 | cleanup(fn?: (error: NodeJS.ErrnoException, bs: BrowserSyncInstance) => void): void;
|
543 | /**
|
544 | * Register a plugin.
|
545 | * Must implement at least a 'plugin' property that returns
|
546 | * callable function.
|
547 | *
|
548 | * @method use
|
549 | * @param {object} module The object to be `required`.
|
550 | * @param {object} options The
|
551 | * @param {any} cb A callback function that will return any errors.
|
552 | */
|
553 | use(module: { "plugin:name"?: string | undefined, plugin: (opts: object, bs: BrowserSyncInstance) => any }, options?: object, cb?: any): void;
|
554 | /**
|
555 | * Callback helper to examine what options have been set.
|
556 | * @param {string} name The key to search options map for.
|
557 | */
|
558 | getOption(name: string): any;
|
559 | /**
|
560 | * Stand alone file-watcher. Use this along with Browsersync to create your own, minimal build system
|
561 | */
|
562 | watch(patterns: string, opts?: chokidar.WatchOptions, fn?: (event: string, file: fs.Stats) => any)
|
563 | : NodeJS.EventEmitter;
|
564 | /**
|
565 | * The internal Event Emitter used by the running Browsersync instance (if there is one). You can use
|
566 | * this to emit your own events, such as changed files, logging etc.
|
567 | */
|
568 | emitter: NodeJS.EventEmitter;
|
569 | /**
|
570 | * A simple true/false flag that you can use to determine if there's a currently-running Browsersync instance.
|
571 | */
|
572 | active: boolean;
|
573 | /**
|
574 | * A simple true/false flag to determine if the current instance is paused
|
575 | */
|
576 | paused: boolean;
|
577 | }
|
578 | }
|
579 |
|
580 | declare const browserSync: browserSync.BrowserSyncStatic;
|
581 | export = browserSync;
|
582 |
|
\ | No newline at end of file |