Clarify env files (#135)

* Adds a `prepare-env` script
* Updates README
* Removes / reorgs `.env` files

.env

@@ -1,23 +1,17 @@
-# Common PUBLIC variables can go in here to conserve space for the Lambda
-# in-memory vars
+# Public variables can go in here to conserve space for the Lambda in-memory vars
 
 # General
 NEXT_PUBLIC_LOCALE='en-US'
 
 # TakeShape
 NEXT_PUBLIC_TAKESHAPE_API_URL='https://api.takeshape.io/project/06ccc3dc-a9da-4f5b-9142-5a104db52ee3/v3/graphql'
 NEXT_PUBLIC_TAKESHAPE_ANONYMOUS_API_KEY='a9a84ace044c4d2796112c5710008a2f'
-
-# TakeShape Auth
 NEXT_PUBLIC_TAKESHAPE_AUTH_ISSUER='https://penny-ecommerce.vercel.app/'
 NEXT_PUBLIC_TAKESHAPE_AUTH_AUDIENCE='https://api.takeshape.io/project/06ccc3dc-a9da-4f5b-9142-5a104db52ee3/open-id'
 
 # Default newsletter list
 NEXT_PUBLIC_DEFAULT_KLAVIYO_LIST_ID='WkaTiM'
 
-# Sentry
-SENTRY_IGNORE_API_RESOLUTION_ERROR='1'
-
 # Shopify
 # Scopes: unauthenticated_write_checkouts,
 # unauthenticated_read_checkouts, unauthenticated_write_customers,
@@ -35,3 +29,12 @@ NEXT_PUBLIC_SITE_CONTACT_EMAIL='[email protected]'
 
 # Contact Provider
 NEXT_PUBLIC_CONTACT_PROVIDER='gorgias'
+
+# ReCAPTCHA
+NEXT_PUBLIC_RECAPTCHA_SITE_KEY='6LdArl4gAAAAADf30J5nPO2hStNG8_IYrnl43RlT'
+
+# Sentry
+NEXT_PUBLIC_SENTRY_DSN='https://[email protected]/6512748'
+SENTRY_ORG='takeshape-deluxetm-sample-proj'
+SENTRY_PROJECT='deluxe-sample-project'
+SENTRY_IGNORE_API_RESOLUTION_ERROR='1'

.env-example

@@ -1,10 +1,11 @@
-# Common PUBLIC variables can go in here to conserve space for the Lambda
-# in-memory vars
+# Copy this file and rename as `.env`
+# Public variables can go in here to conserve space for the Lambda in-memory vars
 
 # General
 NEXT_PUBLIC_LOCALE='en-US'
 
 # TakeShape
+
 # This comes from your TakeShape Home page
 NEXT_PUBLIC_TAKESHAPE_API_URL=''
 # You created this on the Settings > API Keys page
@@ -14,12 +15,6 @@ NEXT_PUBLIC_TAKESHAPE_AUTH_ISSUER=''
 # This is generated in the OpenID Connect config, paste what is there
 NEXT_PUBLIC_TAKESHAPE_AUTH_AUDIENCE=''
 
-# Klaviyo - the id for a default list used in the newsletter signup form
-NEXT_PUBLIC_DEFAULT_KLAVIYO_LIST_ID=''
-
-# Sentry - Suppresses some Sentry warnings that will be removed in future version
-SENTRY_IGNORE_API_RESOLUTION_ERROR='1'
-
 # Shopify - Required Storefront API Token Scopes
 # unauthenticated_write_checkouts,
 # unauthenticated_read_checkouts,
@@ -32,5 +27,25 @@ SENTRY_IGNORE_API_RESOLUTION_ERROR='1'
 NEXT_PUBLIC_SHOPIFY_STOREFRONT_TOKEN=''
 NEXT_PUBLIC_SHOPIFY_STOREFRONT_URL=''
 
-# Use Multipass
-NEXT_PUBLIC_SHOPIFY_USE_MULTIPASS='true'
+# Use Multipass - true or false
+NEXT_PUBLIC_SHOPIFY_USE_MULTIPASS=''
+
+# Contact Provider - gorgias or zendesk
+NEXT_PUBLIC_CONTACT_PROVIDER=''
+
+# Contact Email
+NEXT_PUBLIC_SITE_CONTACT_EMAIL=''
+
+# Klaviyo - the id for a default list used in the newsletter signup form
+NEXT_PUBLIC_DEFAULT_KLAVIYO_LIST_ID=''
+
+# ReCAPTCHA
+NEXT_PUBLIC_RECAPTCHA_SITE_KEY=''
+
+# Sentry
+NEXT_PUBLIC_SENTRY_DSN=''
+SENTRY_ORG=''
+SENTRY_PROJECT=''
+
+# Suppresses some Sentry warnings that will be removed in future version - 1 or 0
+SENTRY_IGNORE_API_RESOLUTION_ERROR='1'

.env.local-example

@@ -6,15 +6,13 @@ NEXTAUTH_SECRET=''
  # NextAuthAllAccess - `npx @takeshape/next-auth-all-access generate-keys`
 ALLACCESS_PRIVATE_KEY=''
 
-# ReCAPTCHA
-NEXT_PUBLIC_RECAPTCHA_SITE_KEY=''
+# NextAuth - Google Provider for Multipass
+GOOGLE_CLIENT_ID=''
+GOOGLE_CLIENT_SECRET=''
 
-# Sentry
+# If you want to disable Sentry for local dev redefine this here
 NEXT_PUBLIC_SENTRY_DSN=''
-SENTRY_ORG=''
-SENTRY_PROJECT=''
 
-# Multipass
+# Shopify Multipass
 SHOPIFY_MULTIPASS_SECRET=''
-GOOGLE_CLIENT_ID=''
-GOOGLE_CLIENT_SECRET=''
+

.env.test

@@ -1,24 +1,15 @@
-# NOTE: Only add public env variables here.
+# This file has settings that only apply to test runs
+# Only put public variables in here, anything secret should go in your runtime env
 
-# Locale for currency formatting
-NEXT_PUBLIC_LOCALE='en-US'
-# e.g.: 'dev-by9w1mxg.us.auth0.com'
-NEXT_PUBLIC_AUTH0_DOMAIN='dev-by9w1mxg.us.auth0.com'
-# Your Auth0 application's Client ID
-NEXT_PUBLIC_AUTH0_CLIENT_ID='qFoQD6d6vGhob9B8lguJbolKKXnL6jDQ'
-# Where to redirect after you login
-NEXT_PUBLIC_AUTH0_REDIRECT_URI='http://localhost:3000/'
-# Auth0 scopes to set, these are required for the necessary auth0 data
-NEXT_PUBLIC_AUTH0_SCOPE='openid profile email offline_access'
-# Auth0 audience must match the audience of your Custom API in Auth0 and TakeShape service
-# Looks like: https://api.takeshape.io/project/f56d44bb-8261-41e0-b3ee-af37931cb493/my-auth-0-service-id
-NEXT_PUBLIC_AUTH0_AUDIENCE='https://api.takeshape.io/project/06ccc3dc-a9da-4f5b-9142-5a104db52ee3/auth-0'
-# Copy the API Endpoint from your TakeShape Project > API > API Endpoint in the lower left
-# Looks like: https://api.takeshape.io/project/f56d44bb-8261-41e0-b3ee-af37931cb493/v3/graphql
-NEXT_PUBLIC_TAKESHAPE_API_URL='https://api.takeshape.io/project/06ccc3dc-a9da-4f5b-9142-5a104db52ee3/v3/graphql'
-# An API Key from TakeShape with the `anonymous` role
-NEXT_PUBLIC_TAKESHAPE_ANONYMOUS_API_KEY='a9a84ace044c4d2796112c5710008a2f'
-# A Stripe API publishable key
-NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY='pk_test_51JG7sTEjMGaPiQ74KqSiOjmOM3A64zrSHkogtR9rzMfC3PZauNAwGV7nDZmH1tNx9LwcJT7pLoKwMZSHaW30EifX00dYuNHWaq'
 # Default newsletter list
 NEXT_PUBLIC_DEFAULT_KLAVIYO_LIST_ID='test-list'
+
+# Contact Email
+NEXT_PUBLIC_SITE_CONTACT_EMAIL='[email protected]'
+
+# ReCAPTCHA
+NEXT_PUBLIC_RECAPTCHA_SITE_KEY=''
+
+# Sentry
+NEXT_PUBLIC_SENTRY_DSN=''
+SENTRY_IGNORE_API_RESOLUTION_ERROR='1'

.env.test-example

@@ -0,0 +1,9 @@
+# These variables are only loaded when NODE_ENV=test, such as with Cypress or Jest.
+# Any variable in here will override or add to the variables in the .env file.
+# Read more here: https://nextjs.org/docs/basic-features/environment-variables#test-environment-variables
+
+# ReCAPTCHA
+NEXT_PUBLIC_RECAPTCHA_SITE_KEY=''
+
+# Sentry
+NEXT_PUBLIC_SENTRY_DSN=''

README.md

@@ -194,9 +194,28 @@ git clone https://github.com/takeshape/penny
 5. Navigate to the project directory in your local terminal and run the `npm install` command to install all
    dependencies.
 
-If you want to run this project locally, follow the instructions in the `.env.test` file.
+6. Set up your environment variables.
 
-The following instructions will help you configure all of the services this project uses.
+- Every project will contain a mix of variables defined in `.env` files and runtime variables defined in a hosting
+  provider.
+
+- Create your project's `.env` starter files. Run `npm run prepare-env`. This repo already contains some `.env` files
+  used for the demo, so you will be prompted to overwrite those files.
+
+- Because many variables are required to get a fully functional project you should ensure all your services are
+  configured before customizing the `.env` files. Take a look at the `.env` files now to get a sense of what you'll need
+  before you run the project, and take note of where the various keys and secrets live along the way.
+
+- `.env` contains common variables for all runtimes. You can define **publicly** available variables here. In most cases
+  these are prefixed with `NEXT_PUBLIC`.
+
+- `.env.local` contains variables to use during local development. This file **is not** checked into your repo and can
+  contain all the secrets you need to get your local development environment running, as well as overrides for common
+  `.env` variables.
+
+- `.env.test` contains variables and overrides only used when running tests, like `jest` or `cypress`.
+
+> Warning! Never check secrets into your repo!
 
 ### NextAuth and OpenID
 
@@ -690,11 +709,6 @@ Because of how the Google OAuth2 service works, you cannot use wildcard callback
 Google auth in Vercel preview environments, which use dynamic URLs. It is recommended you unset
 `NEXT_PUBLIC_SHOPIFY_USE_MULTIPASS` for preview environments and configure it on a case-by-case basis.
 
-### Other environment variables
-
-1. Copy the `.env.local-example` file to `.env.local` and follow the instructions.
-2. Copy the `.env-example` file, overwriting the `.env` file, and follow the instructions.
-
 ## Type generation
 
 Your project is configured to generate types for the GraphQL APIs in use. Run `npm run graphql:typegen` before running
@@ -722,7 +736,7 @@ Both services offer preview deployments, which we've enabled on our PRs.
 
 # GitHub Actions
 
-If you are using the included workflows you will get a great CI process, that includes:
+If you are using the included workflows you will get a great CI process that includes:
 
 - Unit tests on every PR
 - Cypress E2E Testing on every PR