jupl/astraea

TypeScript + React Boilerplate

Astraea _{TypeScript + React Boilerplate}

Note

Recently 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 MobX, context, and more.

Table of Contents

• About
• Prerequisites
• Getting Started
• Project Structure
• Tasks
• Project Resources

About

This is a boilerplate project for developing a mid to large scale client-side application(s) using TypeScript and React. For an example project, visit the example branch.

^{Back to top}

Prerequisites

• Node.js (8.x minimum required)
  • npm CLI is usually included with Node.js
• Editor with support for TypeScript, TSLint, and EditorConfig (ex. Visual Studio Code)

^{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 section.

^{Back to top}

Project structure

Overview

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

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 section)

Domains

domain/
├─ components/
│  ├─ component1/ # See Component sections below
│  ├─ component2/
│  └─ componentX/
└─ ...            # Other domain items (Redux, MobX, context, etc.)

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

component/
├─ index.ts
└─ template.tsx

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:

• Jest
• Enzyme
• React

*.stories.tsx, *.story.tsx

Defines a story to display in React Storybook. Typically this file is in a component. (ex. index.stories.tsx) This guide provides information on how to write stories.

__snapshots__

Generated files/directories when using Jest’s snapshot feature. These files should be left to Jest and not touched manually.

^{Back to top}

Tasks

Tasks can be executed in the following manner:

npm run [command]  # npm

Examples:

npm run server

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:

• Hot reloading (including React Hot Loader)

server:story

Start a local server for React Storybook on port 9001. For more information visit the 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 documentation for Jest.

lint / lint:fix

Check codebase against linting rules. Optionally, some errors can be fixed automatically.

^{Back to top}

Project Resources

• Language
  • TypeScript
  • TSLint
    • TSLint React
• Libraries
  • React
  • Styled Components
  • normalize.css
• Testing
  • Jest
  • Enzyme
• Development Tools
  • Storybook
• Build Tools
  • Webpack

^{Back to top}