Update readme, Node commands
This commit is contained in:
parent
547ad63812
commit
32d0c16c31
2 changed files with 122 additions and 66 deletions
167
README.md
167
README.md
|
|
@ -1,97 +1,152 @@
|
||||||
# LocalSpend - Web Application
|
# LocalSpend (Web App.)
|
||||||
|
|
||||||
This repository contains the Web application for the LocalSpend system.
|
Looking to discover if the value of spending local can be measured, understood and shown.
|
||||||
|
|
||||||
|
This repository contains the Web application for the LocalSpend system. See also:
|
||||||
|
|
||||||
|
* the [server](https://github.com/Pear-Trading/Foodloop-Server); and
|
||||||
|
* the [mobile application](https://github.com/Pear-Trading/LocalSpend-Tracker).
|
||||||
|
|
||||||
## Current Status
|
## Current Status
|
||||||
|
|
||||||
| Branch | Status |
|
| Branch | Status |
|
||||||
| --- | --- |
|
|---------------|------------------ |
|
||||||
| `master` | [](https://travis-ci.org/Pear-Trading/FoodLoop-Web) |
|
| `master` | [](https://travis-ci.org/Pear-Trading/FoodLoop-Web) |
|
||||||
| `development` | [](https://travis-ci.org/Pear-Trading/FoodLoop-Web) |
|
| `development` | [](https://travis-ci.org/Pear-Trading/FoodLoop-Web) |
|
||||||
|
|
||||||
## Contents
|
## Table of Contents
|
||||||
|
|
||||||
1. [Getting Started](#getting-started)
|
* [Tech Stack](#tech-stack)
|
||||||
1. [Environments](#environments)
|
* [Features](#features)
|
||||||
1. [Testing](#testing)
|
* [Installation](#installation)
|
||||||
1. [Troubleshooting](#troubleshooting)
|
* [Configuration](#configuration)
|
||||||
1. [Licences](#licenses)
|
* [Usage](#usage)
|
||||||
|
* [Testing](#testing)
|
||||||
|
* [Code Formatting](#code-formatting)
|
||||||
|
* [Documentation](#documentation)
|
||||||
|
* [Acknowledgments](#acknowledgements)
|
||||||
|
* [License](#license)
|
||||||
|
* [Contact](#contact)
|
||||||
|
|
||||||
## Getting Started
|
## Technology Stack
|
||||||
|
|
||||||
To get started with development, you will need an up-to-date version of
|
The Web app. is written in [TypeScript](https://www.typescriptlang.org/).
|
||||||
Node.js, git, and access to either the backend dev. server or a local
|
|
||||||
copy of it from the [LocalSpend Server][LocalLoop-Server] repo.
|
The stylesheets are written in [SCSS](https://sass-lang.com).
|
||||||
|
|
||||||
|
| Technology | Description | Link |
|
||||||
|
|------------|----------------------------|-----------------|
|
||||||
|
| Node.js | JavaScript server runtime | [Link][node] |
|
||||||
|
| AngularJS | JavaScript MVW framework | [Link][angular] |
|
||||||
|
|
||||||
For your local Node.js, we recommend using:
|
For your local Node.js, we recommend using:
|
||||||
- [n][tj/n] for \*nix and Mac; and
|
|
||||||
- [nodist][marcelklehr/nodist] for Windows.
|
- [n][https://github.com/tj/n] for \*nix and Mac; and
|
||||||
|
- [nodist][https://github.com/marcelklehr/nodist] for Windows.
|
||||||
|
|
||||||
We recommend Node.js version 8.0.0+ and npm version 5.3.0+.
|
We recommend Node.js version 8.0.0+ and npm version 5.3.0+.
|
||||||
|
|
||||||
To get this repository set up:
|
[node]: https://nodejs.org/
|
||||||
|
[angular]: https://angularjs.org/
|
||||||
|
|
||||||
1. Clone it
|
## Features
|
||||||
1. Install the dependencies:
|
|
||||||
- `npm install -g @angular/cli`
|
|
||||||
- `npm install`
|
|
||||||
1. Set up the `src/environments/environment.⟨environment⟩.ts` file
|
|
||||||
1. Start the application:
|
|
||||||
- `npm run start:local` if running the app. locally
|
|
||||||
- The app. will automatically reload after source file changes
|
|
||||||
|
|
||||||
[LocalLoop-Server]:https://github.com/Pear-Trading/Foodloop-Server
|
This client app. provides:
|
||||||
[tj/n]:https://github.com/tj/n
|
|
||||||
[marcelklehr/nodist]:https://github.com/marcelklehr/nodist
|
|
||||||
|
|
||||||
## Environments
|
- user authorisation (but not registration);
|
||||||
|
- transaction logging;
|
||||||
|
- presentation of transaction history analysis; and
|
||||||
|
- presentation of leaderboard.
|
||||||
|
|
||||||
The app defaults to using the production environment.
|
## Installation
|
||||||
For other options, see `angular.json`.
|
|
||||||
|
|
||||||
## Build
|
1. Clone the repo. to your dev. environment (`git clone git@github.com:Pear-Trading/FoodLoop-Web.git`);
|
||||||
|
1. enter the new directory (`cd FoodLoop-Web`); and
|
||||||
|
1. install the dependencies:
|
||||||
|
- `npm install -g @angular/cli`; and
|
||||||
|
- `npm install`.
|
||||||
|
|
||||||
Run `ng build` to build the project; the resulting files will be stored in the `dist/` directory. Use the `-prod` flag for a production build.
|
## Configuration
|
||||||
|
|
||||||
|
The app. defaults to using the ‘production’ environment.
|
||||||
|
|
||||||
|
App. configuration settings are found in `package.json`.
|
||||||
|
|
||||||
|
TypeScript configuration settings are found in `tsconfig.json`.
|
||||||
|
|
||||||
|
Angular configuration settings are found in `angular.json`.
|
||||||
|
|
||||||
|
Environment variables are found in `src/environments/environment.⟨environment⟩.ts`.
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
### Development
|
||||||
|
|
||||||
|
- Run `npm run start:dev` to start in development mode using Angular.
|
||||||
|
- Run `npm run build:dev` to build in development mode using Angular.
|
||||||
|
|
||||||
|
### Local
|
||||||
|
|
||||||
|
- Run `npm run start:local` to start in local mode using Angular.
|
||||||
|
|
||||||
|
### Production
|
||||||
|
|
||||||
|
- Run `npm run start:prod` to start in production mode using Angular.
|
||||||
|
- Run `npm run build:prod` to build in production mode using Angular.
|
||||||
|
|
||||||
## Testing
|
## Testing
|
||||||
|
|
||||||
There are two types of test in this codebase:
|
There are two types of test in this codebase:
|
||||||
- unit tests (using Karma); and
|
|
||||||
- E2E tests (using Protractor).
|
|
||||||
|
|
||||||
### Karma Unit Tests
|
- unit tests; and
|
||||||
|
- end-to-end (E2E) tests.
|
||||||
|
|
||||||
To run these, you just need to run `npm run test` - this should work without any further configuration. These run the `*.spec.ts` files next to the normal source files, and are for basic tests for each function on their own.
|
### Unit Tests
|
||||||
|
|
||||||
These tests are a long-running process, and will automatically run on file changes. Just run the command above, and then check back to the browser window that appears to see any errors as you work!
|
Run `npm run test` to run the full test suite using [Karma](https://karma-runner.github.io/latest/index.html).
|
||||||
|
|
||||||
### Protractor E2E Tests
|
Unit tests re-run automatically on source changes.
|
||||||
|
|
||||||
To run these, you will need to run the following command:
|
Tests are found in `*.spec.ts` files alongside normal source files.
|
||||||
|
|
||||||
- `webdriver-manager update`
|
Karma configuration settings are found in `karma.conf.js`.
|
||||||
|
|
||||||
This will download the correct webdriver for you (we use chromedriver), and
|
### End-to-End (E2E) Tests
|
||||||
any other dependencies it needs.
|
|
||||||
After that, you can run the tests with `npm run e2e`.
|
|
||||||
Note these run once, and will need to be re-run every time you want to run an
|
|
||||||
e2e test.
|
|
||||||
|
|
||||||
These tests are best run regularly, and should show if any issues have emerged
|
Run `npm run e2e` to run the full E2E test suite using (Selenium WebDriver](https://www.selenium.dev/documentation/en/webdriver/).
|
||||||
in other parts of the application that you are not aware of, or if some part
|
|
||||||
of the flow through the app has changed significantly.
|
|
||||||
|
|
||||||
## Troubleshooting
|
You may need to run `webdriver-manager update` to install the correct WebDriver and dependencies first.
|
||||||
|
|
||||||
### ‘Error: EACCES: permission denied, access '/usr/local/lib'’ when installing dependencies
|
E2E tests run only once and will need to be re-run manually after source changes.
|
||||||
|
|
||||||
Change npm's default directory by following [these steps](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally#manually-change-npms-default-directory).
|
## Code formatting
|
||||||
|
|
||||||
## Licences
|
### JavaScript/TypeScript Code
|
||||||
|
|
||||||
### CoreUI
|
- Run `npm run lint` to format all JS/TS files with [Codelyzer](http://codelyzer.com/).
|
||||||
|
|
||||||
The interface itself is based off of [CoreUI][core-ui] which is MIT Licenced.
|
Codelyzer configuration settings are found in `tslint.json`.
|
||||||
For information, see `LICENCE.MIT` included in this repo.
|
|
||||||
|
|
||||||
[core-ui]: http://coreui.io
|
## Documentation
|
||||||
|
|
||||||
|
TODO
|
||||||
|
|
||||||
|
## Acknowledgements
|
||||||
|
|
||||||
|
LocalLoop is the result of collaboration between the [Small Green Consultancy](http://www.smallgreenconsultancy.co.uk/), [Shadowcat Systems](https://shadow.cat/), [Independent Lancaster](http://www.independent-lancaster.co.uk/) and the [Ethical Small Traders Association](http://www.lancasteresta.org/).
|
||||||
|
|
||||||
|
The Web client interface is based off of [CoreUI](https://coreui.io/).
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
This project is released under the [MIT license](https://mit-license.org/).
|
||||||
|
|
||||||
|
## Contact
|
||||||
|
|
||||||
|
| Name | Link(s) |
|
||||||
|
|----------------|-------------------|
|
||||||
|
| Mark Keating | [Email][mkeating] |
|
||||||
|
| Michael Hallam | [Email][mhallam] |
|
||||||
|
|
||||||
|
[mkeating]: mailto:m.keating@shadowcat.co.uk
|
||||||
|
[mhallam]: mailto:info@lancasteresta.org
|
||||||
|
|
|
||||||
17
package.json
17
package.json
|
|
@ -7,17 +7,18 @@
|
||||||
"copyright": "Copyright 2017 Pear Trading Ltd",
|
"copyright": "Copyright 2017 Pear Trading Ltd",
|
||||||
"scripts": {
|
"scripts": {
|
||||||
"ng": "ng",
|
"ng": "ng",
|
||||||
"start": "ng serve",
|
"start": "ng serve --optimization=false",
|
||||||
"start:dev": "ng serve --optimization=false --configuration=dev",
|
"build": "ng build",
|
||||||
"start:prod": "ng serve --optimization=false --configuration=production",
|
"start:dev": "npm run start -- --configuration=dev",
|
||||||
"start:local": "ng serve --optimization=false --configuration=local",
|
"start:prod": "npm run start -- --configuration=production",
|
||||||
"build:dev": "ng build --configuration=dev",
|
"start:local": "npm run start -- --configuration=local",
|
||||||
"build:prod": "ng build --configuration=production",
|
"build:dev": "npm run build -- --configuration=dev",
|
||||||
|
"build:prod": "npm run build -- --configuration=production",
|
||||||
"test": "ng test",
|
"test": "ng test",
|
||||||
"test:ci": "ng test --watch=false --browsers=ChromeHeadless",
|
"test:ci": "npm run test -- --watch=false --browsers=ChromeHeadless",
|
||||||
"lint": "ng lint",
|
"lint": "ng lint",
|
||||||
"e2e": "ng e2e",
|
"e2e": "ng e2e",
|
||||||
"e2e:ci": "ng e2e --configuration=ci",
|
"e2e:ci": "npm run e2e -- --configuration=ci",
|
||||||
"ci": "npm run test:ci && npm run e2e:ci"
|
"ci": "npm run test:ci && npm run e2e:ci"
|
||||||
},
|
},
|
||||||
"private": true,
|
"private": true,
|
||||||
|
|
|
||||||
Reference in a new issue