NOTE: the team is actively working towards getting the repo in a state where anyone can run the app locally without requiring specific permissions.
- Read
docs/Leveraging Modern NextJS Features.md
for an overview on the new Next.js features and React Server Components + Server Actions being leveraged in this repo- If this is your first time working with these technologies, please take the time to read the linked-to blog posts
- Read
docs/Coding Conventions.md
for an overview of coding conventions encouraged for this project
- Install Node v20.10.0 (nvm is recommended for installing Node)
- Install Docker Desktop + CLI
- Install Homebrew
- Clone this repository to your local machine (forking is disabled)
- If you are using SSH to clone, but you do not have a public SSH key for your GitHub account (which will prevent cloning), follow the GitHub SSH guide to set up SSH authentication and signing
cd
into your local swc-web repository- Run
npm install
- Run
cp .env.example .env
- This will generate a new
.env
file in your local repository; this will store all your local environment variables
- This will generate a new
- Open the
.env
file with your favorite text editor, and update the environment variables based off the commented instructions- Updating your
.env
is VERY important, so do that before moving on
- Updating your
- Run
npm run initial
which includes all required set-up commands for first-time local development
npm run dev
- runs the development server locally- In a separate terminal tab,
npm run inngest
- runs Inngest- Both the development server AND Inngest are required for a fully functional website
- Open http://localhost:3000 with your browser to see the results
npx prisma generate
- generates Prisma ORM TypeScript definitions (i.e. DB client code) based onprisma/prisma.schema
- Whenever you make Prisma schema changes, you should run the generate command
npx prisma studio
- spins up a full database UI for the database you are connected tonpm run db:seed
- resets your PlanetScale database, then populates the PlanetScale database with seed data- The database will be based on the
DATABASE_URL
provided in your local.env
file - we will refer to this as "the database you are connected to"
- The database will be based on the
npm run codegen
- generates TypeScript definitions for any GraphQL operations we have defined in our codebase- Whenever you make GraphQL query updates (e.g. our DTSI integration), you should run this command to update your TypeScript definitions
npm run codegen:schemas
- if any of the GraphQL schemas changed for our 3rd-party API partners (e.g. https://www.dotheysupportit.com/), run this command to pull in the latest schemasnpm run intl:extract-compile
- generates initial translation filesnpm run storybook
- view isolated storybook stories- When checking out someone else's branch with changes - if you encounter TypeScript errors, run
npm run newbranch
to execute several common commands that may fix these errors
Whenever you make Prisma schema changes (or pulling commits from main
that includes Prisma schema changes), run the following commands:
npx prisma generate
- updates your Prisma TypeScript definitions- Then, depending on your situation, run either of the following:
npx prisma db push
- if your changes are not breaking and you want to maintain the values in your database, then run this command; this will simply push the schema changes to the database instance you are connected tonpm run db:seed
- if you do have breaking changes, or if you just want to reset your database values, then run this command; this command force-pushes the schema updates to the database instance you are connected to, wiping all existing information and freshly populating the database with seed data
-
Before committing changes, please audit your code locally:
npm run lint
- audits code against ESLint and Prettiernpm run typecheck
- audits code against TypeScriptnpm run test
- execute Jest testsnpm run precheck
- executes all 3 commands above concurrently- If
precheck
fails, then it is very likely that your PR will not pass GitHub CI
- If
-
Likewise, test E2E flows as necessary:
npm run e2e:run
- starts up Cypress UI- With the UI, you can run individual E2E tests under "Specs" and visually follow the flows
npm run e2e:run-headless
- runs all our E2E tests consecutively via Cypress CLI- Currently, this command only executes when new comments are made to main branch because of database dependencies - this may change in the future
- NOTE: the E2E testing suite connects to a local MySQL database, not your PlanetScale database - it will live on
localhost:3306
- Refer to
docs/Coding Conventions.md/Testing
for more information
- Navigate to main branch and run
./bin/deploy_web_production.sh
- Read
docs/Contributing.md
for information on submitting PRs, including database migration steps related to your PR
Before proceeding with anything, PLEASE take time to review the Knowledge pre-requisites.
- Read "What is Prisma" and "Why Prisma" to learn about the ORM we use to query our database
- Watch this YouTube video for a great overview of the tradeoffs between the UI library/framework options that exist for frontend development, and why we decided to use TailwindCSS + Radix UI as our template
- Read Vercel's guide on "Connection Pooling with Serverless Functions" to learn about the architecture tradeoffs of connecting to SQL database in serverless environments, and why we decided to leverage the robust scalability architecture inherent in PlanetScale
- Read the Inngest docs to learn more about how to leverage the tool to build resilient workflows
Software source code, documentation source, and configuration files are licensed under Apache 2.0. Non-code documentation is licensed under CC-BY-4.0.