jherax / ts-app-boilerplate

Boilerplate project for a TypeScript API (Express, tsoa) + UI (React/TSX)

ts-app: Full-stack TypeScript Development Framework

This project is a starting point for developing an API-first application using TypeScript, Node.js, and React.

This project aims to support a "domain driven" approach. A client library is automatically generated from the API, providing a statically typed interface with which to interact with the API from the React UI. The goal is to provide a type-safe and productive developer experience for rapid web application development.

** Check out the new SaaS branch! Includes login flow, password reset, routing, emails and email previews, component library development via Cosmos, and more **

Getting started

• yarn to install dependencies
• yarn build to build from source
• yarn cli start to start developer environment
• yarn cli to use developer CLI
  • Includes dev environment setup, docker management, database management, and more
  • Full CLI docs

Developer experience

Project structure

This project uses TypeScript Project References to organize modules. This gives us:

• Faster builds
• Formal project dependencies; subprojects can't import from other subprojects unless the dependency is configured

Packages

• cli - Developer CLI tool
• client - Front-end React App
• common - Modules used by either browser or node environments
• node - Modules used by node environments
• server - Express server w/ tsoa API
• openapi-client - Autogenerated TypeScript client; used to communicate with OpenAPI REST API from client
• cypress - Cypress tests

System Requirements

• Node.js 14+
• docker and docker-compose
• yarn

Technologies Used

• TypeScript
• Backend
  • Node.js
  • Express
  • tsoa
    • Generates Express Routes from TypeScript controllers
    • Generates OpenAPI ("Swagger") specification, enabling automatic documentation and client library generation
  • PostgreSQL as RDBMS
    • TypeORM for code-first database migrations
      • Optional: ORM-like queries
  • Redis for caching/messaging
• Frontend
  • react
  • openapi-typescript-codegen for API client generation
  • styled-components for styling/css
  • webpack for bundling static assets
• Developer environment
  • docker and docker-compose for non-Node.js project dependencies
  • Single start script that live reloads the API, UI, and related services
  • VSCode launch.json settings have been included to support debugging
• Testing
  • jest test runner/assertions/utilities
  • supertest for API endpoint tests
  • cypress for end-to-end testing
  • react-testing-library for component testing

Running Tests

Jest Tests

Includes server node.js tests and front-end react-testing-library tests.

yarn cli test jest

Cypress Tests

End to end tests that touch everything and hit a running version of the application

yarn cli test cypress

Contributing

• Features and bug fixes welcome