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
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.
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)
Getting Started
- Clone/download this repository.
- Install dependencies using npm:
npm install
- Start running tasks as described below in the tasks section.
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)
- If template does not require data/action bindings then it can just pass through the template. (see
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:
*.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.
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.
Project Resources
- Language
- Libraries
- Testing
- Development Tools
- Build Tools