The working directory for this project is the same folder the README you are
reading right now is located. All commands assume you are in
the {PROJECT_ROOT}/apps/testing-javascript
in your console.
cd apps/testing-javascript
You may need access to the following serverless accounts to run the app:
- Stripe (for Stripe env vars and Stripe CLI)
- Vercel (for env vars, e.g.
POSTMARK_KEY
) - Planetscale (if needed) or use MySQL in Docker
Install all of the dependencies for the entire monorepo by running the following command:
pnpm install
猸愶笍 pnpm install
can be run from any folder in the monorepo and it will install
the dependencies for all projects and apps in the monorepo.
Copy the template .env.local.template
file to .env.local
and .env.template
to .env
馃敀 env.local
contains local private environment variables
ALGOLIA_API_WRITE_KEY
: Required when runningpnpm build
which invokesnext build
which useNODE_ENV=production
.CONVERTKIT_API_SECRET
: not required for local development unless actively working on ConvertKit integration. Can be found in 1password.POSTMARK_KEY
: not required to run in dev, but enables email sending from local environment. Can be found in 1password.STRIPE_SECRET_TOKEN
: Not required unless you need to make an end to end purchase. Can be found in 1password.SKILL_SECRET
: Required for interaction with any access-protected API skill-api endpoint, such aswebhook/stripe-internal
used for any Stripe interaction like making purchases. Add to.env.local
using whatever secret value (recommended: generate a value with this commandecho "sks_$(uuidgen | tr '[:upper:]' '[:lower:]')"
). See Stripe section for the rest of the setup instructions.
馃憢 .env
is required by Prisma and only contains DATABASE_URL
. The
full contents
of this file by default are are:
DATABASE_URL="mysql://root@localhost:3309/kcd-products"
You can use the provided templates. These files are ignored by git because they should never be committed to the repository under any circumstances.
cp .env.local.template .env.local
cp .env.template .env
.env.local
will need new values for every variable.
Now build the app and all dependencies with the following command:
pnpm build
This command will also test
and lint
the project. If you run into errors at
this step, they should be addressed.
At this point you successfully built the app without any errors, then you should be able to run it locally.
pnpm dev
The app will be served at http://localhost:3018
.
You won't be able to do much without setting up a few other dependencies.
Locally we use MySQL via Docker or Planetscale. In production we use Planetscale. Planetscale has a CLI and this is required if you are making changes to the database schema that need to be propogated to production databases via a branch.
You'll need to install Docker Desktop in order to run MySQL with Docker.
If you didn't already, make sure the .env
file is availabe with
the DATABASE_URL
env var set.
Important: If you are developing a standalone script (like a data migration
script) that uses the generated Prisma client, be sure to
use dotenv-flow
to require
the DATABASE_URL
appropriate to the target app.
See Configure your Dev Environment for the details.
To run MySQL (via Docker) execute the following command:
pnpm db:start
pnpm db:push
This starts the MySQL container (running on port 3309
) and applies any schema
changes as needed.
The first time you run this command it will seed the database with the contents
of apps/testing-javascript/seed_data
If you want to reset the database, open docker, delete the container and the associated image. Otherwise nothing will be changed with the database when you run the above command but it will be running normally in the background.
The database can be stopped and started from the Docker dashboard.
Note: the default username
for this MySQL instance is root
and
the password
is blank.
If you need to utilize the Planetscale CLI use the following command:
brew install planetscale/tap/pscale
You'll need to login:
pscale auth login
And then switch to skill-recordings org:
pscale org switch skill-recordings
Finally run the database:
pscale connect kcd-products BRANCH_NAME --port 3309
The production database runs on the main
branch. Use the production database
with caution!
To receive "magic link" emails you'll need a database configured and a valid postmark key.
馃憢 The magic links are logged to the developer console as well so you don't need Postmark configured to simply log in to the app.
鉀旓笍 You can only log in if you have a User
with the email you are trying to use
in the database.
A Postmark API key is required to send email from your local environment. It is
located in 1password or via Postmark and can be added to .env.local
.
This app works in coordination with epic-web
's stripe webhook handling API.
In order to go through a full purchase flow, process refunds, etc., the
epic-web
app will also need to be running (cd ../epic-web; pnpm dev
). The
epic-web
pnpm dev
command will run both the Next.js dev server (running its
API) and a local Stripe webhook listener. Any Testing JavaScript Stripe events
will hit the epic-web
webhook endpoint and will be forwarded to
testing-javascript
's api/skill/webhook/stripe-internal
endpoint.
Prerequisites:
- Have
epic-web
fully setup and running locally - Set the
SKILL_SECRET
value for this app in.env.local
- Use that same
SKILL_SECRET
value inepic-web
's.env.development.local
with the keyTJS_SKILL_SECRET
pscale connect kcd-products PLANETSCALE_DB_BRANCH_NAME --port 3309
Before making any changes to the schema, consider the impact those changes will have on a production system with preexisting live data. You will likely need to take a multi-step approach to get to your desired schema. Prisma's Expand-and-Contract Pattern guide is a good reference for what this multi-step approach might look like.
To alter the schema, you'll need to first
update /packages/database/prisma/schema.prisma
.
Worth noting if you're familiar with writing migrations for database updates: With Planetscale, you alter the schema directly instead of writing migrations. The upside of this approach is that it leaves the responsibility of safe migrations up to Planetscale. The downside is that it will frequently require multiple separate releases if following the Expand-and-Contract Pattern.
When you make changes to the schema via Prisma you'll need to explicitly push it to the DB. We don't use Prisma migrations.
You can test out your schema changes locally with the MySQL in Docker instance.
First, make sure Docker is running with MySQL at the appropriate port (3309
).
Then, apply the changes to the MySQL databse using Prisma's db push
command.
npx prisma db push
From here, you can connect to the MySQL database with a SQL client to view the changes or view it from Prisma Studio.
To develop against the new schema with the full power of Prisma's TypeScript typings, you'll need to re-generate the Prisma client for the updated schema.
pnpm db:generate
This works much the same as with apply schema changes to MySQL in Docker, except we need to push the changes to Planetscale.
If you don't have it already, you'll need to create a Planetscale branch off
the main
database branch. You can do that from the Planetscale dashboard or
using the CLI:
pscale branch create kcd-products PLANETSCALE_DB_BRANCH_NAME
Now open up a connection to the branch that you've created for these schema changes.
pscale connect kcd-products PLANETSCALE_DB_BRANCH_NAME --port 3309
With a connection open at port 3309
, we can now push our schema changes up to
Planetscale.
pnpm db:push
The next step is to open a Deploy Request for getting a team review of your schema changes. This can also either be done from the Planetscale dashboard or the CLI:
pscale deploy-request create kcd-products descriptive-branch-name
Once the Deploy Request has been reviewed and confirmed, Planetscale will
schedule the migration of those schema changes against the main
branch. This
shouldn't take too long for smaller databases. Once the migration is complete,
your schema changes will be live in the production database. This is why it is
important that schema changes are applied incrementally in a non-breaking way.
Start prisma studio:
pnpm db:studio
There are a couple SQL files located in seed_data/
that contain insert
statements for seeding initial users and Stripe product data. You should only
be running these if your database is completely empty and you aren't trying to
restore data from an existing database.
These can be used to seed a locally running MySQL database on port 3309 with the following commands.
mysql -h ::1 -P 3309 -u root -D kcd-products < seed_data/User.00001.sql
mysql -h ::1 -P 3309 -u root -D kcd-products < seed_data/Product.00001.sql
Or they can be used to seed a Planetscale database/branch. To do that, first
open a local proxy connection to the desired Planetscale branch (e.g.
staging
):
pscale connect kcd-products staging --port 3309 --host "::1"
and then run the same commands as you would locally as these will now be proxied to the remote Planetscale database:
mysql -h ::1 -P 3309 -u root -D kcd-products < seed_data/User.00001.sql
mysql -h ::1 -P 3309 -u root -D kcd-products < seed_data/Product.00001.sql
When you make a new branch in Planetscale it doesn't bring data over.
You can seed your branch with the basics that are associated with the test
mode Stripe account. Those seeds are located in seed_data
.
pscale database restore-dump kcd-products next-steps --dir ./seed_data
You can locally dump a copy of the main
branch using pscale database dump
:
pscale database dump kcd-products main --output ./seed_data/pscale_data_dump
Now the seed_data/pscale_data_dump
folder holds a database dump you can
restore to your branch:
pscale database restore-dump kcd-products next-steps --dir ./seed_data/pscale_data_dump --overwrite-tables
Edit workshops with Sanity at testing-javascript.sanity.studio.