feat(api): Create InstantSearch App v3 (algolia/create-instantsearch-…

…app#10)

* feat: Support InstantSearch templates (a870767af9a409275f2a749923cc2d2e9f5fc37b)
  Closes algolia/create-instantsearch-app#9
* feat: Support custom templates (algolia/create-instantsearch-app#30)
* test(e2e): Test template installations (algolia/create-instantsearch-app#14)
* test(e2e): Test template snapshots (9b938cca54b5e583284ec4778c22a333bbf570e7)
* ci(travis): Add Travis configuration (algolia/create-instantsearch-app#22)
* docs(readme): Update documentation (algolia/create-instantsearch-app#26)
* feat(release): Create templates release script (algolia/create-instantsearch-app#27)
* feat(release): Create release scripts (algolia/create-instantsearch-app#28)

.editorconfig

@@ -0,0 +1,10 @@
+# http://editorconfig.org
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true

.eslintignore

@@ -0,0 +1,2 @@
+**/node_modules/**
+/templates

.eslintrc.js

@@ -0,0 +1,8 @@
+module.exports = {
+  extends: ['algolia', 'algolia/jest'],
+  rules: {
+    'import/no-commonjs': 'off',
+    'no-console': 'off',
+    'no-process-exit': 'off',
+  },
+};

.gitignore

@@ -1 +1,16 @@
+# dependencies
 node_modules
+
+# misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# release
+/build

.travis.yml

@@ -0,0 +1,16 @@
+language: node_js
+node_js:
+  - 8
+  - 9
+  - 10
+cache:
+  - yarn: true
+before_install:
+ - curl -o- -L yarnpkg.com/install.sh | bash -s -- --version 1.7.0
+ - export PATH=$HOME/.yarn/bin:$PATH
+script:
+  - "${SCRIPT}"
+env:
+  matrix:
+  - SCRIPT="yarn test && yarn lint"
+  - SCRIPT="yarn test:e2e"

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015-present Algolia, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,33 +1,216 @@
-# create-instantsearch-app
+# Create InstantSearch App
 
-Start your next instantsearch app in a ms ⚡️
+> Build InstantSearch apps at the speed of thoughts ⚡️
 
-`create-instantsearch-app` is a command line utility that helps you quick start your next search app using [Algolia InstantSearch.js](https://community.algolia.com/instantsearch.js/v2).
+[![Build Status][travis-svg]][travis-url] [![Version][version-svg]][package-url] [![License][license-image]][license-url]
+
+`create-instantsearch-app` is a command line utility that helps you quick start your InstantSearch app using any [Algolia][algolia-website] InstantSearch flavor ([InstantSearch.js][instantsearchjs-github], [React InstantSearch][react-instantsearch-github], [Vue InstantSearch][vue-instantsearch-github] and [Angular InstantSearch][angular-instantsearch-github]).
+
+## Get started
+
+> The tool requires Node ≥ 8.
+
+```
+npm init instantsearch-app my-app
+cd my-app
+npm start
+```
+
+Open http://localhost:3000 to see you app.
+
+<details>
+  <summary>I use an older <code>npm</code> version</summary>
+
+[`npm-init <@scope>` ](https://docs.npmjs.com/cli/init) is only available on recent `npm` versions. If it's not available, install `create-instantsearch-app` globally and run the binary.
+
+```
+npm install --global create-instantsearch-app
+create-instantsearch-app my-app
+cd my-app
+npm start
+```
+
+</details>
+
+---
+
+Alternatively, you can use [Yarn](https://http://yarnpkg.com):
+
+```
+yarn create instantsearch-app my-app
+cd my-app
+yarn start
+```
 
 ## Usage
 
-`create-instantsearch-app` is a node based tool, in order to use you need node and npm installed on your computer. Have a look at their documentation to [get started](https://docs.npmjs.com/getting-started/installing-node) or use [nvm](https://github.com/creationix/nvm) (advanced)
+This package comes with the module `createInstantSearchApp(path, options?, tasks?)` and the command-line tool `create-instantsearch-app`.
 
-We recommend to use Yarn as an alternative to NPM for handling dependencies in Node projects because it offers some nice integration with CLI tools like `create-instantsearch-app`.
+```
+$ create-instantsearch-app --help
 
-### Using NPM
+  Usage: create-instantsearch-app <project-directory> [options]
 
-Installation:
+  Options:
 
-```sh
-npm install -g create-instantsearch-app
+    -v, --version                                      output the version number
+    --name <name>                                      The name of the application
+    --app-id <appId>                                   The application ID
+    --api-key <apiKey>                                 The Algolia search API key
+    --index-name <indexName>                           The main index of your search
+    --main-attribute <mainAttribute>                   The main searchable attribute of your index
+    --attributes-for-faceting <attributesForFaceting>  The attributes for faceting
+    -t, --template <template>                          The InstantSearch template to use
+    --library-version <template>                       The version of the library
+    -c, --config <config>                              The configuration file to get the options from
+    --no-installation                                  Ignore dependency installation
+    -h, --help                                         output usage information
 ```
 
-Create a new project:
+### Options documentation
+
+#### `--template`
+
+Supported templates are:
+
+- [`InstantSearch.js`][instantsearchjs-github]
+- [`React InstantSearch`][react-instantsearch-github]
+- [`Vue InstantSearch`][vue-instantsearch-github]
+- [`Angular InstantSearch`][angular-instantsearch-github]
+
+You can also [create your own template](#templates) and specify its path.
+
+#### `--config`
 
-```sh
-create-instantsearch-app [name-of-your-new-app]
+The `config` flag is handy to automate app generations.
+
+<h6 align="center">`config.json`</h6>
+
+```json
+{
+  "name": "my-app",
+  "template": "InstantSearch.js",
+  "libraryVersion": "2.8.0",
+  "appId": "MY_APP_ID",
+  "apiKey": "MY_API_KEY",
+  "indexName": "MY_INDEX_NAME",
+  "searchPlaceholder": "Search",
+  "mainAttribute": "name",
+  "attributesForFaceting": ["brand", "location"]
+}
 ```
 
-### Using Yarn
+Create the app based on this configuration:
+
+```
+create-instantsearch-app my-app --config config.json
+```
+
+## API
+
+`create-instantsearch-app` is based on the module `createInstantSearchApp(path, options?, tasks?)`.
 
-With yarn you don't have an install step, just use:
+```javascript
+const createInstantSearchApp = require('create-instantsearch-app');
 
-```sh
-yarn create instantsearch-app [name-of-your-new-app]
+const app = createInstantSearchApp('~/lab/my-app', {
+  template: 'InstantSearch.js',
+  libraryVersion: '2.0.0',
+  mainAttribute: 'name',
+  attributesForFaceting: ['keywords'],
+});
+
+app.create().then(() => console.log('App generated!'));
+```
+
+### Tasks
+
+The app generation follows this lifecycle:
+
+1.  **Setup**
+2.  **Build**
+3.  **Install**
+4.  (**Clean**) _if the project generation fails_
+5.  **Teardown**
+
+Each task can be plugged to the third argument of the call `createInstantSearchApp(path, options?, tasks?)`.
+
+<h6 align="center">Tasks example</h6>
+
+```javascript
+const app = createInstantSearchApp(
+  'my-app',
+  { template: 'InstantSearch.js' },
+  {
+    setup(config) {
+      // Check the project requirements
+    },
+    teardown(config) {
+      // Go to the project folder
+    },
+  }
+);
+
+app.create();
+```
+
+### Templates
+
+To use your own template, create a file `.template.js` at the root of your template directory. This is the configuration file that `createInstantSearchApp()` reads to retrieve the version of the library to install from `npm` and the [tasks](#tasks) to process.
+
+<h6 align="center">`.template.js`</h6>
+
+```javascript
+const { execSync } = require('child_process');
+
+module.exports = {
+  libraryName: 'algoliasearch-helper',
+  tasks: {
+    install(config) {
+      execSync(`cd ${config.path} && npm install`);
+    },
+    teardown(config) {
+      console.log('Begin by running: npm start');
+    },
+  },
+};
 ```
+
+All your template files that need to be injected values should have the `.hbs` extension ([read more on Handlebars](https://handlebarsjs.com)). You can see examples in the [`templates`](templates) folder. Then, pass the path to your template when generating the app.
+
+Using the API:
+
+```javascript
+const app = createInstantSearchApp('my-app', {
+  template: './my-custom-template',
+});
+
+app.create();
+```
+
+Using the CLI:
+
+```
+create-instantsearch-app my-app --template ./my-custom-template
+```
+
+## License
+
+Create InstantSearch App is [MIT licensed](LICENSE).
+
+<!-- Badges -->
+
+[version-svg]: https://img.shields.io/npm/v/create-instantsearch-app.svg?style=flat-square
+[package-url]: https://npmjs.org/package/create-instantsearch-app
+[travis-svg]: https://img.shields.io/travis/algolia/create-instantsearch-app/develop.svg?style=flat-square
+[travis-url]: https://travis-ci.org/algolia/create-instantsearch-app
+[license-image]: http://img.shields.io/badge/license-MIT-green.svg?style=flat-square
+[license-url]: LICENSE
+
+<!-- Links -->
+
+[algolia-website]: https://www.algolia.com/?utm_medium=social-owned&utm_source=GitHub&utm_campaign=create-instantsearch-app%20repository
+[instantsearchjs-github]: https://github.com/algolia/instantsearch.js
+[react-instantsearch-github]: https://github.com/algolia/react-instantsearch
+[vue-instantsearch-github]: https://github.com/algolia/vue-instantsearch
+[angular-instantsearch-github]: https://github.com/algolia/angular-instantsearch