-
Notifications
You must be signed in to change notification settings - Fork 1
Front End Resources
This document aims to provide some helpful notes on setup and development environments for the avalon-bundle front-end.
yarn is used for front-end package management, over npm. yarn is also the default package manager for webpacker.
If you'd like to install a new package, from the application root directory run:
yarn add my-awesome-new-package, or if it's a development specific dependency, run:
yarn add --dev my-awesome-new-package
https://webpack.js.org/
Webpack is made available to the Rails 5.1 environment through the webpacker package.
https://github.com/rails/webpacker
Custom configuration files/folders for our webpacker integration are located in:
config/webpack.
If there are webpack errors/warnings when running the application, they'll appear in your rails server terminal window. Webpack compilation can also be executed directly via a rails webpacker command:
bundle exec rails webpacker:compile
Running bundle exec rails webpacker will list all over webpacker's available commands (to install React, Vue, check proper configuration, etc).
All JS should be written in ES6 format. Here's a list of webpacker's default ES6 support.
In the avalon-bundle application, ES6 JavaScript is automatically transpiled via Babel as part of webpacker's default configuration.
Application JavaScript files should be placed in the following directory, as configured through webpack as the entrance point location:
app/javascript
Individual pack files are located in app/javascript/packs. These are the files which are referenced in a Rails view or partial. So these pack files should be small, simple JavaScript files which import .js files from the parent directory. The parent directory should store files which contain actual application logic.
Example directory structure:
app/javascript/packs/application.js
app/javascript/packs/some-custom-feature-entrance-file.js
app/javascript/some-custom-feature/index.js
app/javascript/some-custom-feature/split.js
app/javascript/some-custom-feature/into.js
app/javascript/some-custom-feature/small.js
app/javascript/some-custom-feature/modules.js
Then drop the pack file in a Rails view .html.erb to execute the JavaScript:
<%= javascript_pack_tag 'some-custom-feature-entrance-file' %>
To organize ReactJS files separately, place any react components in:
app/javascript/react
If React components need external api data, or need to maintain their own state, they should be wrapped by a container component (place in react/containers), and render a functional 'dumb' component located in react/components.
For browser debugging, setting breakpoints, etc, webpacker's default configuration displays original source .es6 files in the browser's dev tools panel.
In Chrome: DevTools > Sources > Network, the location is:
top / webpack:// / app/javascript / src
We're using Jest (https://facebook.github.io/jest/) for unit testing our app/javascript webpack files.
- Built-in code coverage reports.
- Easier configuration than karma/webpack when using Babel/ES6.
- Powerful mocking library.
All test files should be placed in the same directory as the files they're testing. Test files should have the file extension *.test.js. A sample directory structure including unit tests, looks like this:
app/javascript/some-custom-feature/example-js-file.js
app/javascript/some-custom-feature/example-js-file.test.js
app/javascript/some-custom-feature/ImaClass.js
app/javascript/some-custom-feature/ImaClass.test.js
Jest unit tests can/should be ran locally, within the root /avalon-bundle directory. There is a yarn test script included in package.json which can be ran as follows:
yarn test
https://facebook.github.io/jest/
avalon-bundle's configuration uses both ESLint and Prettier to ensure code quality and consistent formatting before committing code. Prettier formats JavaScript code in app/javascript automatically as webpack compiles, then passes the 'prettified' code to ESLint for further linting.
Our webpacker configuration automatically formats and checks front-end code every time webpacker compiles, however if you'd like to run Prettier or ESLint CLI in your terminal window separately, you can do so through the following yarn commands we've created. (Note: the command package names are purposely different from the community package names; ie. lint instead of eslint and pretty instead of prettier):
yarn run lint
yarn run pretty
yarn scripts can be added/edited in /package.json
From the Prettier docs:
By far the biggest reason for adopting Prettier is to stop all the on-going debates over styles. It is generally accepted that having a common style guide is valuable for a project and team but getting there is a very painful and unrewarding process. People get very emotional around particular ways of writing code and nobody likes spending time writing and receiving nits.
So why choose the "Prettier style guide" over any other random style guide? Because Prettier is the only "style guide" that is fully automatic. Even if Prettier does not format all code 100% the way you'd like, it's worth the "sacrifice" given the unique benefits of Prettier, don't you think?