Fix supertokens docs & integration issues

docs/docs/auth/supertokens.md

@@ -23,13 +23,37 @@ For now, let's focus on SuperTokens's side of things.
 
 When you run the setup command it configures your app to support both email+password logins as well as social auth logins (Apple, GitHub and Google). Working with those social auth logins does require quite a few environment variables. And SuperTokens itself needs a couple variables too. Thankfully SuperTokens makes this very easy to setup as they provide values we can use for testing.
 
-So just copy this to your project's `.env` file.
+# Environment variables
 
-```bash title=".env"
+The environment variables have to be added either to your project's `.env` file (when running in development environment), or to the environment variables of your hosting provider (where running in production).
+
+## Base setup
+
+```bash
+SUPERTOKENS_APP_NAME="Redwoodjs App" # this will be used in the email template for password reset or email verification emails.
 SUPERTOKENS_JWKS_URL=http://localhost:8910/.redwood/functions/auth/jwt/jwks.json
+SUPERTOKENS_CONNECTION_URI=https://try.supertokens.io # set to the correct connection uri
+```
+
+## Production setup
+
+Assuming that your web side is hosted on `https://myapp.com`:
+
+```bash
+SUPERTOKENS_WEBSITE_DOMAIN=https://myapp.com
+SUPERTOKENS_JWKS_URL=https://myapp.com/.redwood/functions/auth/jwt/jwks.json
+```
+
+## Managed Supertokens service setup
+
+```bash
+SUPERTOKENS_API_KEY=your-api-key # The value can be omitted when self-hosting Supertokens
+```
 
-SUPERTOKENS_CONNECTION_URI=https://try.supertokens.io
+## Social login setup
+The following environment variables have to be set up (depending on the social login options):
 
+```bash
 SUPERTOKENS_APPLE_CLIENT_ID=4398792-io.supertokens.example.service
 SUPERTOKENS_APPLE_SECRET_KEY_ID=7M48Y4RYDL
 SUPERTOKENS_APPLE_SECRET_PRIVATE_KEY=-----BEGIN PRIVATE KEY-----\nMIGTAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBHkwdwIBAQQgu8gXs+XYkqXD6Ala9Sf/iJXzhbwcoG5dMh1OonpdJUmgCgYIKoZIzj0DAQehRANCAASfrvlFbFCYqn3I2zeknYXLwtH30JuOKestDbSfZYxZNMqhF/OzdZFTV0zc5u5s3eN+oCWbnvl0hM+9IW0UlkdA\n-----END PRIVATE KEY-----
@@ -40,7 +64,24 @@ SUPERTOKENS_GOOGLE_CLIENT_ID=1060725074195-kmeum4crr01uirfl2op9kd5acmi9jutn.apps
 SUPERTOKENS_GOOGLE_CLIENT_SECRET=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
 ```
 
-That should be enough; now, things should just work.
+## `redwood.toml` setup
+
+Make sure to modify `redwood.toml` to pass the required environment variables to the web side:
+
+```toml
+[web]
+...
+includeEnvironmentVariables = [
+  'SUPERTOKENS_WEBSITE_DOMAIN',
+  'SUPERTOKENS_API_DOMAIN',
+  'SUPERTOKENS_API_GATEWAY_PATH',
+  'SUPERTOKENS_APP_NAME'
+]
+```
+
+
+# Page setup
+
 Let's make sure: if this is a brand new project, generate a home page.
 There we'll try to sign up by destructuring `signUp` from the `useAuth` hook (import that from `'src/auth'`). We'll also destructure and display `isAuthenticated` to see if it worked:
 
@@ -72,3 +113,7 @@ Clicking sign up should navigate you to `/auth` where SuperToken's default login
 <img width="463" height="696" alt="SuperTokens default UI" src="https://user-images.githubusercontent.com/30793/215893664-d367eb3d-566e-4541-a01a-5772d95cc9c7.png" />
 
 After you sign up, you should be redirected back to your Redwood app, and you should see `{"isAuthenticated":true}` on the page.
+
+## Troubleshooting
+
+If going to `http://localhost:8910/auth` results in the plain Javascript file being served instead of the expected auth page, rename the `web/src/auth.tsx` file to `web/src/authentication.tsx`, and update the imports (related to https://github.com/redwoodjs/redwood/issues/9740).

packages/auth-providers/supertokens/setup/src/templates/api/lib/supertokens.ts.template

@@ -9,10 +9,11 @@ const apiGatewayPath =
   process.env.SUPERTOKENS_API_GATEWAY_PATH || '/.redwood/functions'
 
 export const config: TypeInput = {
+  # The below options are ok here even if you're not running on top of AWS Lambda, since Redwood internally translates Fastify request/response objects to and from the AWS Lambda format.
   framework: 'awsLambda',
   isInServerlessEnv: true,
   appInfo: {
-    appName: 'SuperTokens RedwoodJS',
+    appName: process.env.SUPERTOKENS_APP_NAME,
     apiDomain,
     websiteDomain,
     apiGatewayPath,
@@ -21,6 +22,7 @@ export const config: TypeInput = {
   },
   supertokens: {
     connectionURI: process.env.SUPERTOKENS_CONNECTION_URI,
+    apiKey: process.env.SUPERTOKENS_API_KEY,
   },
   recipeList: [
     ThirdPartyEmailPassword.init({

packages/auth-providers/supertokens/setup/src/templates/web/auth.tsx.template

@@ -26,7 +26,7 @@ export const PreBuiltUI = [ThirdPartyEmailPasswordPreBuiltUI]
 isBrowser &&
   SuperTokens.init({
     appInfo: {
-      appName: 'SuperTokens RedwoodJS',
+      appName: process.env.SUPERTOKENS_APP_NAME,
       apiDomain,
       websiteDomain,
       apiGatewayPath,

packages/cli-helpers/src/auth/__tests__/fixtures/supertokensSetup/templates/api/lib/supertokens.ts.template

@@ -26,6 +26,7 @@ export const config = {
   },
   supertokens: {
     connectionURI: process.env.SUPERTOKENS_CONNECTION_URI,
+    apiKey: process.env.SUPERTOKENS_API_KEY,
   },
   recipeList: [
     ThirdPartyEmailPassword.init({