hatch

This repository contains opinionated tools and libraries to jump start development of TypeScript applications for several platforms.

The hatch command-line application is used to "hatch" TypeScript projects that require minimal setup and boilerplate to start developing application code. This is achieved by generating projects which delegate heavily to the hatch-* libraries in this repository. These libraries are highly opinionated, meaning they typically have several peer dependencies, and are intended to be used according specific architectural patterns.

Disclaimer

This project is very much a work in progress. Until the first major release, there will likely be issues, sparse documentation, and APIs that are changing in backwards-incompatible ways. Please proceed at your own risk.

Who is this for?

In short, probably just ourselves! But maybe you, too.

These tools were written so that we, the authors, could use them to jump start our own projects according to design and architectural patterns that we've personally and professionally used successfully elsewhere.

That being said, it's possible that others developing TypeScript apps might find hatch useful. In particular, hatch might be useful for developers who are comfortable sacrificing flexibility in libraries and architecture in exchange for reducing time to development of application features. Developers who are looking for more flexibility and don't mind the extra work to get things set up exactly how they want it should consider using tools which are less opinionated, like create-react-app, Expo, electron, express, or Razzle. These are all great frameworks, and some of them used heavily by hatch for its foundation.

Acknowledgements

This project would not be possible without the support of the initial contributors' employer, Bigfoot Biomedical, which has allowed us to work on the project both on our time and on Bigfoot's when it is mutually beneficial. Bigfoot Biomedical has deep roots in the open source community, and benefits greatly from it. We are proud to have Bigfoot's support as we contribute hatch back to this community.

Installation

The hatch command-line application can be installed via the npm registry, e.g. with npm:

npm install -g @launchtray/hatch-cli

Usage

For up-to-date command-line usage, issue the following:

hatch --help

The hatch CLI can be used to "hatch" entire starter projects, as well as individual modules within an existing project that conform to architectural patterns that hatch uses.

Supported templates

Currently, the hatch CLI supports hatching projects using the following templates:

• webapp -- a single-page web application with:
  • Dependency injection, with the help of tsyringe
  • An express-based web server with server-side rendering (and much more), via a Razzle foundation
  • Portable UI architectural patterns, using React, Redux, Redux-Saga, React Native for Web, and React Router
  • Flexible logging using winston
  • Optional error reporting via Sentry

Refer to documentation for the project types above for more details on what individual modules can be hatched for each project type.

Common concepts

The following concepts and principles are employed throughout the hatch tools, libraries and template projects:

• (SOLID principles in general)
• Dependency injection
• Composition over inheritance
• Unidirectional dependencies / data flow
• Preference for pure UI components

Packages

The hatch repository is split up into the packages below. Generally, these packages are used by the templates generated by the hatch command-line application and are not typically used on their own outside of a project created by hatch.

• hatch-cli -- the source for the hatch command-line application
• hatch-web-client -- a library used for composing web client applications, including the client-side part of the webapp template
• hatch-web-server -- a library used for composing web server applications, including the server-side part of the webapp template
• hatch-server -- a library used for composing HTTP server applications, this is used by the microservice template, as well as by hatch-web-server
• hatch-web -- a library with common webapp modules used by hatch-web-server and hatch-web-client
• hatch-server-middleware -- a library containing server middleware components that perform common tasks, like logging all requests, or parsing a request body as JSON, etc.
• hatch-test -- a library to aid writing of automated tests
• hatch-util -- a library of utilities used by many of the other hatch libraries, including modules for performing dependency injection
• hatch-razzle-config -- a helper method for creating a Razzle config file that is compatible with the design of the webapp template
• hatch-web-injectables -- a library used for injecting useful web parameters

Developer setup

These instructions are for developers who would like to contribute to hatch libraries and tools. These steps are not necessary if you just want to use hatch.

1. Install the latest LTS version of node. e.g. for macOS:

   $ brew uninstall node
   $ brew install node@12
   $ brew link --force --overwrite node@12
   

2. Install Rush:

   $ npm install -g @microsoft/rush
   

3. Install package dependencies:

   $ rush install
   

4. Build hatch libraries:

   $ rush build
   

5. Run an example app:

   $ cd examples/example-web
   $ rushx start