odin-tutorial

An interactive tutorial for learning to write Odin rules React and Node.js with Express (to proxy requests to the Odin REST API).

The setup (including this README) is based on the project structure from Sandeep Raveesh's template.

Launching the Odin tutorial

Dependencies

1. docker
2. docker-compose

It's recommended that you have at least 3GB of RAM available (the REST API also runs an NLP pipeline before things are handed off to Odin).

docker-compose up

To view the interactive tutorial, open your browser to [localhost:8880]. To interact with the Odin ReST API, open your browser to [localhost:8881/api].

Development

Dependencies

1. Node.js
2. yarn

Installing the dependencies

yarn install

Development mode

In development mode, 2 servers will run. The frontend code will be served by the webpack dev server which helps with hot and live reloading. The server side Express code will be served by a node server using nodemon which helps in automatically restarting the server whenever server side code changes.

# start the dual servers with hot reloading of any modifications to the source
yarn run dev

Production mode

In production mode, a single server will run. All the client side code will be bundled into static files using webpack and it will be served by the Node.js/Express application.

You can run the app in production mode with the following commands:

# Minify everything
yarn run build
# Start the production server
yarn start

Documentation

Project structure

Aside from the config (see config.js), the source is found inside src directory. Inside src, the code is divided between the client and server directories. All the frontend code (react, css, js and any other assets) will be in client directory. Backend Node.js/Express code will be in the server directory.

Babel

Babel allows us to write code in the latest version of JavaScript, while maintaining compatibility with older browsers via transpilation.

.babelrc file is used describe the configurations required for Babel.

Babel requires plugins for handling various transpilation tasks. Presets are the set of plugins defined by Babel. The env preset is compatible with babel-preset-es2015, babel-preset-es2016, and babel-preset-es2017 and will transpile them all to ES5. The react preset allows translates JSX into Javascript.

ESLint

ESLint is a pluggable and configurable linter for JavaScript.

.eslintrc.json describes the configurations required for ESLint.

Currently, this project uses Airbnb's popular Javascript style guide as a basis (see below for some modifications). Since this project involves both client (browser) and server side (Node.js) code, the env is set to browser and node. Note that the following have been turned off:

• no-console
• comma-dangle
• react/jsx-filename-extension

Webpack

Webpack is a module bundler. Its main purpose is to bundle JavaScript files for usage in a browser.

webpack.config.js file is used to describe the configurations required for webpack.

1. entry: Denotes where the application starts executing and webpack starts bundling. Note: babel-polyfill is added to support async/await. Read more here.
2. output path and filename: The target directory and the filename for the bundled output.
3. module loaders: Module loaders are transformations that are applied on the source code of a module. We pass all the js file through babel-loader to transform JSX to Javascript. CSS files are passed through css-loaders and style-loaders to load and bundle CSS files. Fonts and images are loaded through url-loader.
4. Dev Server: Configurations for the webpack-dev-server which will be described in coming section.
5. plugins: clean-webpack-plugin is a webpack plugin to remove the build folder(s) before building. html-webpack-plugin simplifies creation of HTML files to serve your webpack bundles. It loads the template (public/index.html) and injects the output bundle.

Webpack dev server

Webpack dev server is used along with webpack. It provides a development server that with support for live reloading of the client side code. This should be used for development only.

The devServer section of webpack.config.js contains the configuration required to run the webpack-dev-server.

• Port: specifies the Webpack dev server to listen on this particular port (3000 in this case). - open: when set to true, it will automatically open the home page on startup. Proxying URLs can be useful when we have a separate API backend development server and we want to send API requests on the same domain. In our case, we have a Node.js/Express backend which handles API requests to the Odinson REST API (layers upon layers!).

Nodemon

Nodemon is a utility that monitors for any changes in the server source code automatically restarts the server updon detection. This is used in development only.

The nodemon.json file is describes the configurations for Nodemon. Here we instruct nodemon to watch the files in the directory src/server where all of our server side code resides. Nodemon will restart the node server whenever a file under src/server directory is modified.

Express

Express is a web application framework for Node.js. It is used to build our backend APIs.

src/server/index.js is the entry point to the server application. Aside from proxying API calls to the ODINSON REST API, the server is also configured to serve static assets from the dist directory.

Concurrently

Concurrently is used to run multiple commands concurrently. We're using it to run the webpack dev server and the backend node server concurrently in the development environment.