geisterfurz007 / fullstack-typescript-boilerplate

A monorepo, fullstack TypeScript boilerplate with all the things!

This project is archived because I don't have time to keep it up to date anymore. It was created originally as a starting point for several projects I had in mind but I barely even find the time to work on the first of them and backporting changes to this repository just hinders my progress.

Fullstack TypeScript Boilerplate

This project provides a monorepo setup for a Fullstack TypeScript project and comes with the following:

Backend

• Koa
• Apollo GraphQL Server
• TypeGraphQL
• Prisma ORM

UI Builder (subpackage to build/theme your UI in)

• Preact
• Chakra-UI
• Storybook
• Chromatic

Frontend

• Preact
• Chakra-UI
• Next.js
• urql
• graphql-code-generator

Tooling

• Prettier
• ESLint
• Docker
• GitHub Action

How do I use this?

0. Clone this repository

1. Create the env files mentioned in .env files. For a starter setup you can just copy the .example files to their name without the .example (for Chromatic, see the general steps below).

2. Local development:
   Run yarn install, then yarn server:generate and use one of the available scripts! Everything should just work together in the setup you download (Note: yarn web:generate requires the backend to be running because the code generator loads the schema directly from the server).

3. Docker setup: Run docker-compose up, wait for the images to build, then have a look at the ports, where the built production instances will be running (Note: The docker setup is not suitable for development as it doesn't use volumes, storybook won't be launched in containers either).

Required steps for an actual project

If you are building a serious project with this, there are a few additional changes required to get everything running smoothly:

General

You should follow these steps whenever you start a new project with this boilerplate.

• Replace @project/ with @<projectname>/ in all package.json files
• Replace fullstack-typescript-boilerplate-example with your actual project's name in docker-compose.yml and docker-compose.yml
• Create a new project on Chromatic and place your project token in packages/ui/.env as CHROMATIC_PROJECT_TOKEN=token

GitHub Actions

You should follow these steps when you have this repository on GitHub and want to use Actions as CI/CD tool.

• Replace fullstack-typescript-boilerplate-example with your actual project's name in .github/workflows/build.yml
• Create three Docker repositories on Docker Hub, named <name>-migration, <name>-server and <name>-web replacing <name> with your project's name
• Go to your repository > Settings > Secrets and create these secrets:
  • CHROMATIC_PROJECT_TOKEN - contains the Chromatic token for the project
  • DOCKERHUB_USERNAME - contains the username you created the repositories in
  • DOCKERHUB_TOKEN - contains a Docker Hub access token

Available scripts

The repository comes with a bunch of yarn scripts you can run to do several things. The most important ones are available from the root directory of the project and listed here:

yarn eslint:check - Runs linting in all packages.
yarn eslint:write - Runs linting in all packages and fixes auto-fixable problems.
yarn format:check - Runs prettier on the entire project and reports styling issues.
yarn format:write - Runs prettier on the entire project and fixes styling issues.
yarn server:dev - Runs the backend for development (using ts-node-dev).
yarn server:generate - Generates backend source and packages using prisma.
yarn storybook - Runs and opens the Storybook project.
yarn test - Runs the test script in all workspaces.
yarn web:dev - Runs the next frontend for development.
yarn web:generate* - Generates GraphQL types and hooks for the frontend.

* - This script requires the backend to be running on http://localhost:5000/graphql because the code generator loads the schema directly from the server.

.env files

Currently, the boilerplate utilizes several .env files (I am not too happy about it, feel free to open an issue for suggesting an approach to only use one):

• .env contains environment variables used in the Docker setup
• packages/server/.env contains environment variables local to the server package, currently only used for providing the DATABASE_URL variable to prisma
• packages/ui/.env contains the chromatic project token
• packages/web/.env.local contains variables usable in Next.js (docs)

For all used .env files listed above, there is a .env.example file in this repository that you can copy to ./.env and adapt to your needs.

Docker

The server and web packages have been dockerized, and a docker-compose setup using postgres as database is available.

Environment variables

The docker-compose setup expects a series of environment variables to be set:

DATABASE_HOST - The host on which to find the database on
DATABASE_DB_NAME - The name of the database to use
DATABASE_USER - The user to use for database login
DATABASE_PASSWORD - The password to use for database login
BACKEND_PORT* - The port to run the backend on (default: 5000)
BACKEND_HOST - The hostname used inside the docker-network to connect to the server (default: server)

* This value is used during build-time of the container already to expose the correct port. If you change it, you have to rebuild the container!

Ports

The boilerplate currently uses the following ports:

Port	Service
3000	Next.js
5000	Backend*
5432	Database
6006	Storybook

* The port can be changed using the BACKEND_PORT environment variable.

fullstack-typescript-boilerplate's Issues

Implement the @emotion/jest serializer for storyshots to include the style information

Why

Currently snapshots look like this:

  <button
    type="button"
    label="Button"
    class=".chakra-button .css-oqfhsh"
  >
    Button
  </button>

With chakra-button supposedly containing the default chakra styling and css-oqfhsh containing additional style information processed by emotion. Getting to know this additional style information is desirable since it allows for more subtle changes in colors to be detected that Chromatic doesn't seem to pick up.

How?

Following https://emotion.sh/docs/testing, this should be as easy as adding the @emotion/jest/serializer to the snapshotSerializer array, however in tests that didn't seem to suffice.

From my understanding the order of operations needs to be:

1. Preact renders story to object
2. Emotion serializer resolves the styles
3. Preact object is rendered to HTML
4. Emotion serializer replaces the styles

Step 2-4 should "just" function within the emotion serializer given that the correct snapshot serializer is used from the provided array, getting the story rendered to an object however has been proven to be a bigger issue in earlier attempts.

Update packages and add renovate

Automatically pick up resolvers to avoid having to manually export them

Currently you have to export all classes and then collect them in an array to pass to typegraphl's resolvers option.

Ideally these are picked up automatically so you don't have to specify all of them. This could be done with a custom decorator which internally calls the original Resolver from typegraphql.