search

codeandcognition / koconut

a very cool assess pool
2 stars 0 forks source link

readme

very cool status flow status emoji status productivity status reactmarkdown inline html

Codeitz (formerly Koconut)

Index

Other Docs

Project Information

Technology Stack

Currently, koconut is built using the following stack:

Frontend

Backend

Custom APIs

Tools

Development of koconut is assisted by the usage of:

Style Guide

JavaScript

Style

JavaScript is written in ES6 with Flow style static typing.

Format

Code should be formatted similarly to Google JavaScript Style.

For formatting this means:

Other formatting should also be consistent. It is worth noting that many IDEs (including WebStorm) can automatically reformat code.

Documentation

JavaScript classes and functions should be commented with JSDoc style comments to help with documentation.

Not every tag needs to be used. The most important tags to use are:

Comments should also have a brief description.

Render methods do not need Flow annotations or @returns tags because typing is easily inferred and obvious to the reader.

CSS

Sass is written using SCSS syntax.

Setup and Usage

Installation

After cloning the repo, you can quickly install all the project dependencies using the following command within the project directory:

yarn install

If you don't already have Yarn, you can install it using npm (which diplomatically lets you install its direct competitor :+1:):

npm install yarn

Yarn is an alternative package manager that we use because it's both faster and cuter (npm has no cats :cat:). All npm commands can be replaced with yarn commands!

It may be necessary to change your version of Node and update package.json. Node v8.11.2 worked at time or writing. Run n 8.11.2 to set the version of Node (download may be required) and then update package.json with npm update.

Quick Start

To have a live preview of the application, simply run the following command:

yarn start

This command does the following:

  • Starts a development server that will host a live preview of the application
  • Starts a Sass watcher which automatically generates CSS from SCSS files as they are updated

To also run the backend api, use a similar command:

yarn start-all

  • Starts a nodemon server that will host the backend server and update automatically when files are changed

n.b.: SASS has been behaving unusually (as of May 2019, node v10.15.3, npm v6.9.0, mac OS 10.14.3), so running npx react-scripts start can circumvent any SASS errors that prevent start-up.

Development Scripts

Command Description
yarn run start-docs Starts the documentation.js server on :4001
yarn run flow Starts a Flow server and type-checks your code
yarn run make-flow-nicer (Usually) fixes Flow being mean to you

Build Scripts

Command Description
yarn run build Builds the application and dumps it in /build and /build_node. The project will not build if it does not correctly type-check
yarn run build-ignore Builds the application, ignoring type-checking
yarn run build-docs Builds documentation.js and dumps it in /dev/docs

Test Scripts

Jest tests can be quickly run using yarn test.

Resources

WebStorm

WebStorm is a JavaScript (and more!) IDE that can assist with development. WebStorm (and all JetBrains software) is free to use for students through a yearly license which can be obtained here.

Using the Google Style Guide in WebStorm

You can automatically import the Google Style Guide into your settings by choosing it from the existing style guides:

Preferences -> Editor -> Code Style -> JavaScript -> Set from… -> Predefined Style -> Google JavaScript Style Guide

To automatically reformat code, you can simply Code -> Reformat Code.

Using Flow in WebStorm

You can use the follow instructions to add Flow support to WebStorm (you will probably already have Flow installed and will not need to add or change the project's .flowconfig): Using Flow in WebStorm

Note: The default Flow directory that WebStorm will fill in will not work. It should look something like this:

[parent directories]/koconut/node_modules/.bin/flow.

Instead, use the following Flow executable:

[parent directories]/koconut/node_modules/flow-bin/vendor/flow.

Using GitHub Version Control with WebStorm

You can register your GitHub account in WebStorm for easy version control: Registering GitHub Account in WebStorm

It is recommended that you use token authentication: Personal API Tokens

VS Code

You can use Visual Studio Code instead of Webstorm, but you will find that it is harder to use Flow with. Visual Studio has an add-on for Flow that is a lot slower and feels a bit buggier, whereas Webstorm's feels very smooth.

If you're just getting started, I highly suggest using Webstorm. Once you get more familiar with the code base, then you can choose to switch to Visual Studio Code.

Tutorials and API References

JavaScript

React

React Libraries

Sass

Flow

Jest

Node.js

Express

See also: Koconut Wiki