Merge branch 'main' into correct-firstrun-deploy-message

.yarnrc.yml

@@ -16,4 +16,4 @@ plugins:
 
 preferInteractive: true
 
-yarnPath: .yarn/releases/yarn-3.2.1.cjs
+yarnPath: .yarn/releases/yarn-3.2.2.cjs

docs/docs/connection-pooling.md

@@ -14,15 +14,15 @@ description: Scale your serverless functions
 
 Production Redwood apps should enable connection pooling in order to properly scale with your Serverless functions.
 
-## Connection pooling with the Prisma Data Platform
+## Prisma Data Proxy
 
-The Prisma Data Proxy provides database connection management and pooling for Redwood apps using Prisma. It supports MySQL and Postgres databases in either the U.S. or EU regions. 
+The [Prisma Data Proxy](https://www.prisma.io/docs/data-platform/data-proxy) provides database connection management and pooling for Redwood apps using Prisma. It supports MySQL and Postgres databases in either the U.S. or EU regions. 
 
-To set up a Prisma Data Proxy, sign up for the Prisma Data Platform for free. In your onboarding workflow, plug in the connection URL for your database and choose your region. This will generate a connection string for your app. Then follow the instructions in [Prisma's documentation](https://www.prisma.io/docs/concepts/data-platform/data-proxy). 
+To set up a Prisma Data Proxy, sign up for the [Prisma Data Platform](https://www.prisma.io/data-platform) for free. In your onboarding workflow, plug in the connection URL for your database and choose your region. This will generate a connection string for your app. Then follow the instructions in [Prisma's documentation](https://www.prisma.io/docs/concepts/data-platform/data-proxy). 
 
-> Note that the example uses npm. Rather than using npm, You can access the Prisma CLI using `yarn redwood prisma` inside a Redwood app.
+> Note that the example uses npm. Rather than using npm, you can access the Prisma CLI using `yarn redwood prisma` inside a Redwood app.
 
-## Prisma Pooling with PgBouncer
+## Prisma & PgBouncer
 
 PgBouncer holds a connection pool to the database and proxies incoming client connections by sitting between Prisma Client and the database. This reduces the number of processes a database has to handle at any given time. PgBouncer passes on a limited number of connections to the database and queues additional connections for delivery when space becomes available.
 

docs/docs/graphql.md

@@ -6,7 +6,131 @@ description: GraphQL is a fundamental part of Redwood
 
 GraphQL is a fundamental part of Redwood. Having said that, you can get going without knowing anything about it, and can actually get quite far without ever having to read [the docs](https://graphql.org/learn/). But to master Redwood, you'll need to have more than just a vague notion of what GraphQL is. You'll have to really grok it.
 
-The good thing is that, besides taking care of the annoying stuff for you (namely, mapping your resolvers, which gets annoying fast if you do it yourself!), there's not many gotchas with GraphQL in Redwood. GraphQL is GraphQL. The only Redwood-specific thing you should really be aware of is [resolver args](#redwoods-resolver-args).
+
+## GraphQL 101
+
+GraphQL is a query language that enhances the exchange of data between clients (in Redwood's case, a React app) and servers (a Redwood API).
+
+Unlike a REST API, a GraphQL Client performs operations that allow gathering a rich dataset in a single request.
+There's three types of GraphQL operations, but here we'll only focus on two: Queries (to read data) and Mutations (to create, update, or delete data).
+
+The following GraphQL query:
+
+```graphql
+query GetProject {
+  project(name: "GraphQL") {
+    id
+    title
+    description
+    owner {
+      id
+      username
+    }
+    tags {
+      id
+      name
+    }
+  }
+}
+```
+
+returns the following JSON response:
+
+```json
+{
+  "data": {
+    "project": {
+      "id": 1,
+      "title": "My Project",
+      "description": "Lorem ipsum...",
+      "owner": {
+        "id": 11,
+        "username": "Redwood",
+      },
+      "tags": [
+        { "id": 22, "name": "graphql" }
+      ]
+    }
+  },
+  "errors": null
+}
+```
+
+Notice that the response's structure mirrors the query's. In this way, GraphQL makes fetching data descriptive and predictable.
+
+Again, unlike a REST API, a GraphQL API is built on a schema that specifies exactly which queries and mutations can be performed.
+For the `GetProject` query above, here's the schema backing it:
+
+```graphql
+type Project {
+  id: ID!
+  title: String
+  description: String
+  owner: User!
+  tags: [Tag]
+}
+
+# ... User and Tag type definitions
+
+type Query {
+  project(name: String!): Project
+}
+```
+
+:::info
+
+More information on GraphQL types can be found in the [official GraphQL documentation](https://graphql.org/learn/schema/).
+
+:::
+
+Finally, the GraphQL schema is associated with a resolvers map that helps resolve each requested field. For example, here's what the resolver for the owner field on the Project type may look like:
+
+```ts
+export const Project = {
+  owner: (args, { root, context, info }) => {
+    return db.project.findUnique({ where: { id: root.id } }).user()
+  },
+  // ...
+}
+```
+
+:::info
+
+You can read more about resolvers in the dedicated [Understanding Default Resolvers](#understanding-default-resolvers) section below.
+
+:::
+
+To summarize, when a GraphQL query reaches a GraphQL API, here's what happens:
+
+```
++--------------------+                  +--------------------+
+|                    | 1.send operation |                    |
+|                    |                  |   GraphQL Server   |
+|   GraphQL Client   +----------------->|    |               |
+|                    |                  |    |  2.resolve    |
+|                    |                  |    |     data      |
++--------------------+                  |    v               |
+          ^                             | +----------------+ |
+          |                             | |                | |
+          |                             | |    Resolvers   | |
+          |                             | |                | |
+          |                             | +--------+-------+ |
+          |  3. respond JSON with data  |          |         |
+          +-----------------------------+ <--------+         |
+                                        |                    |
+                                        +--------------------+
+```
+
+In contrast to most GraphQL implementations, Redwood provides a "deconstructed" way of creating a GraphQL API:
+
+- You define your SDLs (schema) in `*.sdl.js` files, which define what queries and mutations are available, and what fields can be returned
+- For each query or mutation, you write a service function with the same name. This is the resolver
+- Redwood then takes all your SDLs and Services (resolvers), combines them into a GraphQL server, and expose it as an endpoint
+
+## Redwood and GraphQL
+
+Besides taking care of the annoying stuff for you (namely, mapping your resolvers, which gets annoying fast if you do it yourself!), there's not many gotchas with GraphQL in Redwood.
+The only Redwood-specific thing you should really be aware of is [resolver args](#redwoods-resolver-args).
 
 Since there's two parts to GraphQL in Redwood, the client and the server, we've divided this doc up that way.
 
@@ -1087,3 +1211,10 @@ This might be one of our most frequently asked questions of all time. Here's [To
 
 <!-- TODO -->
 <!-- This https://community.redwoodjs.com/t/how-to-add-resolvetype-resolver-for-interfaces/432/7 -->
+
+## Futher Reading
+
+Eager to learn more about GraphQL? Check out some of the resources below:
+- [GraphQL.wtf](https://graphql.wtf) covers most aspects of GraphQL and publishes one short video a week
+- The official GraphQL Yoga (the GraphQL server powering Redwood) [tutorial](https://www.graphql-yoga.com/tutorial/basic/00-introduction) is the best place to get your hands on GraphQL basics
+- And of course, [the official GraphQL docs](https://graphql.org/learn/) are great place to do a deep dive into exactly how GraphQL works

docs/docs/local-postgres-setup.md

@@ -84,7 +84,7 @@ If you'd rather not follow any of the advice here and create another Postgres us
 Tell Prisma to use a Postgres database instead of SQLite by updating the `provider` attribute in your
 `schema.prisma` file:
 
-```graphql title="prisma/schema.prisma"
+```graphql title="api/db/schema.prisma"
 datasource db {
   provider = "postgresql"
   url = env("DATABASE_URL")

docs/package.json

@@ -24,17 +24,17 @@
     ]
   },
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.21",
-    "@docusaurus/plugin-content-docs": "2.0.0-beta.21",
-    "@docusaurus/preset-classic": "2.0.0-beta.21",
+    "@docusaurus/core": "2.0.0-rc.1",
+    "@docusaurus/plugin-content-docs": "2.0.0-rc.1",
+    "@docusaurus/preset-classic": "2.0.0-rc.1",
     "@mdx-js/react": "1.6.22",
     "clsx": "1.2.1",
     "react": "17.0.2",
     "react-dom": "17.0.2",
     "react-player": "2.10.1"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.0.0-beta.21",
+    "@docusaurus/module-type-aliases": "2.0.0-rc.1",
     "@tsconfig/docusaurus": "1.0.6",
     "typescript": "4.7.4"
   }

docs/src/components/FileExtSwitcher.tsx

@@ -1,6 +1,6 @@
 import * as React from 'react'
 
-import { useTabGroupChoice } from '@docusaurus/theme-common'
+import { useTabGroupChoice } from '@docusaurus/theme-common/internal'
 
 interface Props {
   path: string

docs/src/components/ShowForTs.tsx

@@ -1,6 +1,6 @@
 import * as React from 'react'
 
-import { useTabGroupChoice } from '@docusaurus/theme-common'
+import { useTabGroupChoice } from '@docusaurus/theme-common/internal'
 import MDXContent from '@theme/MDXContent'
 
 interface Props {