A Yeoman generator to start a GarlicTech web app.

[![Build Status][build]][link]
[build]: https://travis-ci.org/garlictech/generator-garlic-webapp.svg?branch=master
[link]: https://travis-ci.org/garlictech/generator-garlic-webapp

Getting Started

$3

The Yeoman generator and the loopback generator must be installed:

``bash
$ sudo npm install -g yo generator-loopback
`

$3

To install the generator-garlic-webapp, run:

`bash
$ sudo npm install -g generator-garlic-webapp
`

The generator has some peer dependencies. If they are missing (for instance, the loopback.io generator), you must also install them globally. The above install
command will warn you and list the missing software in this case.

Environment variables

When you use private Github and NPM repos, you have to specify some tokens to grant access to the resources. They are accessed via environment variables. In addition, you can work for several organizations in the same time, so you may have several scopes. This situation is handled by the following rules:

* Your personal github access token must be in the `GITHUB_TOKEN` environment variable.
* Your NPM token must be in environment variables like: `NPM_TOKEN_Garlictech`:

* Prefix: `NPM_TOKEN`
* Suffix: your scope in CamelCase.

Some of the generators may use `NPM_TOKEN` as well. If both token variables are set, then the more specific one (`NPM_TOKEN_Garlictech`) has priority.

The Generators

General remarks

* Some of the generators ask for scope. The scope must be the organization id in github (so, for garlictech projects, it must be garlictech). You can see this ID in the URL of the github repos.
* Some of the generator questions provide default values. They are either calculated (for example, based on the current directory), or the generator records the last value you selected, and offers that.
* Selecting a default: simply press return.

$3

tl;dr

`
mkdir my-project
cd my-project
yo garlic-webapp:angular2


Select garlictech scope (the default)

npm run setup
npm run build:docker
npm start
npm run unittest
npm run e2etest
npm run build:prod

...then develop something, then:

git add .
npm run commit
`

$3

`
mkdir my-project
cd my-project
yo garlic-webapp:angular2
`

Answer the (straighforward) questions, then you have a scaffolded Angular 2 app that you can build and start immediately.

$3

You can use the following generators (deduct from their names what they generate):

`
yo garlic-webapp:ng2-service
yo garlic-webapp:ng2-module
yo garlic-webapp:ng2-component
`

You can add the base folder of the component and the component name. Mind, that the generated file names do not follow the usual Angular 2 conventions, because we utilize webpack file resolution.

Mind, that the generators generete new files only: for example, you can generate a service in a module folder with the intention that the module should provide the service. You have to add the service manually to the provides array of the module.

Develop an Angular 1 client side app

tl;dr

`
mkdir my-project
cd my-project
yo garlic-webapp:angular2


Select garlictech scope (the default)

npm run setup
npm run build
npm start
npm run unittest
npm run e2etest

...then develop something, then:

git add .
npm run commit
`

Your web site is: http://localhost:8081.

The generator generates files for the Garlictech workflow. For the details of the above procedure, consult this site.

$3

All the client projects are based on Angular JS, plus some dockerized software (webpack, karma, protractor).

* Create a project directory. The directory naming must be in kebabcase (for example: _My Project_ should be in directory _my-project_) Enter the directory, then:

`bash
$ yo garlic-webapp
`
* Type a scope or press return to select the default. The scope must be the organization id in github (so, for garlictech projects, it must be garlictech. You can see this ID in the URL of the github repos).
* Select project type.
* `module`: the project is an AngularJS module. There is no `index.html`, therefore the generator creates a "site" for you that you can use during the development as some kind of sandbox. `npm start` will use this site.
* `site`: A regular, AngularJS based site. In this case, `index.html` will be generated in the `src` folder, as the entry point of your site.
* Confirm if you want to create a Github repo for the project. If you reply yes, the github/travis generator starts.

Good to know

* The generated module names will follow the following convention (assuming that your organization is my-organization, your project folder is my-module-name):

Main angular module name:

`
MyOrganization.MyModuleName
`

Then, any services, etc. are named like:

`
MyOrganization.MyModuleName.MyService
`

The directives are named:

`
myOrganizationMyModuleMyDirective # in javascript
my-organization-my-module-my-directive # in HTML
`

* if your project folder name ends with `-angular` (like a-cool-component-angular), then `-angular` will be omitted in the angular module name generation.

After that, it scaffolds the webapp.

The generated code will utilize the Docker based client side workflow package. Go there for more information about how to develop your site/module.

Develop a server project

tl;dr

`
mkdir my-project
cd my-project
yo garlic-webapp:server --force
npm run setup-dev
make build
make start


See your server in http://0.0.0.0:3000

...then develop something, then:

git add .
npm run commit
`

The generator generates files for the Garlictech workflow. For the details of the above procedure, consult this site.

$3

* Create a project directory. The directory naming must be in kebabcase (for example: _My Project_ should be in directory _my-project_) Enter the directory, then:

`bash
$ yo garlic-webapp:server --force
`

Mind the --force parameter. We use composed generators and sometimes, files must be overwritten. This option eliminates the confirmation questions.

* Type a scope or press return to select the default. The scope must be the organization id in github (so, for garlictech projects, it must be garlictech. You can see this ID in the URL of the github repos).
* Select the project type.
** empty: nothing. You start server development from scratch.
** express: an Express server.
** loopback: a loopback server. In this case, the loopback generator also starts.
* Accept the default application name!
** The following environment variables are taken into account: DOCKER_REPO.

After that, the generator scaffolds the server.

$3

For development, we use make. For example, build the development server image:

`make build`

Read the Makefile comments for all the commands, they are obvious. Normally, they start a docker container and execute a command.




$3

`make build`

It uses the generated Dockerfile.dev and created a development server image. It id derived from the workflows-server image. Go here for all the npm packages pre-installed.
You do not have to add the preinstalled packages to package.json, just start requiring them.

$3

You can start a bash session inside a container.

`
make bash
`

The generators

During the generator examples, we use MyOrganization az as example organization name. Mind, that the organization refers to the github organization, and must be in CamelCase. For example, if your organization is at
`http://github.com/my-organization`, then the label you should use everywhere is `MyOrganization`.

Generators for AngularJS projects

`
yo garlic-webapp:directive
`

Generate a directive. Asks for teh tirective name. If template extraction is enabled, then it generates ID for the directive templates in $templateCache,
and adds references to the ui and style files in the src/templates module. Do, the template of the directive can be replced in another project.

Otherwise, style and ui files are referenced directly from directive.coffee. In this case, teh templates cannot be replaced.

The generator registers the directive in the main Angular module, so it ia available immediately.

Allow rewiting files when it asks for it!

Generic generators

They work both on server and client sides.

$3

Creates and initializes a github repo for the project. It also configures Travis CI, and sets up the Slack notifications.

`
yo garlic-webapp:github
`

The organization is taken from the scope variable of `.yo-rc.json`. Then, you have to add some tokens. The generator
can obtain those tokens from environment variables as well, it will offer them as defaults. The generation process will display those variable names.
Some variable names follow the convention in the docker-image section.

You can obtain the Slack webhook URL from the settings of any github repos (sending messages to the same Slack channel). As for Slack token, ask the admin of the organization.

Also, ask the development team id from the admin.

$3

`
yo garlic-webapp:docker-image
`

Creates a docker image template in the `docker-images` folder. Also, creates organization-specific build scripts.

Before that, you have to set the following environment variables:

`
export NPM_TOKEN_MyOrganization=
export DOCKER_USERNAME=
export DOCKER_PASSWORD=
`

Alternatively, you can set `NPM_TOKEN` instead of `NPM_TOKEN_MyOrganization`. If both are set, `NPM_TOKEN_MyOrganization` has priority.

Do not forget to change labels in docker.my-organization.com, if your docker repo is in a different host.

Known issues

* If you changed `scripts/build.sh` (because, for example, your docker registry is not in the generated docker.my-organization.com), then do not allow the generator to overwrite this file. If you did, you have to re-implement your changes.

$3

`
yo garlic-webapp:commitizen
`

We suggest using commitizen during github commits. This generator prepares your project for this. The default generator also invokes this, by default. The actual commitizen packages are in the workflows-common docker image.

$3

`
yo garlic-webapp:semantic-release
``

We suggest using semantic release for travis ci-based automated releasing and labeling. This generator prepares your project for this. The default generator also invokes this, by default. The actual semantic-release packages are in the workflows-common docker image.