Cleverstarter

A Full-stack TypeScript GraphQL Project Template

1. Reduce time to MVP
2. Reduce developer pain-points
3. Provide a robust foundation for Enterprise scale

Quickstart

Ensure you have npm and git.

Given the above dependencies, run the following in a terminal as a regular user:

npm init @clevertech.biz/cleverstarter
npm start

Familiarize yourself with the contents of ./<project>

What & Why?

1. React

• Why: Standard, robust, well-known client library
• Docs: https://reactjs.org
• Known Alternatives: Angular

2. Express

• Why: Standard, robust, well-known server library
• Docs: https://expressjs.com/
• Known Alternatives: Koa

3. Apollo Client / Server:

• Why: decouple the frontend from the backend:
• Docs: https://www.apollographql.com/docs/
• Known Alternatives: Postgraphile and Relay Modern

4. TypeScript

• Why: Typed JavaScript scales better and results in less bugs
• Docs: https://www.typescriptlang.org/
• Known Alternatives: write new code in JavaScript and leave the existing TypeScript

5. TypeGraphQL

• Why: Using decorators and classes, quickly define schema in a modular, maintainable way
• Docs: https://typegraphql.com/
• Known Alternatives: Apollo lets you build your schema by hand

6. TypeORM

• Why: Manage Database and GraphQL schema with the same classes
• Docs: https://typeorm.io/
• Known Alternatives: Sequilize

9. Jest for unit tests

• Why: Delightful unit testing framework, easy to mock imports for isolated unit testing
• Docs: https://jestjs.io
• Alternatives: Mocha / Jasmine / Karma

10. Supertest for integration tests

• Why: Easily test HTTP endpoints for full integration
• Docs: https://github.com/visionmedia/supertest
• Known Alternatives: Perform integration tests on the endpoint methods with Jest

11. Cypress for e2e testing

• Why: Professional, well-loved E2E testing framework for web applications
• Docs: https://cypress.io
• Alternatives: TestCafe

12. Passport OIDC Relay Provider Strategy

• Why: offload most auth logic to a hosted UI (like AWS Cognito) which supports Enterprise IdP integration
• Docs: https://github.com/panva/node-openid-client
• Alternatives: SAML, Local Auth, and any other passport.js strategy

13. Documentation: A detailed, helpful readme in each folder

• Why: Knowledge is lost unless it is written down
• Docs: makeareadme.com
• Alternatives: GitHub Pages / Wiki

Note: Skim through as much of the above documentation as you can (skip but observe) to set yourself up for success

Usage

Because Cleverstarter is a template, running the initializer is all you need to "use" the starter.

From there, you must know your domain language and begin building out your API and client-side application.

To assist you in this process, we will describe the various components of the application with README files in their respective directories

See above for links to the documentation of the variuos tooling we use.

Tutorials

Tutorials could be added to this section w.r.t. how to do common tasks within the starter like:

• Logging in, logging out, and protecting new resources
• Adding new resolvers to the schema
• Adding new routes to the frontend
• Querying data with Apollo
• Handling cache updates in Apollo
• N+1 Data Loader

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

1. Clone down the code:

git clone [email protected]:clevertech/cleverstarter.git

2. Start the watchers:

cd cleverstarter
npm start

3. Then edit the files in the template folder:

• template/api
• template/web/apollo-react
• template/mobile

Tests

Running npm test in the root of each template will verify all tests continue to pass.
Run npm test in the top-level folder of this repository to verify all tests still pass before committing. Please make sure to update and add tests as appropriate. Aim for over 80% coverage.

License

MIT