Scalable React TS Boilerplate

Checkout our website for documentation and examples.

Background Info

This project was initially inspired by the Scalable React Boilerplate. It inherits the Feature-First organizational pattern.

The main feature of this project is that it uses TypeScript as its main language. The reasons to use static types for front-end engineering are plentiful, but if you need more convincing, check the resources section below.

Getting Started

1. Clone the Repo git clone https://github.com/RyanCCollins/scalable-react-ts-boilerplate

2. Install Dependencies From the root of the project directory, run yarn if you have yarn installed globally. --- or --- npm install.

3. Start the Development Server Run npm run start then browse http://localhost:1337 to see your running app.

What is Feature First?

In most projects and frameworks, files are organized in a File type first fashion. For example, your tests exist in a test folder, your styles in a styles folder. This boilerplate takes a different approach.

We encourage encapsulation of features by asking that you organize each feature into the same folder. With React, this means that your containers and components exist in their own folders, along with literally every other file that pertains to that one feature. In other words, your actions, reducers, tests, styles, types and everything else are all internal to the feature they represent. By decoupling your features from the rest of your app, you set yourself up to reuse your UI components in future projects. You can thank us later!

Give it a try! We promise you will enjoy it.

Styled Components

This project embraces styled-components as it's a fantastic way to style your React components.

Check the components directory for examples.

Full Stack

This boilerplate contains setup to quickly get started with a full stack application. Within the src/ directory, you will find a server and a client folder.

File Tree Structure

Client File Structure

src/client
├── apolloClient.ts
├── components
│   ├── Box
│   │   ├── __tests__
│   │   │   ├── __mocks__
│   │   │   │   └── boxMocks.mock.ts
│   │   │   ├── __snapshots__
│   │   │   │   └── index.test.tsx.snap
│   │   │   └── index.test.tsx
│   │   ├── index.tsx
│   │   ├── maps.ts
│   │   ├── styleUtils.ts
│   │   ├── styles.ts
│   │   └── types.ts
│   ├── Section
│   │   ├── __tests__
│   │   │   ├── __mocks__
│   │   │   │   └── sectionMocks.mock.ts
│   │   │   ├── __snapshots__
│   │   │   │   └── index.test.tsx.snap
│   │   │   └── index.test.tsx
│   │   ├── index.tsx
│   │   └── styles.ts
│   └── index.ts
├── containers
│   ├── Blog
│   │   ├── index.tsx
│   │   ├── posts.graphql.ts
│   │   └── styles.ts
│   ├── BlogPost
│   │   ├── comments.graphql.ts
│   │   ├── index.tsx
│   │   ├── post.graphql.ts
│   │   └── styles.ts
│   └── index.ts
├── index.tsx
├── reducers.ts
├── routes.tsx
├── store.tsx
└── styles
    └── index.css

Server file structure

src/server
├── db
│   ├── index.ts
│   ├── models
│   │   ├── comment.ts
│   │   └── post.ts
│   └── utils
│       └── uuid.ts
├── graph
│   ├── index.ts
│   ├── mutations
│   │   ├── comment
│   │   │   ├── createComment.ts
│   │   │   └── index.ts
│   │   └── index.ts
│   ├── queries
│   │   ├── comment
│   │   │   ├── comment.ts
│   │   │   ├── comments.ts
│   │   │   └── index.ts
│   │   ├── index.ts
│   │   └── post
│   │       ├── index.ts
│   │       ├── post.ts
│   │       └── posts.ts
│   ├── schema.json
│   └── types
│       ├── comment
│       │   ├── comment.ts
│       │   └── commentInput.ts
│       ├── index.ts
│       └── post
│           ├── post.ts
│           └── postInput.ts
├── graphqlEntry.ts
└── index.tsx

Apollo GraphQL

Recently, we've added support for Apollo and GraphQL both server and client side. The starter code in this repo demonstrates how to setup your GraphQL server. The /blog route will show you a very simple example of loading data via Apollo Graphql.

UI Components

Build your next UIKit with this library!

Included in this project are a few primitive components that you can use to bootstrap your next project, or as a reference for building a UIKit.

• Box
  • Flex Box component! Whoot!
• Section
  • A section component. Extends the Box component giving flex-box properties.
• Anchor
• Article
• Button
• Footer
• Heading
• Headline
• Hero
• Image
• Markdown
• NavBar
• Paragraph
• SvgIcon
• And more!

Generators

We've included some generators so that you can easily scaffold out components & containers from the command line.

To use the generators, run npm run generator and select the options you want to use. The generators will create your component or container and their accompanying imports / exports.

Server Rendering

This project embraces server-side rendering. Included in the setup is an Express server that will server render. Note that the server-rendering will not work with the TypeScript source code, so you must compile the project into the Build directory first. Also, you must copy any other assets (images, markdown, etc.) into the build folder.

Code Generation

A big feature of the Scalable React Boilerplate project is the code generation tools. They will be incorporated into this project at a later time. If you are interested in contributing, please let us know!

Testing

Included is a test framework for all of your React testing needs. We are using Jest to run the test suite and generate snapshots, plus Enzyme for component introspection.

Tests should be collocated within the component / container they represent. Test files should be named index.test.tsx and mocks must be named myMock.mock.ts.

Please reference the Box and Section components for example tests. More will be added at a later time.

Note that the test are not compiled by TypeScript, that way there is no code duplication and you can use static types in your tests.

P.S. If you are looking to contribute, this would be a great first contribution!

Deployment

The documentation website built for this boilerplate is deployed to Heroku. Included is a Procfile that will run the server. The deployment is automated completely. After the install script, the deploy script will run on the server in order to compile the bundle and prepare the build folder for server-rendering.

Scripts

• npm run setup:yarn
  • Install the package dependencies via yarn
• npm install
  • Install dependencies (the ol' fashioned way)
• npm run start
  • Start the dev server
• npm run build
  • Build the project
• npm run deploy
  • Create a production bundle for deployment
• npm run run serve
  • Serve the production bundle on port 1337
• npm run test
  • Run the test suite
• npm run test:watch
  • Run the test suite in watch mode
• npm run test:update
  • Update the failing snapshot tests

Resources

• JavaScript Code Quality with Free Tools
• Working with React & TypeScript
• Setting up a New React / TypeScript Project
• Feature First Architecture

Contributing

See here for our contribution guide. We are on slack, please go here for an invite! We'd love to hear from you!

License

See here for the license.

Roadmap

v1.0.2

• Add CI
• Integrate storybook
• Add a no any rule and update source to use it
• Add more reusable modules, ala box / section
• Standardize the tslint configuration
• Introduce an async redux workflow
  • Redux logic
  • Redux Side-effect
  • Sagas
  • Etc.
• Remove requires and use es6 imports for all libs

Troubleshooting

Make sure to use the right version of node. You can reference the version in the .nvmrc file. For help installing and using NVM, please refer to this gist.