{"id":18320857,"url":"https://github.com/bazaarvoice/scoutfile","last_synced_at":"2025-04-05T22:32:04.484Z","repository":{"id":28117733,"uuid":"31616647","full_name":"bazaarvoice/scoutfile","owner":"bazaarvoice","description":"A Node module for generating a scout file for a client-side JS app","archived":false,"fork":false,"pushed_at":"2022-02-11T16:26:03.000Z","size":209,"stargazers_count":34,"open_issues_count":5,"forks_count":18,"subscribers_count":18,"default_branch":"master","last_synced_at":"2024-08-08T15:04:36.957Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bazaarvoice.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-03-03T19:23:07.000Z","updated_at":"2021-02-17T10:04:25.000Z","dependencies_parsed_at":"2022-07-25T17:52:37.841Z","dependency_job_id":null,"html_url":"https://github.com/bazaarvoice/scoutfile","commit_stats":null,"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bazaarvoice%2Fscoutfile","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bazaarvoice%2Fscoutfile/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bazaarvoice%2Fscoutfile/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bazaarvoice%2Fscoutfile/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bazaarvoice","download_url":"https://codeload.github.com/bazaarvoice/scoutfile/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223221181,"owners_count":17108525,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-05T18:17:40.103Z","updated_at":"2024-11-05T18:17:40.840Z","avatar_url":"https://github.com/bazaarvoice.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![NPM version][npm-image]][npm-url]\n[![Build Status][travis-image]][travis-url]\n[![Dependency Status][daviddm-url]][daviddm-image]\n\n# Scout\n\n[Developer README](./CONTRIBUTING.md)\n\nThis repository provides a Node module that can be used to generate a \"scout\"\nfile for a client-side JavaScript application.\n\n## Requirements\n\nTo use this project, it is assumed you already have an environment running\nNode 5.\n\nThe application module is written using ES6. In order to use the source you may need to\nprovide your own transpiler, depending on your supported browsers.\n\nWe also take advantage of some built-ins that you may need to polyfill:\n\n- `Promise`: http://caniuse.com/#feat=promises\n\n## Roadmap and Issues\n\nSee the [issues](//github.com/bazaarvoice/scoutfile/issues/) page for details on current development and future\nplans. If there is scout file functionality that your project needs and is not\nprovided currently, please open an issue. Bug reports are also appreciated.\n\n## Overview\n\nA scout file is a small JavaScript file that serves as a loader for a client-\nside JavaScript application. The scout file must always be less than 14k when\nminified and gzipped. The scout file should have a short TTL, so changes will\ntake effect quickly; the resources it loads should have versioned URLs,\nallowing them to have long TTLs.\n\n[Read more about scout files and deploying JavaScript\napplications](https://alexsexton.com/blog/2013/03/deploying-javascript-applications/).\n\nThe scout file's key responsibilities are:\n\n- Load the core application resources\n- Queue calls to render the core application until the core application is loaded\n- Provide a way for the core application to access configuration information\n- Provide a way for the core application to respond to any queued render calls\n- Provide a way for the core application to redefine render behavior for future calls\n\nThis project uses [webpack](http://webpack.github.io/) to generate the built\nscout file. It allows client-side JavaScript applications to specify the\nfunctionality required in their scout file and provide any code that is unique\nto their application that should be included in the scout file. It also\nprovides loaders for common tasks, such as using a JSON file as a source, or\ninlining CSS. See below for more details about [loaders](#Loaders)\n\n## Example\n\nTo try an example:\n\n- Clone this repo:\n\n```\ngit clone https://github.com/bazaarvoice/scoutfile.git\n```\n\n- Copy the files from the example directory of the repo:\n\n```\ncd scoutfile\ncp -r example ../scout-example\n```\n\n- Run the example:\n\n```\ncd ../scout-example\nnpm install\nnode generator.js\n```\n\n- Run the example Grunt task (make sure to `npm install -g grunt-cli` first if\n  you don't already have the Grunt CLI installed):\n\n```\ngrunt scoutfile\n```\n\n## Usage\n\nYou will need to `npm install` the scoutfile module and save it to your\nproject's dependencies:\n\n```\nnpm install --save scoutfile\n```\n\n*Check the repo for the latest stable version, and modify the command above as required.*\n\nYou can now write your application's portion of the scout file. The example\nbelow shows an application that includes modules provided by the scout project\n(see [Including common functionality via modules](#including-common-functionality-via-modules)),\nas well as a JSON resource (see [Including non-JS-resources](#including-non-js-resources)).\n\n```js\nvar App = require('scoutfile/lib/browser/application');\nvar loader = require('scoutfile/lib/browser/loader');\n\nvar config = require('json!./config.json');\n\nvar MyApp = App('MyApp');\n\nMyApp.config = config;\nMyApp.loadScript = loader.loadScript;\n\nloader.loadScript(config.appJS);\nloader.loadStyleSheet(config.appCSS);\n```\n\n### Including common functionality via modules\n\nThis project provides modules for common tasks, such as reading and writing\ncookies; loading JavaScript and CSS; and queueing JavaScript calls from the\nhost site until the core application resources arrive. [Learn more about the\nmodules provided by this project][modules].\n\n### Including non-JS resources\n\nThe scout project provides access to several Webpack\n[loaders](http://webpack.github.io/docs/using-loaders.html). These assist with\ncommon tasks such as embedding a JSON file into the built scout file; loading\nCSS into the built scout file; loading templates into the built scout file;\nand other tasks. The following loaders are currently provided:\n\n- [Handlebars](https://github.com/altano/handlebars-loader)\n- [JSON](https://github.com/webpack/json-loader)\n- [Raw](https://github.com/webpack/raw-loader)\n- [Sass](https://github.com/jtangelder/sass-loader)\n- [Yaml](https://github.com/okonet/yaml-loader)\n- [CSS](https://github.com/webpack/css-loader)\n- [File](https://github.com/webpack/file-loader)\n\nIf your project would benefit from a loader that is not listed here, please\nfork this repository, create a branch, add the loader via `npm install\n--save`, and then open a pull request explaining the need.\n\n## Generating a scout file\n\n### Via Node\n\nThe following code will log the generated scout file as a string:\n\n```js\nvar scout = require('scoutfile');\nscout.generate({\n  appModules: [\n    {\n      name: 'MyApp',\n      path: './app/scripts/scout/main.js'\n    }\n  ],\n\n  // Specify `pretty` to get un-uglified output.\n  pretty: true\n}).then(function (scout) {\n  console.log(scout);\n});\n```\n\n### Via Grunt\n\nThis project also provides a Grunt task. To use it, first, load the Grunt task\nin your Gruntfile.js:\n\n```\ngrunt.loadNpmTasks('scoutfile');\n```\n\nThis creates a `scoutfile` Grunt multitask. You can configure the task as\nfollows, providing the source modules and the destination for each multitask\nconfiguration:\n\n```js\ngrunt.initConfig({\n  // ...\n  scoutfile: {\n    server : {\n      src : [\n        {\n          name : 'MyApp',\n          path : './app/scripts/scout/main.js'\n        }\n      ],\n      dest : '.tmp/scripts/scout.js',\n\n      // Specify `pretty` to get un-uglified code\n      pretty : true\n    },\n    test : {\n      src : [\n        {\n          name : 'MyApp',\n          path : './app/scripts/scout/main.js'\n        }\n      ],\n      dest : '.tmp/scripts/scout.js'\n    }\n  },\n  // ...\n});\n```\n\nTo use the task, you can now run:\n\n```bash\ngrunt scoutfile:server\n```\n\n### Controlling the Output\n\n#### Specifying a \"namespace\"\n\nBy default, the scout will create `window.APP`, and use that as its namespace\nif it needs to expose anything globally. This namespace can be accessed via\nthe `lib/browser/namespace` module. You can specify a different namespace by\nsetting the `namespace` property of the configuration that you pass to the\ngenerator.\n\nSpecifying a namespace when using the scout module:\n\n```js\nvar scout = require('scoutfile');\nscout.generate({\n  appModules: [\n    {\n      name: 'MyApp',\n      path: './app/scripts/scout/main.js'\n    }\n  ],\n\n  // Override the default `APP` namespace\n  namespace: 'APPLICATION',\n\n  // Specify `pretty` to get un-uglified output.\n  pretty: true\n}).then(function (scout) {\n  console.log(scout);\n});\n```\n\nSpecifying a namespace for a Grunt task:\n\n```\ngrunt.initConfig({\n  // ...\n  scoutfile: {\n    server : {\n      src : [\n        {\n          name : 'MyApp',\n          path : './app/scripts/scout/main.js'\n        }\n      ],\n      dest : '.tmp/scripts/scout.js',\n\n      // Override the default `APP` namespace\n      namespace: 'APPLICATION',\n\n      // Specify `pretty` to get un-uglified code\n      pretty : true\n    }\n  },\n  // ...\n});\n```\n\n#### Using build flags\n\nYou can also define flags that can be used to control build output; for\nexample, you could define a flag `DEBUG` that you could then use to only\nexecute certain code when the flag is true:\n\n```\nif (DEBUG) {\n  doSomething();\n}\nelse {\n  doSomethingElse();\n}\n```\n\nIf a flag is false for a certain build configuration, and the `pretty` option\nis not true, then Uglification will include dead code removal. So, for\nexample, if the `DEBUG` flag was set to false for a certain build\nconfiguration, the above code would be reduced to:\n\n```\ndoSomethingElse();\n```\n\nTo specify flags, add a `flags` property to the config you provide to the\ngenerator (or the config for each grunt task). The value of this property\nshould be an object, such as:\n\n```\nflags : {\n  DEBUG : true\n}\n```\n\n**If you are using a flag in your application's scout file code, note that\nit's important to define it for all build configurations -- not just for the\nbuild configuration for which it is true.**\n\nRead more about flags and the Webpack `DefinePlugin`\n[here](http://webpack.github.io/docs/list-of-plugins.html#defineplugin).\n\n#### Including configuration information\n\nTo specify configuration data that should be available within the generated\nscout file, add an `appConfig` property to the config you provide to the\ngenerator (or the config for each grunt task).\n\n```\nappConfig : {\n  reviews : true,\n  comments : false,\n  customerName : 'atticus'\n}\n```\n\nThe value you provide here should be an object that can be serialized using\n`JSON.stringify`. See the [modules][modules] documentation for details on how\nto access this data via the `appConfig` module.\n\n#### Including a banner\n\nTo specify one or more \"banners\" to appear at the top of your file, add a\nbanner property to the config you provide to the generator (or the config\nfor each grunt task).\n\n```\nbanner : {\n  content : 'Copyright 2015 Bazaarvoice. All rights reserved.'\n}\n```\n\nBy default, a banner will be inserted as a comment at the top of the\ngenerated file. You can provide an `options` property to insert raw,\nuncommented content instead:\n\n```\nbanner : {\n  content : '\"version:697-test-8e037c82-e49a-4136-ade1-fbe08c281a24\";',\n  options : {\n    raw : true\n  }\n}\n```\n\nYou can also provide an array of banner objects:\n\n```\nbanner : [\n  {\n    content : '\"version:697-test-8e037c82-e49a-4136-ade1-fbe08c281a24\";',\n    options : {\n      raw : true\n    }\n  },\n  {\n    content : 'Copyright 2015 Bazaarvoice. All rights reserved'.\n  }\n];\n```\n\n#### Advanced Webpack configuration and source maps\n\nBy passing in Webpack configuration options to the generator, you can override\nany of the default Webpack configuration that is constructed when generating a\nscout file. Note that this can absolutely break things, for example if you\nprovide your own plugins array that includes plugins used by this library.\n\nA more common use case is to request a source map to be constructed:\n\n```\nvar scout = require('scoutfile');\nscout.generate({\n  appModules: [\n    {\n      name: 'MyApp',\n      path: './app/scripts/scout/main.js'\n    }\n  ],\n\n  // Specify `pretty` to get un-uglified output.\n  pretty: true,\n\n  // Specify overridden Webpack options.\n  webpackOptions: {\n    // Create a source map file main.js.map in addition to the scout file.\n    devtool: 'source-map'\n  }\n}).then(function (sources) {\n  // When requesting a source map file in addition to a scout file, an array\n  // is returned.\n  console.log('Scout: ' + sources[0]);\n  console.log('Source map: ' + sources[1]);\n});\n```\n\nIf using the grunt task, a `sourceMapDest` configuration property must be\nprovided in addition to `dest` if the source map is generated as a separate\nfile:\n\n```\ngrunt.initConfig({\n  // ...\n  scoutfile: {\n    server : {\n      src : [\n        {\n          name : 'MyApp',\n          path : './app/scripts/scout/main.js'\n        }\n      ],\n      dest : '.tmp/scripts/scout.js',\n      sourceMapDest : '.tmp/scripts/scout.js.map'\n\n      // Override the default `APP` namespace\n      namespace: 'APPLICATION',\n\n      // Specify `pretty` to get un-uglified code\n      pretty : true,\n\n      // Specify overridden Webpack options.\n      webpackOptions: {\n        // Create a source map file that will be written to sourceMapDest.\n        devtool: 'source-map'\n      }\n    }\n  },\n  // ...\n});\n```\n\n## Troubleshooting\n\n### loader timeout\n\nUnderstanding the loader module is critical to the usage of this repository. The default timeout is sufficient for common usage, but may not be large enough for environments where load times will be much slower than anticipated, such as slow mobile networks, dial-up connection, use of tunneling Selenium test services such as BrowserStack and Sauce Labs, and so forth. Older browsers such as IE8 may obfuscate timeout problems with other errors, making it difficult to debug such issues.\n\nIf you experience any issues with application load timeouts, review the documentation on the [timeout option][timeout-option] and experiment with larger timeout values.\n\n[npm-url]: https://npmjs.org/package/scoutfile\n[npm-image]: https://badge.fury.io/js/scoutfile.svg\n[travis-url]: https://travis-ci.org/bazaarvoice/scoutfile\n[travis-image]: https://travis-ci.org/bazaarvoice/scoutfile.svg?branch=master\n[daviddm-url]: https://david-dm.org/bazaarvoice/scoutfile.svg?theme=shields.io\n[daviddm-image]: https://david-dm.org/bazaarvoice/scoutfile\n[modules]: ./docs/modules.md\n[timeout-option]: ./docs/modules.md#loader-timeout\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbazaarvoice%2Fscoutfile","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbazaarvoice%2Fscoutfile","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbazaarvoice%2Fscoutfile/lists"}