Skip to content

Latest commit

 

History

History
238 lines (153 loc) · 6.63 KB

LOCAL.md

File metadata and controls

238 lines (153 loc) · 6.63 KB

Local Setup

Join the Trash Discord

To contribute you will first need to fork the repo and make some adjustments to get it up and running on your local machine. Below are the steps to follow for you to get TypeHero to run on your local machine.

1. Create a .env file

Provide your values as needed.

2 Configure your database

You can either use PlanetScale or a local Docker container to run your database. Use either 2.a or 2.b for the next step.

2.a Local Database (using Docker)

Starting the docker container

docker compose up -d

2.b Remote Database (using PlanetScale)

Follow the PlanetScale quick start guide to get started

After creating an account and creating a database using the steps above:

  1. Click either the big "Connect" button or the "connect to your database" Link. connect

  2. Select "Connect with Prisma" and copy the DATABASE_URL for your .env getting the connection string

3. Create a new GitHub OAuth Application

Follow this link to create a new app filling the following required details on creation:

Homepage URL: http://localhost:3000
Authorization callback URL: http://localhost:3000/api/auth/callback/github

Once completed, you will be redirected to the application page settings, from there create the client secret by clicking on Generate a new client secret button.

Next, copy the client secret generated and the client ID into the .env file, replacing <client_id> and <client_secret>, respectively:

GITHUB_ID=<client_id>
GITHUB_SECRET=<client_secret>

4. Setup uploadthing for file uploads

Go to uploadthing.com and create a project, then copy in the secrets into your .env.

In the end your local .env file should look something like the following

DATABASE_URL="mysql://dev:dev@localhost/typehero"
GITHUB_ID=very_real_github_id
GITHUB_SECRET=very_real_secret

UPLOADTHING_SECRET="very_real_uploadthing_secret"
UPLOADTHING_APP_ID="very_real_uploadthing_app_id"
# Next Auth
# You can generate a new secret on the command line with:
# openssl rand -base64 32
# https://next-auth.js.org/configuration/options#secret
NEXTAUTH_SECRET="for local use you can just use a garble of letters"
NEXTAUTH_URL="http://localhost:3000"

5. Setup algolia for search

Go to algolia.com and create a project, then copy in the secrets into your .env.

NEXT_PUBLIC_ALGOLIA_APP_ID=APP_ID
NEXT_PUBLIC_ALGOLIA_API_KEY=API_KEY

6. Install dependencies

Use pnpm to install dependencies.

pnpm install

7. Push Database Schema and Seed

pnpm db:push
pnpm db:seed

8. Running the dev server

Finally, you can run the dev server:

pnpm dev

Sync data

Once the server is running you can seed and sync data

  1. Navigate to http://localhost:3000/api/auth/github to authenticate with GitHub OAuth.

Make Yourself an Admin

  1. Ensure you have logged into your local instance atleast once

  2. Run pnpm db:studio - to open Prisma Studio

    prisma studio

  3. Click on the User table from the list of models

  4. Locate your username and open record in new tab to modify Role

    modify role

Dependencies

UI Library: shadcn

Testing

1. Install Playwright Dependencies

pnpm test:e2e:install

2. Run E2E Tests

You can use the production server or the dev server to run the e2e tests.

Warning

The dev server may cause tests to timeout.

2.a Production server

Playwright will automatically start the production server

pnpm build && pnpm test:e2e

2.b Dev server

Open two separate terminals and run the following commands in each one:

Terminal 1:

pnpm dev

Terminal 2:

pnpm test:e2e

Running Tests in UI Mode

In the event you need to troubleshoot the end-to-end tests, you can run Playwright in UI mode. You can do this by running pnpm test:e2e:ui. This will spin up a playwright server on localhost:8080, which will provide a playwright app that you can use to view a series of snapshots.

In addition you can use Playwright Inspector to debug tests, which is a debugger that Playwright maintains. It automatically stops at each test suite, as well as each test case within them. As a result, you can debug a specific test suite by running pnpm test:e2e:inspector -- {testName}

Troubleshooting A11y

In the event the end-to-end tests find an A11y violation, the playwright report will contain more information. Such as the description of the violation, a link to Deque University that will explain the violation as well as some ways to fix it, and finally the HTML that is causing the violation.

You can access the playwright report by first running pnpm test:e2e. After it has completed, you can run pnpm exec playwright show-report to see the HTML report, or simply open the index.html file under apps/web/playwright-report.

FAQ

How do I totally rebuild and re-seed the database?

Run the command

pnpm refresh

This will cause Prisma to force reset the database through the db:reset command and then run db:seed.

What if I run into errors with that command? If you are using the docker setup for your local environment then get into the container with 
docker exec -it typehero-db bash
# we are in the container from here on
$ mysql -u dev -p -h 127.0.0.1 typehero
> drop database typehero;

Exit out of the container and then run

pnpm refresh

This tends to resolve the issue as it entirely destroys and rebuilds + reseeds the database.

How do I use the `@vercel/toolbar` locally? If you have access to the vercel project then you can run `vercel link` (make sure you have the vercel CLI).

Follow the interactive CLI to link it to the Trash Company/typehero project.

From there on out you should be able to read and make comments while on local host for that branch.