Currently, koconut is built using the following stack:
- koconut-api is a Python API we built which checks correctness and handles user modeling
Development of koconut is assisted by the usage of:
- Flow: a type-checking system for JavaScript
- Jest: a JavaScript testing framework
- documentation.js: a documentation generator
JavaScript is written in ES6 with Flow style static typing.
Code should be formatted similarly to Google JavaScript Style.
For formatting this means:
- Block indents are +2 spaces
- Continuation indents are +4 space
- Tab character are not used
- Column limit (right margin) of 80 characters
Other formatting should also be consistent. It is worth noting that many IDEs (including WebStorm) can automatically reformat code.
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:
@class@param@returns
Comments should also have a brief description.
Render methods do not need Flow annotations or
@returnstags because typing is easily inferred and obvious to the reader.
Sass is written using SCSS syntax.
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 👍):
npm install yarn
Yarn is an alternative package manager that we use because it's both faster and cuter (npm has no cats 🐱). All
npmcommands can be replaced withyarncommands!
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.
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.
| 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 |
| 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 |
Jest tests can be quickly run using yarn test.
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.
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.
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.
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
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.
- react-loadable: A higher order component for loading components with promises
See also: Koconut Wiki