README.md

⚠️ Notice: This repository is under active development. Things will be missing, broken, or incomplete as development continues.

What is this?

This repo is my heavily opinionated starter template. Every so often I like to revisit what my tech stack consists of and currently this is it. The focus of this project is to maintain a base set of functionality for creating a bleeding edge app in Next.js with end to end type safety and testing built in.

Everyone is welcome to use this starter template, report bugs, and suggest changes. Keep in mind that this is my personal tech stack, so I might not implement all suggestions.

Tech Stack

• ▲ Turborepo - Monorepo support
• ▲ Next.js 14 - React framework
• 🦺 TypeScript - Type safety code base
• 📦 tRPC - Type safe client and server side API requests
• 🎯 trpc-openapi - Dynamic REST endpoints and automatic Swagger documentation
• 💎 zod - Data validation and parsing
• ✅ validator - String validation types
• 🏔️ Prisma - Database ORM
  • 🗄️ Postgres - Local database
  • ⚡️ Supabase - Remote database
  • 🪐 PlanetScale - Optional remote database
• 🍃 Tailwind CSS - Utility styles
• 📝 Tailwind Forms Plugin - Form utility styles
• 🪄 Framer Motion - CSS animations
• 🃏 Jest - Unit tests
• 🚨 Sentry - Server and client side error logging
• 📘 Storybook - Component library
  • 🐙 Testing Library - Testing library for UI components
• 🎭 Playwright - Running end to end tests on the web app
• 🎛️ Github Actions - Continuous integration testing
• 🐳 Docker - Optional local development
  • 🌊 DigitalOcean - Remote deployment with Docker
• ▲ Turborepo - Monorepo support
• ▲ Vercel - Remote deployment
• 🌎 Netlify - Remote deployment

Getting Started

1. Fork, "Use this template" via GitHub or clone locally and remove remote to create a repo.
2. Install dependencies with npm ci.
3. Create an .env.local file in ./apps/web/ with the contents of .env.example
4. Generate JWT keys by running ./apps/web/bin/generate_jwt_keys.sh <password>.
5. Setup Google OAuth for your app https://support.google.com/cloud/answer/6158849 and copy the id and secret into .env.local.
6. Add http://localhost:3000/oauth/google/callback to the list of Authorized redirect URIs for your Google OAuth web application.
7. Generate the database types with npm run db:generate (if you have VS Code open, run TypeScript: Reload project to see the updated types)
8. Setup the database with npm run db:push
9. Run with npm run dev

Database

Postgres

1. Install Postgres
2. Create create-app database
3. Setup the database with npm run db:push

supabase

1. Create database
2. Go to Project Settings > Database
3. Copy and paste the connection string into .env.local as the value for DATABASE_URL
4. Replace [YOUR-PASSWORD] with your password you made when creating the database.
5. Append ?pgbouncer=true to the connection string if Connection Pooling is enabled.
6. Push changed to database with npm run db:push

PlanetScale

1. Create database

2. Go to Settings > Password

3. Create new password

4. Supply a name for the password

5. Hit generate password

6. Change the Connection string dropdown to Prisma

7. Copy and paste the URL into .env.local

8. Open packages/database/prisma/schema.prisma and update the datasource value to the following:

   datasource db {
    provider     = "mysql"
    url          = env("DATABASE_URL")
    relationMode = "prisma"
   }
   

9. Push changed to database with npm run db:push

Logging

Sentry

It's recommended that when setting up Sentry that you limit the allowed domains in your project settings so only logs from your application can be logged.

Docker

The included docker setup can be used for developing on a machine without Node.js or Postgres installed. It can also be modified to be deployed to an online service, like DigitalOcean.

Build and run images

$ docker compose up --detach

Cleanup

$ docker compose down

Testing

Jest

Jest tests are setup to work both locally and via GitHub Actions.

Run the following to run all tests that match *.test.ts or *.test.tsx.

$ npm test

Or if you want to run a specific file:

$ npm test -- -- ./apps/web/src/modules/auth/controller.test.ts

Storybook

Storybook testing requires storybook to be built and the static storybook running on a server in the background. The following command does all of this for you to prevent having to have two terminal windows open.

$ npm run test:styleguide

If you would like to run the tests in two terminal windows you can run the following commands:

$ npm run storybook-static

$ npm run test-storybook

GitHub Actions

GitHub Actions workflows will lint all files, attempt a build and then run all unit tests. This workflow will run either when commits are pushed directly to the main branch or when a Pull Request is created (not a draft).

Questions

If you have any questions regarding the use of @neogeek/create-app, please use either GitHub Discussions or Discord server. The issue tracker is to be used for bug reports and feature requests only.

Contributing

Be sure to review the Contributing Guidelines before logging an issue or making a pull request.

Troubleshooting

prepared statement \"s0\" already exists

If you are having issues making database requests to your Supabase database, make sure you are using the correct connection string (pooled or unpooled). See this ticket for more information prisma/prisma#12121 and the Prisma documentation.

DATABASE_URL=postgresql://USER:PASSWORD@HOST:PORT/DATABASE?pgbouncer=true"

License

MIT