#+HTML: <h1>Astraea <sub><sub><sub>TypeScript + React Boilerplate</sub></sub></sub></h1>
[[https://travis-ci.org/jupl/astraea][file:https://img.shields.io/travis/jupl/astraea/master.svg?label=travis&style=flat-square]]
[[https://david-dm.org/jupl/astraea/master][file:https://img.shields.io/david/jupl/astraea/master.svg?style=flat-square]]
[[https://david-dm.org/jupl/astraea/master?type=dev][file:https://img.shields.io/david/dev/jupl/astraea/master.svg?style=flat-square]]

** Note
Recently [[https://redux.js.org/][Redux]] support has been removed from this boilerplate. It can still be incorporated, but by default this boilerplate is focused more on React. There are many other options like [[https://mobx.js.org/][MobX]], [[https://reactjs.org/docs/context.html][context]], and more.

** Table of Contents
- [[#about][About]]
- [[#prerequisites][Prerequisites]]
- [[#getting-started][Getting Started]]
- [[#project-structure][Project Structure]]
- [[#tasks][Tasks]]
- [[#project-resources][Project Resources]]

** About
This is a boilerplate project for developing a mid to large scale client-side application(s) using [[https://www.typescriptlang.org/][TypeScript]] and [[https://facebook.github.io/react/][React]]. For an example project, visit the [[https://github.com/jupl/astraea/tree/example][example branch]].

^{[[#astraea-typescript--react-boilerplate][Back to top]]}

** Prerequisites
- [[https://nodejs.org/en/][Node.js]] (8.x minimum required)
  - [[https://docs.npmjs.com/cli/npm][npm CLI]] is usually included with Node.js
- Editor with support for TypeScript, [[https://palantir.github.io/tslint/][TSLint]], and [[http://editorconfig.org/][EditorConfig]] (ex. [[https://code.visualstudio.com/][Visual Studio Code]])

^{[[#astraea-typescript--react-boilerplate][Back to top]]}

** Getting Started
1. Clone/download this repository.
2. Install dependencies using npm:
   - =npm install=
3. Start running tasks as described below in the [[#tasks][tasks section]].

^{[[#astraea-typescript--react-boilerplate][Back to top]]}

** Project structure
*** Overview
#+BEGIN_EXAMPLE
astraea/
├─ .coverage/                  # Code coverage reports
├─ .storybook/                 # Storybook configuration
├─ dist/                       # Result from build tasks
│  ├─ assets/                  # Result assets
│  └─ story/                   # Result storybook build
├─ jest/                       # Code that runs before tests are run
├─ src/                        # Source code
│  ├─ app/                     # Application domain
│  │  └─ components/root/      # Top level application view
│  ├─ assets/                  # Static files and entry points to include in builds
│  │  └─ app.tsx               # An application entry point
│  └─ common/                  # Shared code used throughout project
│     ├─ components/container/ # Application wrapper component
│     └─ declarations/         # TypeScript declarations
├─ package.json                # Configuration, tasks, and dependencies
├─ package-lock.json           # Dependency pinning
├─ tsconfig.json               # TypeScript configuration
├─ tslint.json                 # TypeScript linting rules
└─ webpack.config.ts           # Webpack build configuration
#+END_EXAMPLE
*** Entry Points
When TypeScript code is built, any files directly inside the =src/assets/= directory are used to create the output files. The boilerplate currently generates =app.js=, as there is a single entry point inside =src/assets/=. (=src/assets/index.js=) If there are more than one entry points more files generated as well as an additional file =common.js=, which contains shared code across all entry points. =common.js= must be loaded before you load an entry point. You can see what gets generated by running the =build:dev= / =build:prod= task. (see the [[#tasks][tasks section]])
*** Domains
#+BEGIN_EXAMPLE
domain/
├─ components/
│  ├─ component1/ # See Component sections below
│  ├─ component2/
│  └─ componentX/
└─ ...            # Other domain items (Redux, MobX, context, etc.)
#+END_EXAMPLE
Rather than group items by things like components/reducers/actions/etc., items are grouped by domain which can be a saner option as the project grows. Examples of domains can be things like resources (ex. =blog/=, =users/=) or other things. (ex. =ui/=) Domains may include things like components, actions, reducer, etc. but they don't have to include all of them. In fact, you can think of =app/= and =common/= as domains. Other files may be present as well.
*** Components
#+BEGIN_EXAMPLE
component/
├─ index.ts
└─ template.tsx
#+END_EXAMPLE
React components are grouped in a directory.
- =template.tsx= defines the React component without any knowledge of outside logic (ex: Redux) specifics or other things like React DnD. (sometimes referred as /dumb/ component)
- =index.ts= is the entry point of the component when used by others.
  - If template does not require data/action bindings then it can just pass through the template. (see =src/app/components/root/index.ts=)
  - If template requires data/action bindings then it is done here.  (sometimes refereed as /smart/ component)
*** Other Files
**** =*.test.ts=, =*.test.tsx=
Tests for components/domains/logic/etc. If code needs to be run before tests are executed see =setup-tests.ts= Some guides on tests include:
- [[https://facebook.github.io/jest/docs/api.html][Jest]]
- [[http://airbnb.io/enzyme/index.html#basic-usage][Enzyme]]
- [[https://facebook.github.io/jest/docs/tutorial-react.html][React]]
**** =*.stories.tsx=, =*.story.tsx=
Defines a story to display in React Storybook. Typically this file is in a component. (ex. =index.stories.tsx=) [[https://getstorybook.io/docs/react-storybook/basics/writing-stories][This guide]] provides information on how to write stories.
**** =__snapshots__=
Generated files/directories when using Jest's [[https://facebook.github.io/jest/docs/tutorial-react.html#snapshot-testing][snapshot feature]]. These files should be left to Jest and not touched manually.

^{[[#astraea-typescript--react-boilerplate][Back to top]]}

** Tasks
Tasks can be executed in the following manner:
#+BEGIN_EXAMPLE
npm run [command]  # npm
#+END_EXAMPLE
Examples:
#+BEGIN_EXAMPLE
npm run server
#+END_EXAMPLE
*** =start=
Alias for =build:prod=.
*** =server=
Alias for =server:hot=.
*** =server:hot=
Start a local development server with hot reloading. To override the port change the environment variable =PORT=. The following is provided:
- [[https://webpack.js.org/concepts/hot-module-replacement][Hot reloading]] (including [[https://github.com/gaearon/react-hot-loader][React Hot Loader]])
*** =server:story=
Start a local server for React Storybook on port 9001. For more information visit the [[https://getstorybook.io/docs][documentation for React Storybook]].
*** =build:dev= / =build:prod=
Build application and include assets into a packaged build in the =dist/assets/= directory. The build for =build:dev= is not minifed and includes source maps, making it ideal for development. The build for =build:prod= is minified (with dead code elimination) and does not include source maps, making it ideal for production.
*** =build:story=
Generate a static build of React Storybook in the =dist/story/= disrectory.
*** =test= / =test:watch= / =coverage= / =coverage:watch=
Execute tests once or continuously on file changes. In addition, code coverage can be determined. For more information visit the [[https://facebook.github.io/jest/docs/configuration.html][documentation for Jest]].
*** =lint= / =lint:fix=
Check codebase against linting rules. Optionally, some errors can be fixed automatically.

^{[[#astraea-typescript--react-boilerplate][Back to top]]}

** Project Resources
- Language
  - [[https://www.typescriptlang.org/][TypeScript]]
  - [[https://palantir.github.io/tslint/][TSLint]]
    - [[https://github.com/palantir/tslint-react][TSLint React]]
- Libraries
  - [[https://facebook.github.io/react/][React]]
  - [[https://styled-components.com/][Styled Components]]
  - [[https://necolas.github.io/normalize.css/][normalize.css]]
- Testing
  - [[https://facebook.github.io/jest/][Jest]]
  - [[https://github.com/airbnb/enzyme/][Enzyme]]
- Development Tools
  - [[https://storybook.js.org/][Storybook]]
- Build Tools
  - [[https://webpack.js.org/][Webpack]]

^{[[#astraea-typescript--react-boilerplate][Back to top]]}