5. Developer Guide

1. Setting up the project

1.1 Pre-requisite

This development environment is tested and should be working on:

NodeJs v6.9.4
Windows 10 & Mac OS

We will be using yarn for our dependency management in this project.
Follow the guide to install yarn for your operating system

1.2 Getting started

In your terminal type:

git clone https://github.com/nus-mtp/sashimi-note.git
cd sashimi-note
yarn
yarn start

Jump to links 2. Working with the project 3. Project structure 4. Continuous deployment 5. Continuous integration

2. Working with the project

2.1 Recommended text editor

Visual Studio Code

Visual Studio Code (VSCode) is recommended during the development of this project.
It is a powerful text editor that enables many of the functionalities

However, feel free to use any text editor or IDE that you are most comfortable with.

2.1.1 eslint for VSCode

Open your Visual Studio Code
Open the Extension tab Ctrl/Cmd + Shift + X
Search for 'Eslint' by Dirk Baeumer
Install the extension and reload the Visual Studio Code's window
Eslint should be integrated with your Visual Studio Code now.

* External guides are available for setting up eslint for Sublime and Atom Text Editor.

2.1.2 JavaScript tool for VSCode

JavaScript snippet and IntelliSense is built-in to VSCode.
No additional set up is required.

2.1.3 Launching project folder with VSCode

You can quickly open the project folder using VSCode by typing code . in your terminal.

2.1.4 Vetur

To better support the development of VueJs application with VSCode.
Our team uses Vetur by Pine Wu.

3. Project Structure

3.1 Project root

3.1.1 Development environments

This project is divided into 2 development environments

Webapp sashimi-webapp
Platform sashimi-platform

The 2 development environments have their own package.json file and node_modules dependencies folder. The project has been configured to install the necessary dependency for each development environment when yarn is executed in the project root folder.

yarn command in the project root folder will:

install node_modules in the project root foldre
install node_modules in sashimi-webapp
build sashimi-webapp
duplicate sashimi-webapp/dist into sashimi-platform/public
install node_modules in sashimi-platform

Note:

Travis will skip step 3 and 4 to speed up the process.
The automated node_modules installation is done with shelljs inside the scripts folder.

3.1.2 Configuration files

.eslintrc.js - Two eslintrc.js files are placed:
- at the sashimi-platform folder for the platform (express server) and
- at the sashimi-webapp folder for the Webapp (browser environment)
.eslintignore
.gitignore - gitignore.io is used to generate the main part of the file
Vagrantfile - configured to use amoshydra/node6
yarn.lock

3.2 Sashimi Webapp

sashimi-webapp contains the client application (in browser) that user see and interact with.

sashimi-webapp is a Single Page Application developed with VueJs.

As of milestone v0.1.x, sashimi-webapp will be a standalone web application. This means that all logic used by the application will be loaded inside the client side. Therefore, once it is loaded, it will require minimal to no server connection to function.

3.2.1 Development commands

sashimi-webapp uses a separate package.json configuration file. It comes with its own npm script and dependencies. Make sure to cd into sashimi-webapp first before running these commands.

# install dependencies
yarn

# serve with hot reload at localhost:8080
yarn run dev

# build for production with minification
yarn run build

# build for production and view the bundle analyzer report
yarn run build --report

# run unit tests
yarn run unit

# run e2e tests
yarn run e2e

# run all tests
yarn test

For detailed explanation on how things work, checkout the guide and docs for vue-loader.

3.2.2 Folder structure

The folder structure is scalffold from vue-webpack-boilerplate.

sashimi-webapp/
├── build/                  	# webpack config files
|   └── ...
├── config/
|   ├── index.js		# main project config
|   └── ...
├── src/                        # app folder consisting of all essential js files
|   ├── assets/                 # node_module assets (processed by webpack)
|   ├── components/		# Vuejs UI components
|   ├── database/		# database modules
|   ├── helpers/		# helper modules
|   ├── logic/
|   |   ├── documentPackager/
|   |   ├── fileManager/
|   |   ├── inputHandler/
|   |   └── renderer/
|   ├── router/ 
|   ├── App.vue			# main app component
|   ├── main.js                 # main entry for the application
|   └── ...
├── static/			# all static assets placed here
├── test/                       # test folder, structurally mimics app folder
|   ├── e2e/			# e2e tests
|   └── unit/			# unit tests
├── index.html			# index.html template
├── package.json		# build scripts and dependencies
├── yarn.lock			# yarn lockfile
└── ...

Folder	Description
`build/`	This directory holds the actual configurations for both the development server and the production webpack build. Normally you don't need to touch these files unless you want to customize Webpack loaders, in which case you should probably look at `build/webpack.base.conf.js`.
`config/index.js`	This is the main configuration file that exposes some of the most common configuration options for the build setup. See API Proxying During Development and Integrating with Backend Framework for more details.
`src/`	This is where the bulk of the application code will be located in.
`static/`	This directory is an escape hatch for static assets that you do not want to process with Webpack. They will be directly copied into the same directory where webpack-built assets are generated. See Handling Static Assets for more details.
`test/unit`	Contains unit test related files. See Unit Testing for more details.
`test/e2e`	Contains e2e test related files. See End-to-end Testing for more details.
`index.html`	This is the template index.html for our single page application. During development and builds, Webpack will generate assets, and the URLs for those generated assets will be automatically injected into this template to render the final HTML.
`package.json`	The NPM package meta file that contains all the build dependencies and build commands.

3.3 Sashimi Platform

sashimi-platform contains the express server, which will be used to serve the sashimi-webapp.

For milestone 0.1.x, the express server will only be used to serve the Webapp.
Therefore, most of the work for milestone 0.1.x is to be done inside the sashimi-webapp folder.

4. Continuous Deployment

Continuous deployment with Heroku.

Heroku will monitor two branches in this project

master branch
- deployed to https://sashimi-note.heroku.com
- NODE_ENV set to production
development/v0.x.x
- deployed to https://sashimi-note-dev.heroku.com
- NODE_ENV set to development (error stack will be printed)

Heroku make use to yarn and yarn start at the project root folder for the deployment.
yarn start will start the Express server inside sashimi-platform,
which will serve a built Webapp via its public folder.