chore(docs): prisma "migration" guide

prisma-labs · Jun 19, 2020 · bac0163 · bac0163
1 parent 32d4016
commit bac0163
Show file tree

Hide file tree

Showing 10 changed files with 169 additions and 35 deletions.
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
@@ -2,7 +2,11 @@
 
 - [Welcome To Nexus](README)
 - [Tutorial](tutorial/introduction)
-- [Migrate from Nexus Schema](getting-started/migrate-from-nexus-schema)
+
+- Migration Guides
+
+- [Prisma Users](migration-guides/prisma-users)
+- [Nexus Schema Users](getting-started/migrate-from-nexus-schema)
 
 - Guides
 

diff --git a/docs/components/schema/api/_sidebar.md b/docs/components/schema/api/_sidebar.md
@@ -4,50 +4,55 @@
 - [Tutorial](tutorial/introduction)
 - [Migrate from Nexus Schema](getting-started/migrate-from-nexus-schema)
 
-- Guides
+- Migration Guides
 
-- [Concepts](guides/concepts)
-- [Schema](guides/schema)
-- [Server](guides/server)
-- [Logger](guides/logger)
-- [Testing](guides/testing)
-- [Project Layout](guides/project-layout)
-- [Error Handling](guides/error-handling)
-- [Plugins](guides/plugins)
-- [Recipes](references/recipes)
-- [Writing Plugins](guides/writing-plugins)
-- [CLI](guides/cli)
+- [Prisma Users](migration-guides/prisma-users)
+- [Nexus Schema Users](getting-started/migrate-from-nexus-schema)
 
-- Plugins
+* Guides
 
-- [`prisma`](plugins/prisma)
-- [`jwt-auth`](https://github.com/Camji55/nexus-plugin-jwt-auth)
-- [`shield`](https://github.com/lvauvillier/nexus-plugin-shield)
+* [Concepts](guides/concepts)
+* [Schema](guides/schema)
+* [Server](guides/server)
+* [Logger](guides/logger)
+* [Testing](guides/testing)
+* [Project Layout](guides/project-layout)
+* [Error Handling](guides/error-handling)
+* [Plugins](guides/plugins)
+* [Recipes](references/recipes)
+* [Writing Plugins](guides/writing-plugins)
+* [CLI](guides/cli)
 
-* API
+* Plugins
 
-* [`nexus`](api/modules/main)
+* [`prisma`](plugins/prisma)
+* [`jwt-auth`](https://github.com/Camji55/nexus-plugin-jwt-auth)
+* [`shield`](https://github.com/lvauvillier/nexus-plugin-shield)
+
+- API
+
+- [`nexus`](api/modules/main)
 
   - [`schema`](api/modules/main/exports/schema)
   - [`log`](api/modules/main/exports/logger)
   - [`server`](api/modules/main/exports/server)
   - [`settings`](api/modules/main/exports/settings)
   - [`use`](api/modules/main/exports/use)
 
-- [`nexus/testing`](api/modules/testing)
+* [`nexus/testing`](api/modules/testing)
 
-- [`nexus/plugin`](api/modules/plugin)
+* [`nexus/plugin`](api/modules/plugin)
 
-- Meta
+* Meta
 
-- [Roadmap ⤤](https://github.com/orgs/graphql-nexus/projects/1)
-- [Changelog](changelog)
-- [Spec Sheet](meta/spec-sheet)
-- [Architecture](architecture)
+* [Roadmap ⤤](https://github.com/orgs/graphql-nexus/projects/1)
+* [Changelog](changelog)
+* [Spec Sheet](meta/spec-sheet)
+* [Architecture](architecture)
 
-* Components Standalone
+- Components Standalone
 
-* [`@nexus/schema`](components/schema/about)
+- [`@nexus/schema`](components/schema/about)
 
   - [API](components/schema/api/index.md)
     - [objectType](components/schema/api/copy/api-objectType)
@@ -70,7 +75,7 @@
     - [Nullability Guard](components/schema/plugins/nullability-guard)
     - [Prisma](components/schema/plugins/prisma)
 
-- [`@nexus/logger`](components/logger/about)
+* [`@nexus/logger`](components/logger/about)
   - [API](components/logger/api)
   - [Plugins](components/logger/plugins)
   - [Plugins API](components/logger/plugins-api)
diff --git a/docs/getting-started/migrate-from-nexus-schema.md b/docs/getting-started/migrate-from-nexus-schema.md
@@ -1,3 +1,5 @@
+# Hello Nexus Schama User!
+
 Prior to version `0.20`, the `nexus` package comprised only the schema definition and code generation components of the Nexus framework. These components are now known as [`@nexus/schema`](components/schema/about), and while they're included as part of the Nexus framework, they remain available as a [standalone package](https://github.com/graphql-nexus/schema). (You can read more about the transition of Nexus from a schema library to a full-fledged framework in the [announcement in this GitHub issue](https://github.com/prisma-labs/nexus/issues/373).)
 
 For users of `nexus` version `0.12` and below, you can either migrate to the `@nexus/schema` package, or to the new Nexus framework. The former is more straightforward, but the latter may significantly simplify your configuration and give you the benefit of baked-in sensible defaults and best practices (especially if you were previously using `graphql-yoga` or `express-graphql`). This guide will cover both scenarios.

diff --git a/docs/migration-guides/prisma-users.md b/docs/migration-guides/prisma-users.md
@@ -0,0 +1,56 @@
+# Hello Prisma user!
+
+Nexus is a feature rich GraphQL Framework. One of its hallmark features is how it helps you achieve a very high degree of type-safety as you implement your API. If you are a long-time Prisma user you can see it as a spiritual successor to the rich GraphQL experiences that Prisma 1 and even Graphcool offered. Nexus is still young, but growing fast.
+
+If you haven't already, you should read the [Welcome to Nexus](/README) introduction.
+
+## Vanilla Integration {docsify-ignore}
+
+As a Prisma user you can easily integrate Prisma into Nexus yourself, take a look:
+
+```ts
+import { PrismaClient } from '@prisma/client'
+import { schema } from 'nexus'
+
+const db = new PrismaClient()
+
+schema.addToContext(req => ({ db })) // exopse Prisma Client in all resolvers
+
+schema.queryType({
+  definition(t) {
+    t.field('...', {
+      type: '...'
+      resolve(_, __, ctx) {
+        ctx.db // <- Prisma Client
+      }
+    })
+  }
+})
+```
+
+Run `nexus dev` in one shell, and your usual `prisma` workflow in another. ✅
+
+## Plugin! {docsify-ignore}
+
+This is fine, but there's something better. The Nexus Prisma _plugin_ (`nexus-plugin-prisma`). It levels up your experience, including:
+
+- Bundling the Prisma deps
+- Running your Prisma generators
+- Integrating your Prisma Client automatically, including into Nexus' test system
+- Declarative APIs for projecting types from your Prisma schema onto your GraphQL Schema
+- Declarative APIs for creating mutations and queries (including automatically implemented resolvers!)
+
+If you haven't already, you should read the [Welcome to Nexus Prisma](/plugins/prisma) introduction.
+
+## Learning Path {docsify-ignore}
+
+1. Read [Welcome to Nexus](/README)
+2. Do [The Nexus Tutorial](/tutorial/introduction)
+3. If using the Prisma plugin (you should!) read [Welcome to Nexus Prisma](/plugins/prisma)
+
+TL;DR
+
+```
+npm add nexus nexus-plugin-prisma
+npm run nexus
+```
diff --git a/docs/tutorial/_sidebar.md b/docs/tutorial/_sidebar.md
@@ -12,6 +12,11 @@
   - [7. Authentication](tutorial/chapter-7-authentication)
 - [Migrate from Nexus Schema](getting-started/migrate-from-nexus-schema)
 
+- Migration Guides
+
+- [Prisma Users](migration-guides/prisma-users)
+- [Nexus Schema Users](getting-started/migrate-from-nexus-schema)
+
 - Guides
 
 - [Concepts](guides/concepts)

diff --git a/website/content/01-getting-started/01-welcome-to-nexus.mdx b/website/content/01-getting-started/01-welcome-to-nexus.mdx
@@ -1,6 +1,5 @@
 ---
-title: 'Welcome to Nexus'
-metaTitle: 'Welcome to Nexus'
+title: Welcome to Nexus
 ---
 
 ## Welcome to Nexus

diff --git a/website/content/01-getting-started/index.mdx b/website/content/01-getting-started/index.mdx
@@ -1,5 +1,3 @@
 ---
-title: 'Getting started'
-metaTitle: 'Getting started'
-metaDescription: 'Getting started'
+title: Getting started
 ---
diff --git a/website/content/01-migration-guides/01-prisma-users.mdx b/website/content/01-migration-guides/01-prisma-users.mdx
@@ -0,0 +1,60 @@
+---
+title: Prisma Users
+---
+
+# Hello Prisma user!
+
+Nexus is a feature rich GraphQL Framework. One of its hallmark features is how it helps you achieve a very high degree of type-safety as you implement your API. If you are a long-time Prisma user you can see it as a spiritual successor to the rich GraphQL experiences that Prisma 1 and even Graphcool offered. Nexus is still young, but growing fast.
+
+If you haven't already, you should read the [Welcome to Nexus](/README) introduction.
+
+## Vanilla Integration
+
+As a Prisma user you can easily integrate Prisma into Nexus yourself, take a look:
+
+```ts
+import { PrismaClient } from '@prisma/client'
+import { schema } from 'nexus'
+
+const db = new PrismaClient()
+
+schema.addToContext(req => ({ db })) // exopse Prisma Client to all resolvers
+
+schema.queryType({
+  definition(t) {
+    t.field('...', {
+      type: '...'
+      resolve(_, __, ctx) {
+        ctx.db // <- Prisma Client
+      }
+    })
+  }
+})
+```
+
+Run `nexus dev` in one shell, and your usual `prisma` workflow in another. ✅
+
+## Plugin!
+
+This is fine, but there's something better. The Nexus Prisma _plugin_ (`nexus-plugin-prisma`). It levels up your experience, including:
+
+- Bundling the Prisma deps
+- Running your Prisma generators
+- Integrating your Prisma Client automatically, including into Nexus' test system
+- Declarative APIs for projecting types from your Prisma schema onto your GraphQL Schema
+- Declarative APIs for creating mutations and queries (including automatically implemented resolvers!)
+
+If you haven't already, you should read the [Welcome to Nexus Prisma](/plugins/prisma) introduction.
+
+## Learning Path
+
+1. Read [Welcome to Nexus](/README)
+2. Do [The Nexus Tutorial](/tutorial/introduction)
+3. If using the Prisma plugin (you should!) read [Welcome to Nexus Prisma](/plugins/prisma)
+
+TL;DR
+
+```
+npm add nexus nexus-plugin-prisma
+npm run nexus
+```
diff --git a/...content/01-getting-started/04-migrate.mdx → ...igration-guides/02-nexus-schema-users.mdx b/...content/01-getting-started/04-migrate.mdx → ...igration-guides/02-nexus-schema-users.mdx
@@ -1,11 +1,13 @@
 ---
-title: Migrate from Nexus Schema
+title: Nexus Schema Users
 # TODO if these frontmatter items are removed the site crashes
 duration: ''
 experimental: false
 staticLink: false
 ---
 
+# Hello Nexus Schama User!
+
 ## Migrate from Nexus Schema
 
 Prior to version `0.20`, the `nexus` package comprised only the schema definition and code generation components of the Nexus framework. These components are now known as [`@nexus/schema`](components/schema/about), and while they're included as part of the Nexus framework, they remain available as a [standalone package](https://github.com/graphql-nexus/schema). (You can read more about the transition of Nexus from a schema library to a full-fledged framework in the [announcement in this GitHub issue](https://github.com/prisma-labs/nexus/issues/373).)

diff --git a/website/content/01-migration-guides/index.mdx b/website/content/01-migration-guides/index.mdx
@@ -0,0 +1,3 @@
+---
+title: Migration guides
+---