Angular-Gulp

Version

Version 2.

Built using the gulp-site-template repo.

Requirements

Node.js

Installation and Usage

Developers

Download or clone the repo.
cd into the project directory.
Run npm install to install dependencies.
Run npm run compile:dev to compile for the files for local development.
Run npm run serve to start the local server.
Open localhost:3000.

For your convenience, this project utilises Gulp's 'watch' functionality. In order to activate it while developing, run gulp watch. For more information about Gulp watch, check the Gulp documentation.

Components

Located in: src/app/components

Sample component - A sample component meant as an example. Feel free to delete.
Error page - A sample error page, to which the user is redirected whenever the route doesn't match an existing route (already configured in the routing module). Feel free to configure according to your needs.

Services

Located in: src/app/services

Sample service - Provided in the app root. A sample service meant as an example. Feel free to delete.

Production Scripts

The project contains two production-ready scripts:

server.js - Contains a basic Express server with compression, in order to serve files in a production environment.
env-config.js - Contains a script to find and replace environment variables (in src/environments) with configured environment variables from the hosting environment. This script is an optional adjustment - feel free to delete it if you don't need it.

Dependencies

Gulp

The site uses several tools to maximise compatibility:

Gulp - Gulp enables running tasks automatically. You can read more on the Gulp website. Gulp is a Node.js tool, so it requires installing Node.
Gulp-Postcss with Autoprefixer Plugin - A Gulp plugin which adds the necessary browser prefixes to the CSS file. For more info check the Gulp-postcss page and the Autoprefixer page on NPM.
Rollup (with @rollup/stream) - A module bundler for JS. Rollup bundles up the main module (AppModule) and converts it from TypeScript to ES6. For more info, check the Rollup repo and Gulp's Rollup + Gulp recipe.
Gulp-Babel - A Gulp plugin for the transpiler Babel. Converts ES6 output to the highly supported ES5 (currently isn't used). For more info check the plugin's GitHub repository.
Gulp-Uglify - A Gulp plugin which minimises the single ES5 file (Babel's output). For more info check the Gulp-uglify page on NPM.
Gulp-Sourcemaps - A Gulp plugin utilizing the source maps tool. For more info check the Gulp-sourcemaps page on NPM.
Gulp-Rename - A gulp plugin used to rename files. Used to rename the main module JS and to change the directory name of all HTML files. For more info check the Gulp-rename page on NPM.
Gulp-replace - A string replace plugin for Gulp. Used to change the templateUrls in the final JS file. For more info, check the Gulp-replace page on NPM.

Angular

@angular/animations - Angular's animations library.
@angular/common - Angular's commonly needed services, pipes and directives.
@angular/compiler - Angular's template compiler.
@angular/compiler-cli - Command-line interface to invoke Angular's compiler.
@angular/core - Critical runtime parts of the Angular framework.
@angular/forms - Support for template-driven and reactive forms.
@angular/platform-browser - Everything DOM and browser-related.
@angular/platform-browser-dynamic - Providers and methods for compiling and running the app.
@angular/router - Angular's router module.
rxjs - Contains an implementation of observables, which many Angular APIs use.
typescript - TypeScript language server, which Angular uses.
zone.js - Implementation of zones for JavaScript (used by Angular).
core-js - Modular standard library for JavaScript. Contains polyfills. For more information, check the GitHub repo.

For more information about Angular's required NPM packages, check the Angular docs.

Testing Dependencies

This project's tests are run using the Jasmine framework and the Karma runner. Thus, testing requires several packages:

Jasmine - An open-source behaviour-driven testing framework. For more information, check Jasmine's official site. Included packages:
- jasmine-core
- jasmine-spec-reporter
- @types/jasmine - A typed version, required in order to write TypeScript tests.
Karma - An open-source test-runner, used to run the tests on various devices with a test server. For more information, check Karma's official site. Included packages:
- karma
- karma-jasmine - A Karma adapter for the Jasmine framework. Project repo.
- karma-jasmine-html-reporter - A reporter that shows test results in HTML. NPM page..
- karma-chrome-launcher - A launcher for Chrome, Chrome Canary and Chromuim. Project repo..
- karma-coverage - Code coverage generator. Project repo.
- karma-coverage-istanbul-reporter - Code coverage generator reporter. NPM page.
- karma-sourcemap-loader - A preprocessor that loads existing source maps. NPM page.
- karma-rollup-preprocessor - A rollup preprocessor for karma, used to bundle up the tests. NPM page.
Cypress - An open-source test runner, used primarily for e2e and integration tests. For more information, check their official documentation.

Production Dependencies

Express - This project uses Express in order to run a basic server in deployment. This server is used to send the static files and script to the user. For more information, check the Express website.
Compression - A Node extension used to compress production files when sending them from the Express server to the client. For more information, check the compression NPM page.
dotenv - A Node extension for accessing environment variables. Used by the frontend while in production mode. For more information, check the dotenv NPM page.

Testing

Writing Tests

Tests are written in TypeScript and each component's tests are located in the same directory as the component. Test files' names follow this format: <component_name>.spec.ts. This format is the way tests are picked up by the main testing file, and so it's important to keep to it.

End-to-end tests are also written in TypeScript. All end-to-end tests are located in e2e/src, and are named in a similar manner to regular specs files: <something_to_test>.spec.ts. The Cypress config is in the root (in cypress.json), but the plugins and support files are in the e2e folder as well.

Running Tests

Running tests is done through the dedicated Gulp task. All you need to do is run gulp test in the terminal; this will start Karma and trigger Rollup's compilation of tests and project files.

Running end-to-end tests is done through an npm script. Running npm run e2e in the terminal will bundle up assets for testing, fire up the development server and run Cypress.

Hosting

If you want to clone and host your own version, you can do so by using the following guide (the following commands are for Heroku, but they can be adjusted depending on your host):

Create a Heroku account (skip this step if you already have an account).
Install the Heroku command line interface.
In your Terminal, enter heroku login. This triggers logging in via the CLI.
Enter heroku create <APP_NAME> (with your own app name). If successful, Heroku returns the live version's URL (will be referred to as <LIVE_URL>) and the Git repo link (will be referred to as <GIT_URL>).
Add your environment variables (if there are any).
Make sure you're in the top directory (FSND-capstone). In your terminal, enter git remote add heroku-client <GIT_URL>.
Enter git push heroku-client master. This triggers the app build. If successful, you'll get a 'Verifying deploy... done.' message.
All done! Now you can visit your <GIT_URL> to see the live app.

Known Issues

There are no current issues at the time.

shirblc/angular-gulp