Home

Getting Started

Install Yarn

Install Yarn as the package manager. All npm commands should be using yarn and not npm. After installing Yarn, run yarn once at the root of the repository.

yarn

Set up the .env file

Make a copy of apps/portal/.env.example to apps/portal.env. This is the environment config that is used by the TIH Portal Next.js app.

cp apps/portal/.env.local apps/portal.env

• DATABASE_URL: You will need to have a local PostgreSQL database already running and add in the password.
• GITHUB_CLIENT_SECRET: Ping @yangshun) for the value.

Run the app locally

• yarn dev: Runs just app/portal. Most of the time you'll only need this. Open http://localhost:3000 to access the app.
• yarn dev:ui: Runs just `app/storybook. Runs the local Storybook environment.

Tech Stack

Area	Choice	What is it
Monorepo	Turborepo	High-performance build system that allows you to break a repo into multiple smaller packages
Language	TypeScript	Statically typed JavaScript
View	React	Most popular UI library
App Framework	Next.js	React meta framework that has multiple ways of rendering
Styling	Tailwind CSS	Rapidly build modern websites without ever leaving your HTML
Data Fetching	React Query	A pretty sophisticated data fetching library
Auth	NextAuth.js	Authentication for Next.js, supports many OAuth options
Type Safety	tRPC	End-to-end typesafe APIs made easy
ORM	Prisma	Next-generation Node.js and TypeScript ORM
Database	PostgreSQL	Popular open source relational database

Development

Source Control

• main is release branch and should remain stable at all times.
• Create feature branches for your in-progress features and using the format <username>/my-feature (doesn't have to be your GitHub username, just use something identifiable and be consistent about it).
• Before merging/pushing to main, ensure that running yarn ci in the root directory doesn't show any errors.
• We use a variation of Conventional Commits specification for commit messages:
• Use [feat] my commit message instead of feat: my commit message.
• Prefix the commit message with the project. E.g. [resumes][feat] foobar, [offers][fix] foobar, [questions][refactor] foobar.
• Rebase and squash commits into a single commit before merging into main. We don't want main to contain any merge commits. A linear Git history is much easier to look at.
• Delete your branch after merging into main.

Code Editor

• VS Code is the recommended IDE due to it's superb support for TypeScript.
• Install the following extensions for VS Code, or find the equivalents for your IDE:
  • Prettier - Code formatter
  • TypeScript Importer
  • Tailwind CSS IntelliSense
  • ESLint
  • Prisma
  • Stylelint
  • Code Spell Checker
  • Optional: Tailwind Docs
• Use Workspace settings (in .vscode/settings.json (as the source of truth for your VS Code settings for this project.

Directory Structure

The repository is structured as a Turborepo monorepo:

.
├── package.json # Global dependencies. You shouldn't need to modify this.
├── apps
│   ├── portal # TIH portal
│   ├── storybook # Storybook to view and try UI components
│   └── website # Existing website on Docusaurus. Ignore
└── packages
    ├── eslint-config-tih # ESLint configuration
    ├── tsconfig # TypeScript configuration
    └── ui # UI components

You should spend most of the time building within /apps/portal. New dependencies should be installed within /apps/portal/package.json.

Front End

Next.js

• For most imports, use ~/ which is an alias for the apps/portal/src instead of relative paths.
• We're using the new newNextLinkBehavior: true flag, so there's no need for <a> within <Link>.
• SSR pages as much as possible (via getServerSideProps()), rather than fetching data on the client side for better SEO.
• Work within your designated directories:
  • Resumes: src/components/resumes and src/pages/resumes
  • Offers: src/components/offers and src/pages/offers
  • Questions: src/components/questions and src/pages/questions

React

• Props should be Readonly.
• Props should be sorted alphabetically.
• Props should be destructured in the component function declaration.

Styling

• Use components as much as possible, rather than Tailwind classes.
• TODO

Data Fetching

React Query is a client side state management library to help you manage remote state (data fetched from the server). With React Query (and tRPC), you can do data fetching in a declarative and typesafe manner.

Form Library

• Form library TBD. Possibly react-hook-form.
• Don't add state for forms unless necessary (e.g. front end validation).

Back End

Data Model: Prisma

We use Prisma, which is an ORM for JavaScript/TypeScript applications. Make sure you have the Prisma VS Code extension installed, which gives you autocompletion and formatting of the .prisma files.

• Model
  • Namespace/Prefix your models per project (e.g. ResumesSomething, OffersSomething, QuestionsSomething).
  • enum values should be written using UPPER_SNAKE_CASE.
• Fields
  • Use camelCase for fields in schema.prisma. If you see some snake_case fields in Account, that's because of the requirements of NextAuth.js, and they are exceptions.
  • Use cuid() for ids, don't use autoincrement(). We don't want to reveal how many rows there are in a table.
  • Look around and see the existing schema fields and try to be consistent about field naming, even across projects.

Prisma Studio

In case you want to have an admin view of your database, run yarn prisma studio which will run an admin web app on http://localhost:5555.

Server API calls: tRPC

• userIds for creator fields should always come from the session, not from a parameter.
• Prisma doesn’t have ACL (access control list), so we need to manually implement permissioning in tRPC routing code.

Database

Set up your own local PostgreSQL database and update the DATABASE_URL field within the .env file.

Setting up

Run prisma migrate dev if it's your first time.

Changing schema

1. After you change schema.prisma, run prisma migrate. Prisma will generate migration files for you and make the changes in your local database.
2. Ping @yangshun to productionize any changes.

Auth

We're using NextAuth.js which has integrations with many auth providers for Next.js and is super handy. Most of the time you won't need to mess with authentication since it's already done. But if you need to, here's NextAuth.js' official demo site and the source code on GitHub.