Starter Kit

A technical kit to quickly build new products from Open Government Products, Singapore.

Features

• 🧙‍♂️ E2E typesafety with tRPC
• ⚡ Full-stack React with Next.js
• 🌈 Database with Prisma
• 🪳 CockroachDB
• 🌇 Image upload with R2
• ⚙️ VSCode extensions
• 🎨 ESLint + Prettier
• 💚 CI setup using GitHub Actions:
  • ✅ E2E testing with Playwright
  • ✅ Linting
• 🔐 Env var validation

Quickstart

Follow these instructions if you are familiar with building applications, and/or are in a hurry to prepare an environment to work on your product.

If you are new, see our Getting Started guide.

If you are exploring what else you can do with Starter Kit, a more comprehensive set of documentation, including guides and tutorials, can be found here.

One-click deploy

We recommend Vercel to deploy your application. A one-click deployment step is provided below, which will also set up your own copy of this codebase on GitHub for you to work on.

This needs a few prerequisites, detailed below.

Prerequisites

The deployment needs a few environment variables to be set for it to function. They are:

Name	What It Is	Example
DATABASE_URL	The connection string for your database. This should have been obtained from CockroachDB	postgresql://user:pass@happy-snail-4237.9xw.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full
POSTMAN_API_KEY	An API key to send email via Postman	asdfn_v1_6DBRljleevjsd9DHPThsKDVDSenssCwW9zfA8W2ddf/T
SESSION_SECRET	A sequence of random characters used to protect session identifiers, generated by running npx uuid from your terminal	66a21b98-fb17-4259-ac4f-e94d303ac894

Deployment

Working on your product

You may work on the codebase with:

• A GitHub Codespace provided by us, or;
• With your local machine.

Using GitHub Codespaces

Follow the official GitHub guide for developing with a codespace.

Using your local developer environment

In summary:

• Clone the repository to your local machine
• Follow instructions for running the app locally

Running the app locally

Install dependencies

npm i

Set environment variables

cp .env.example .env.development.local

Optionally set POSTMAN_API_KEY to send login OTP emails via Postman. If not set, OTP emails will be logged to the console instead.e

Retrieving client-side environment variables in code

⚠️ When adding client-only environment variables in NextJS, you must prefix the variable with NEXT_PUBLIC_ to ensure that the variable is exposed to the browser. For example, if you want to add a variable called MY_ENV_VAR, you should add it to your .env file as NEXT_PUBLIC_MY_ENV_VAR.

You will also need to update src/env.mjs to explicitly reference the variable so NextJS will correctly bundle the environment variable into the client-side bundle.

Start database

# Assumes that you have previously copied .env.example to .env.development.local
export $(grep DATABASE_URL .env.development.local | xargs) && npm run setup

Start server

npm run dev

Developer Operations

TODO: CI/CD test with GitHub Actions

TODO: Github branch protection rules

Useful notes

Commands

npm run build      # runs `prisma generate` + `prisma migrate` + `next build`
npm run db:reset   # resets local db
npm run dev        # starts next.js
npm run setup      # starts cockroach db + runs migrations + seed
npm run test-dev   # runs e2e tests on dev
npm run test-start # runs e2e tests on `next start` - build required before
npm run test:unit  # runs normal Vitest unit tests
npm run test:e2e   # runs e2e tests

Files of note

Path	Description
./prisma/schema.prisma	Prisma schema
./src/pages/api/trpc/[trpc].ts	tRPC response handler
./src/server/routers	Your app's different tRPC-routers

---