` tags wont be shown in TOC yet.
-
-```js
-sdd
-```
-
-
-
-
-```ts
-const posts = await prisma.user.findOne({
- where: {
- id: 2,
- },
- include: {
- post: true,
- },
-})
-```
-
-
-
-
-```ts
-const posts = await prisma.user.findOne({
- where: {
- id: 2,
- },
- include: {
- post: true,
- },
-})
-```
-
-
-
diff --git a/website/content/01-getting-started/03-tutorial/01-chapter-0-introduction.mdx b/website/content/01-getting-started/03-tutorial/01-chapter-0-introduction.mdx
index ea035c14d..07cc75c09 100644
--- a/website/content/01-getting-started/03-tutorial/01-chapter-0-introduction.mdx
+++ b/website/content/01-getting-started/03-tutorial/01-chapter-0-introduction.mdx
@@ -8,7 +8,7 @@ Welcome to _the_ Nexus tutorial! If you're new to Nexus and want a guided learni
This tutorial is still under construction. Some chapters will continue to be refined and more added. If you're looking for our old tutorial content, it can still be found [here](/getting-started/tutorial).
-## Assumed Tools
+## Assumed tools
Throughout this journey, we'll be making a few minor assumptions about your toolchain to keep the content flowing:
@@ -22,34 +22,34 @@ If you're using another set of tools, like Yarn on Windows with Sublime Text, th
There's a few conventions used throughout this tutorial that you should know about.
-- **Annotated Code Blocks**
+### Annotated code blocks
- Most Code Blocks are explained with annotations. Take the following for example. Immediately following the codeblock are numbered points. Each corresponds to a line annotated with that number in the code block.
+Most Code Blocks are explained with annotations. Take the following for example. Immediately following the codeblock are numbered points. Each corresponds to a line annotated with that number in the code block.
-
- ```ts
- const a = 1 as const // 1
+
+```ts
+const a = 1 as const // 1
- interface A {} // 2
- interface A {} // 2
+interface A {} // 2
+interface A {} // 2
- const b: any = 1 // 3
- ```
+const b: any = 1 // 3
+```
- 1. Use `as const` to make TS take the narrowest inference. Here `1` vs `number`.
- 2. Same-named interfaces will merge into one.
- 3. Use `any` to effectively disable type-checking
+1. Use `as const` to make TS take the narrowest inference. Here `1` vs `number`.
+2. Same-named interfaces will merge into one.
+3. Use `any` to effectively disable type-checking
-- **Auxiliary Content**
+### Auxiliary content
- Sometimes content that isn't core to the current flow but related to it will be mentioned. That looks like so:
+Sometimes content that isn't core to the current flow but related to it will be mentioned. That looks like so:
- > Hello there, have a nice day!
+> Hello there, have a nice day!
-## Copy-Pasting
+### Copy-pasting
As you progress you'll be writing code, of course. Often you'll have the chance to copy and paste our code, but we strongly suggest if you're just starting out to **write the code yourself**. This will expose you to _experience_ of writing a Nexus app. Things like autocompletion and letting static safety guide your implementations, e.g. inside a GraphQL resolver. Also if you're new to TypeScript getting used to encountering, understanding, and fixing static type errors is essential practice. That said at no time should you feel _frustrated_. If things just aren't working, copy-paste our work as needed. Then, once things _are_ working, taking a moment muck around, break things, fix them again, etc. is almost always time well spent.
-## Wrapping Up
+## Wrapping up
-Thanks for checking out Nexus, we hope you're as excited to learn about it as we are to show it to you! :rocket:
+Thanks for checking out Nexus, we hope you're as excited to learn about it as we are to show it to you! π
diff --git a/website/content/01-getting-started/03-tutorial/02-chapter-1-setup-and-first-query.mdx b/website/content/01-getting-started/03-tutorial/02-chapter-1-setup-and-first-query.mdx
index 08e152ec3..b32b64b1c 100644
--- a/website/content/01-getting-started/03-tutorial/02-chapter-1-setup-and-first-query.mdx
+++ b/website/content/01-getting-started/03-tutorial/02-chapter-1-setup-and-first-query.mdx
@@ -15,7 +15,7 @@ In this first chapter we're just going to get the bare minimum of a Nexus projec
Start by creating your project directory, initializing your `package.json`, and adding the `nexus` dependency.
-```bash
+```bash-symbol
mkdir nexus-tutorial && cd nexus-tutorial
npm init -y
npm add nexus
@@ -23,7 +23,7 @@ npm add nexus
Nexus comes out of the box with a CLI. You'll use it often while working on your app. While you can access the CLI of your local nexus via `yarn` or npm scripts or `npx` but there's an even easier way. Install `nexus` globally. Then you can access the CLI from anywhere. Nexus is smart enough to delegate all invocations to the _local_ nexus. This is the idiomatic way to work with Nexus, but you aren't forced to do this.
-```markdown
+```bash-symbol
npm add --global nexus
```
@@ -43,37 +43,37 @@ Despite having the global Nexus CLI, using package scripts can be a handy way of
}
```
-## Conventional Entrypoint
+## Conventional entrypoint
We'll now create our first module at `api/app.ts`:
-```bash
+```bash-symbol
mkdir api && touch api/app.ts
```
The directory name `api` is arbitrary but the module name `app` has special meaning. Nexus will find `app.ts` wherever you put it within your project and treat it as your entrypoint. Furthermore, every module that imports `nexus` will be automatically included into the final build by Nexus. This makes growing and refactoring your project easy as you are freed from managing import/export tedium. You might be wondering how import order is managed. The answer is that Nexus' APIs are declarative and so designed to be order independent.
-## Contextual Feedback
+## Contextual feedback
Ok, with our entrypoint setup, let's boot up dev mode and see what happens.
-```bash
+```bash-symbol
nexus dev
```
Woops? You should be seeing a warning from Nexus:
-```bash
+```bash-symbol
β² nexus:schema Your GraphQL schema is empty. [...]
```
All good, you indeed haven't added any types to your GraphQL schema yet so Nexus is right here. This is the first example of Nexus' rich development mode contextual feedback. One of the goals of Nexus is to never leave you in a confused disoriented state. If Nexus can give you in inline feedback it should. Add rich jsDoc and precise TypeScript types into the mix, and ideally you can largely avoid getting lost and _needing_ to consult the Nexus website, community, so on.
-## Try It Out
+## Try it out
Aside from the warning, you should also see a message indicating that your server is running, and where.
-```bash
+```bash-symbol
β nexus:server listening -- url: 'http://localhost:4000/'
```
@@ -85,10 +85,14 @@ This is a graphical user interface for interacting with GraphQL APIs. If you pre
Take a look at the right-hand side SCHEMA tab. There you'll see a default schema that Nexus has provided for you. This, along with the warning you say before, will go away once you begin your own schema.
-## Wrapping Up
+## Wrapping up
That's it! In the next chapter you'll begin working on your app's schema.
-
-
-[β³](/tutorial/chapter-2-writing-your-first-schema)
+
+ Next →
+
diff --git a/website/content/01-getting-started/03-tutorial/03-chapter-2-writing-your-first-schema.mdx b/website/content/01-getting-started/03-tutorial/03-chapter-2-writing-your-first-schema.mdx
index c3994b65c..6f585ee1e 100644
--- a/website/content/01-getting-started/03-tutorial/03-chapter-2-writing-your-first-schema.mdx
+++ b/website/content/01-getting-started/03-tutorial/03-chapter-2-writing-your-first-schema.mdx
@@ -11,20 +11,16 @@ In this chapter you're going to write your first schema. You'll learn about:
- GraphQL SDL file generation
- Enhanced type safety & autocompletion
-
-
-## What About That Server?
+## What about that server?
In the last chapter you probably noticed the minimal setup required to get up and running. In fact, you might even be confused and wondering:
-"Hey, all I have is an empty `app.ts` file, how can my server even be running?"
+> "Hey, all I have is an empty `app.ts` file, how can my server even be running?"
Well, Nexus comes with a server out of the box. There's no need for you to start or stop the server or otherwise think about it beyond your domain logic. Nexus wants you to focus on what makes your GraphQL API unique.
If your lock-in fears are tingling, know that **you still have _full_ access** to the underlying server instance. So if you need to add custom middlewares, routes, and so on, you can. It happens that currently it is an `express` instance but this area of Nexus will evolve ([#295](https://github.com/graphql-nexus/nexus/issues/295)).
-
-
## Reflection?
Before we get going we need a moment to introduce an important part of the Nexus development workflow. Nexus has an unconventional concept called "Reflection". It refers to the fact that, when `nexus dev` or `nexus build` is running, not only is your application code being run, but **information is being gathered and artifacts are being derived**. Some of Nexus' uses for reflection include:
@@ -39,19 +35,17 @@ Architecturally there's a lot more to say about reflection but for now, from a u
> There are plans to run Nexus Reflection as a separate process integrated into your IDE. You can learn more about and track the feature here ([#949](https://github.com/graphql-nexus/nexus/issues/949))
-
-
-## Model The Domain
+## Model the domain
Let's get started with our blog schema by modeling some key entities in the domain. We'll begin with the concept of a `Post`. A post will represent a page in your blog. When not published, we'll call it a _draft_.
Your modeling work is going to start on the API layer as opposed to the database layer. This API-first approach can be a good way to collaborate with frontend teams, getting their input in shaping the data early.
-> A note about terminology. We will be talking about the Post Object not Post Model. The difference is that at the API layer we have objects but at the database layer we have models. The name difference helps us talk about these different layers without confusion. It is also how GraphQL (API layer) and Prisma (database layer, discussed later) respectively refer to these things.
+> A note about terminology. We will be talking about the _Post Object_, not the _Post Model_. The difference is that at the API layer we have objects but at the database layer we have models. The name difference helps us talk about these different layers without confusion. It is also how GraphQL (API layer) and Prisma (database layer, discussed later) respectively refer to these things.
Create a new module for your Post object at `api/graphql/Post.ts`. We _could_ write our whole schema within say `api/app.ts` or `api/graphql.ts`, but modularizing your GraphQL type definitions can help scale your codebase. Neither approach is inherently wrong though, so do as you see you fit. For this tutorial we'll use the modular style.
-```bash
+```bash-symbol
mkdir api/graphql && touch api/graphql/Post.ts
```
@@ -98,9 +92,7 @@ You are free to disable this file (settings discussed later) but its existence h
For the remainder of this tutorial we'll be keeping SDL to the right of Nexus code blocks.
-
-
-## Your First Home Grown Query
+## Your first home-grown query
Your `Post` object is in place now but there's still no way for clients to read that data. Let's change that. You'll use the special `Query` object to expose your Post object.
@@ -228,4 +220,6 @@ Congratulations! You've successfully got your first GraphQL schema up and runnin
-[β³](/tutorial/chapter-3-adding-mutations-to-your-api)
+
+ Next →
+
\ No newline at end of file
diff --git a/website/content/01-getting-started/03-tutorial/04-chapter-3-adding-mutations-to-your-api.mdx b/website/content/01-getting-started/03-tutorial/04-chapter-3-adding-mutations-to-your-api.mdx
index c469fe882..41b7d12cb 100644
--- a/website/content/01-getting-started/03-tutorial/04-chapter-3-adding-mutations-to-your-api.mdx
+++ b/website/content/01-getting-started/03-tutorial/04-chapter-3-adding-mutations-to-your-api.mdx
@@ -13,7 +13,7 @@ In this chapter you're going to add some write capability to your API. You'll le
To keep our learning gradual we'll stick to in-memory data for now but rest assured a proper databases is coming in an upcoming chapter.
-## Wire Up The Context
+## Wire up the context
The first thing we'll do is setup an in-memory database and expose it to our resolvers using the _GraphQL context_.
@@ -21,7 +21,7 @@ The GraphQL Context is a plain JavaScript object shared across all resolvers. Ne
So go ahead and create the database.
-```bash
+```bash-symbol
touch api/db.ts
```
@@ -61,7 +61,7 @@ module global {
> **Note** For those familiar with GraphQL, you might be grimacing that weβre attaching static things to the context, instead of using export/import.
> This is a matter of convenience. Feel free to take a purer approach in your apps if you want.
-## Use The Context
+## Use the context
Now let's use this data to re-implement the `Query.drafts` resolver from the previous chapter.
@@ -85,7 +85,7 @@ schema.queryType({
**Did you notice?** Still no TypeScript type annotations required from you yet everything is still totally type safe. Prove it to yourself by hovering over the `ctx.db.posts` property and witness the correct type information it gives you. This is the type propagation we just mentioned in action. π
-## Your First Mutation
+## Your first mutation
Alright, now that we know how to wire things into our context, let's implement our first mutation. We're going to make it possible for your API clients to create new drafts.
@@ -96,8 +96,6 @@ This mutation will need a name. Rather than simply call it `createPost` we'll us
As before we will take the collocation approach.
-
-
We need to get the client's input data to complete our resolver. This brings us to a new concept, GraphQL arguments. Every field in GraphQL may accept them. Effectively you can think of each field in GraphQL like a function, accepting some input, doing something, and returning an output. Most of the time "doing something" is a matter of some read-like operation but with `Mutation` fields the "doing something" usually entails a process with side-effects (e.g. writing to the database).
Let's revise our implementation with GraphQL arguments.
-
-
1. Add an `args` property to the field definition to define its args. Keys are arg names and values are type specifications.
2. Use the Nexus helpers for defining an arg type. There is one such helper for every GraphQL scalar such as `schema.intArg` and `schema.booleanArg`. If you want to reference a type like some InputObject then use `schema.arg({ type: "..." })`.
3. In our resolver, access the args we specified above and pass them through to our custom logic. If you hover over the `args` parameter you'll see that Nexus has properly typed them including the fact that they cannot be undefined.
-## Model The Domain pt 2
+## Model the domain: Part 2
Before we wrap this chapter let's flush out our schema a bit more. We'll add a `publish` mutation to transform a draft into an actual published post, then we'll let API clients read the the published posts.
-
-
```ts
// api/graphql/Post.ts
@@ -193,7 +183,7 @@ schema.extendType({
draftId: schema.intArg({ required: true }),
},
resolve(_root, args, ctx) {
- let draftToPublish = ctx.db.posts.find((p) => p.id === args.draftId)
+ let draftToPublish = ctx.db.posts.find(p => p.id === args.draftId)
if (!draftToPublish) {
throw new Error('Could not find draft with id ' + args.draftId)
@@ -215,10 +205,6 @@ type Mutation {
}
```
-
-
-## Try It Out
+## Try it out
Great, now head on over to the GraphQL Playground and run this query (left). If everything went well, you should see a response like this (right):
-
-
-## Wrapping Up
+## Wrapping up
Congratulations! You can now read and write to your API.
But, so far you've been validating your work by manually interacting with the Playground. That may be reasonable at first (depending on your relationship to TDD) but it will not scale. At some point you are going to want automated testing. Nexus takes testing seriously and in the next chapter we'll show you how. See you there!
-
-
-[β³](/tutorial/chapter-4-testing-your-api)
+
+ Next →
+
diff --git a/website/content/01-getting-started/03-tutorial/05-chapter-4-testing-your-api.mdx b/website/content/01-getting-started/03-tutorial/05-chapter-4-testing-your-api.mdx
index 72c2c1a34..f2403592d 100644
--- a/website/content/01-getting-started/03-tutorial/05-chapter-4-testing-your-api.mdx
+++ b/website/content/01-getting-started/03-tutorial/05-chapter-4-testing-your-api.mdx
@@ -10,7 +10,7 @@ So far you've been validating your work by manual interacting with the Playgroun
- Setting up a test environment
- The `nexus/testing` module
-## It's At the System Level
+## It's at the system level
There are multiple ways you can test a GraphQL API. One way is to extract resolvers into isolated functions and then unit test them. Of course these are rarely pure functions so those unit tests either become partial integration tests or mocks are introduced to try and retain the unit level of testing. Unit testing resolvers can work well, but here are some reasons why and where it might not;
@@ -20,13 +20,13 @@ There are multiple ways you can test a GraphQL API. One way is to extract resolv
Testing non-trivial resolvers in isolation is likely to be a good investment in most cases but its up to you as a developer. What Nexus provides help with is not at this level, but higher up in the [testing pyramid](https://codingjourneyman.com/tag/uncle-bob/page/2/), at the system level. System testing means tests that will run operations against your API just like a real client would. This chapter will focus on that. Let's dive-in!
-## Setting up Your Test Environment
+## Setting up your test environment
During this tutorial, you'll use the [Jest testing framework](https://jestjs.io/) to test your API. This is not mandatory but we do recommend it. Still, in general, outside this tutorial, if you prefer another testing framework, feel free to use it.
First, install `jest` and accompanying tools
-```bash
+```bash-symbol
npm add --save-dev jest @types/jest ts-jest
```
@@ -44,13 +44,11 @@ Then, configure jest and npm scripts in your `package.json`
Finally, create a `tests` folder at the root of your project and a `Post.test.ts` file inside it
-```bash
+```bash-symbol
mkdir tests && touch tests/Post.test.ts
```
-You're set.
-
-## Testing The Publish Mutation
+## Testing the `publish` mutation
Nexus comes with a special testing module that you can import from `nexus/testing`.
@@ -60,7 +58,7 @@ Before jumping into your first test we will show you a pattern that more tightly
Create a `tests/__helpers.ts` module with the following contents.
-```bash
+```bash-windows
touch tests/__helpers.ts
```
@@ -169,11 +167,11 @@ it('ensures that a draft can be created and published', async () => {
2. This is the mutation from the end of last chapter.
3. The result will be snapshoted inline allowing us to see the input and output collocated!
-## Try It Out
+## Try it out
Now run your tests and let's see the snapshots come to life! It should look similar to this:
-```bash
+```bash-symbol
npm run test
```
@@ -211,10 +209,14 @@ Published draft snapshot
Awesome, beautiful workflow isn't it? If inline snapshots get too unwieldy you can switch to regular snapshots and install [a VSCode plugin](https://marketplace.visualstudio.com/items?itemName=asvetliakov.snapshot-tools) that will display the snapshots upon hovering over the `toMatchSnapshot` method name. While not quite as fluid as seeing inline snapshots throughout your test module, it may work better for you.
-## Wrapping Up
+## Wrapping up
You've just made a big step in the maintainability of your API. Here we showed how to test your `createDraft` and `publish` mutation, proving that a draft can be properly created and published. However you did _not_ test if the draft was correctly persisted into your database. That piece will come soon! But first we need a real database in the first place. That's what the next chapter is all about!
-
-
-[β³](/tutorial/chapter-5-persisting-data-via-prisma)
+
+ Next →
+
diff --git a/website/content/01-getting-started/03-tutorial/06-chapter-5-persisting-data-via-prisma.mdx b/website/content/01-getting-started/03-tutorial/06-chapter-5-persisting-data-via-prisma.mdx
index 871600100..7e54dff3a 100644
--- a/website/content/01-getting-started/03-tutorial/06-chapter-5-persisting-data-via-prisma.mdx
+++ b/website/content/01-getting-started/03-tutorial/06-chapter-5-persisting-data-via-prisma.mdx
@@ -16,7 +16,7 @@ Postgres is a well known open-source relational database. Prisma is a new way of
Its important to understand that Nexus does not _require_ these technology choices and _could_ actually be used with any database and abstractions over them (raw SQL, query builder, ORM..). However, Nexus is built by a team at Prisma (the company) and unsurprisingly there is great integration between its tools and Nexus.
-## Prisma?
+## What is Prisma?
So, what _is_ Prisma? It is an open source database toolkit that consists of the following parts:
@@ -42,7 +42,7 @@ Another convention that they usually follow is that they use the default export
Plugins are easy to use:
-```bash
+```bash-symbol
npm add nexus-plugin-foo
```
@@ -70,11 +70,11 @@ Now that you know a bit about Prisma and Nexus plugins, let's get going! Do the
like so:
-```bash
+```bash-symbol
npm add nexus-plugin-prisma
```
-> Note: Like we mentioned in Chapter 1, the simplicity of the dependency story here is no accident. Nexus Prisma plugin bundles deps like `@prisma/client` for you. If you're curious about Nexus' philosophy on dependency management [we've written about it here](/meta/architecture#dependency-philosophy).
+> **Note**: Like we mentioned in Chapter 1, the simplicity of the dependency story here is no accident. Nexus Prisma plugin bundles deps like `@prisma/client` for you. If you're curious about Nexus' philosophy on dependency management [we've written about it here](/meta/architecture#dependency-philosophy).
```ts
// api/app.ts
@@ -85,13 +85,13 @@ import { prisma } from 'nexus-plugin-prisma'
use(prisma())
```
-```bash
+```bash-symbol
mkdir prisma
touch prisma/schema.prisma
touch prisma/.env
```
-```groovy
+```prisma
// prisma/schema.prisma
datasource postgres {
@@ -107,8 +107,8 @@ DATABASE_URL=""
Almost done, but we still need to setup a Postgres database for our app to connect to. There are a ton of ways to do this so we're just going to show the most straight forward cross-platform way we know how. First, make sure you have [docker installed](https://docs.docker.com/get-docker/). Then, simply run this command:
-```
-β― docker run --detach --publish 5432:5432 -e POSTGRES_PASSWORD=postgres --name postgres postgres:10.12
+```bash-symbol
+docker run --detach --publish 5432:5432 -e POSTGRES_PASSWORD=postgres --name postgres postgres:10.12
```
That's it. You now have a Postgres server running. You can connect to it at a URL like:
@@ -145,13 +145,13 @@ With our database schema specified, we're now ready to proceed to our first data
Generate our migration files...
-```bash
+```bash-symbol
npx prisma migrate save --experimental
```
Then, apply the migration...
-```bash
+```bash-symbol
npx prisma migrate up --experimental
```
@@ -159,7 +159,7 @@ npx prisma migrate up --experimental
Now let's finally ditch our in-memory data! Let's start by removing the `api/db.ts` module and then be guided by TypeScript errors.
-```bash
+```bash-symbol
rm api/db.ts
```
@@ -324,10 +324,14 @@ schema.extendType({
Awesome, you're ready to open up the playground and create a draft! If all goes well, good job! If not, no worries, there's a lot of integration pieces in this chapter where something could have gone wrong. If after reviewing your steps you still don't understand the issue, feel free to open up a [discussion](https://nxs.li/discussions) asking for help.
-## Wrapping Up
+## Wrapping up
We've just changed our code, so we must be due or overdue for a test update right? Well, in the next chapter we'll do just that, and show you how Nexus testing works with Prisma.
-
-
-[β³](/tutorial/chapter-6-testing-with-prisma)
+
+ Next →
+
diff --git a/website/content/01-getting-started/03-tutorial/07-chapter-6-testing-with-prisma.mdx b/website/content/01-getting-started/03-tutorial/07-chapter-6-testing-with-prisma.mdx
index f4a9862dd..15b4b011d 100644
--- a/website/content/01-getting-started/03-tutorial/07-chapter-6-testing-with-prisma.mdx
+++ b/website/content/01-getting-started/03-tutorial/07-chapter-6-testing-with-prisma.mdx
@@ -187,6 +187,6 @@ About our app, it's starting to take shape but it's still lacking something pret
Come onto the next chapter to get that added to your app!
-
-
-[β³](/tutorial/chapter-7-authentication)
+
+ Next →
+
diff --git a/website/content/01-getting-started/03-tutorial/08-chapter-7-authentication.mdx b/website/content/01-getting-started/03-tutorial/08-chapter-7-authentication.mdx
index a6fe0c460..a58fd8d83 100644
--- a/website/content/01-getting-started/03-tutorial/08-chapter-7-authentication.mdx
+++ b/website/content/01-getting-started/03-tutorial/08-chapter-7-authentication.mdx
@@ -1,5 +1,5 @@
---
-title: 6. Authentication
+title: 7. Authentication
---
## Chapter 7: Authentication
diff --git a/website/content/01-migration-guides/01-prisma-users.mdx b/website/content/01-migration-guides/01-prisma-users.mdx
index 37b67d61e..b5fc52327 100644
--- a/website/content/01-migration-guides/01-prisma-users.mdx
+++ b/website/content/01-migration-guides/01-prisma-users.mdx
@@ -2,13 +2,13 @@
title: Prisma Users
---
-# Hello Prisma user!
+## Overview
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
+## Vanilla integration
As a Prisma user you can easily integrate Prisma into Nexus yourself, take a look:
@@ -54,7 +54,7 @@ If you haven't already, you should read the [Welcome to Nexus Prisma](/plugins/p
TL;DR
-```
+```bash-symbol
npm add nexus nexus-plugin-prisma
npm run nexus
```
diff --git a/website/content/01-migration-guides/02-nexus-schema-users.mdx b/website/content/01-migration-guides/02-nexus-schema-users.mdx
index a375d44b1..189ec7cb5 100644
--- a/website/content/01-migration-guides/02-nexus-schema-users.mdx
+++ b/website/content/01-migration-guides/02-nexus-schema-users.mdx
@@ -6,8 +6,6 @@ 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
index 6f8651631..51c3b2c37 100644
--- a/website/content/01-migration-guides/index.mdx
+++ b/website/content/01-migration-guides/index.mdx
@@ -1,3 +1,4 @@
---
title: Migration guides
+hidePage: false
---
diff --git a/website/content/02-guides/01-concepts.mdx b/website/content/02-guides/01-concepts.mdx
index 4f6df9b6f..920ed8ec9 100644
--- a/website/content/02-guides/01-concepts.mdx
+++ b/website/content/02-guides/01-concepts.mdx
@@ -2,7 +2,7 @@
title: 'Concepts'
---
-## Work, Run, Test
+## Overview
Nexus is a powerful tool built of multiple components that broadly fall into three categories: runtime, worktime, testtime.
diff --git a/website/content/02-guides/02-schema.mdx b/website/content/02-guides/02-schema.mdx
index 2f3950297..b7f0c3a00 100644
--- a/website/content/02-guides/02-schema.mdx
+++ b/website/content/02-guides/02-schema.mdx
@@ -2,9 +2,7 @@
title: 'Schema'
---
-## Schema
-
-[API Reference](/api/modules/main/exports/schema) β [issues](https://nxs.li/issues/component/schema) / [features](https://nxs.li/issues/components/schema/features) | [bugs](https://nxs.li/issues/component/schema/bugs)
+## Overview
This is the Nexus schema component guide. Here you will find concepts explained and a survey of how to use the API. If you are not familiar with Nexus this is a good document to read. If you are familiar, then the [Schema API Docs](/api/modules/main/exports/schema) may be of more use to you.
@@ -22,11 +20,9 @@ import { schema } from 'nexus' // named-export style
app.schema === schema // true
```
-
-
> Leverage [VSCode auto-import](https://code.visualstudio.com/docs/languages/typescript#_auto-imports). Anywhere in a TypeScript module in your project type either `app` to summon auto-import for the default style or `schema` for named-export style.
-### Singleton & Mutation
+### Singleton and mutation
The schema component is part of the app singleton and usage of its methods affects the overall app state. While this is not a functionally pure approach it does allow you to use its methods throughout your project without having to think about exporting/importing values. One of Nexus' design goals is to approach the ease and readability of [GraphQL SDL](https://www.prisma.io/blog/graphql-sdl-schema-definition-language-6755bcb9ce51) where we can. This is one example of doing that.
@@ -43,7 +39,7 @@ schema.objectType({
})
```
-## GraphQL Type Builders
+## GraphQL type builders
We will now begin exploring the GraphQL schema building parts of the schema component. Having prior knowledge of GraphQL language itself will greatly help. If you are new to GraphQL you may want to read some of the resources listed below.
@@ -55,7 +51,7 @@ We will now begin exploring the GraphQL schema building parts of the schema comp
[graphql.org Object Types](https://graphql.org/learn/schema/#object-types-and-fields)
-#### Basic Anatomy
+#### Basic anatomy
```ts
@@ -106,9 +102,7 @@ We will now begin exploring the GraphQL schema building parts of the schema comp
})
```
-#### Scalar Fields
-
-
+#### Scalar fields
```ts
schema.objectType({
@@ -133,11 +127,7 @@ type Alpha {
}
```
-
-
-#### Relational Fields
-
-
+#### Relational fields
```ts
schema.objectType({
@@ -169,12 +159,8 @@ type Beta {
}
```
-
-
###### Lists & Nullability
-
-
```ts
schema.objectType({
name: 'Alpha',
@@ -198,7 +184,6 @@ type Alpha {
}
```
-
### Entrypoint Types
@@ -208,7 +193,7 @@ Enum types are a scalar with a finite set of allowed values. They can be used as
[graphql.org Enumeration Types docs](https://graphql.org/learn/schema/#enumeration-types)
-
+
```ts
schema.enum({
@@ -224,11 +209,11 @@ enum Alpha {
}
```
-
-#### Example: As argument type & field type
-
+#### Example: As argument type and field type
+
+
```ts
schema.queryType({
@@ -265,8 +250,8 @@ type Query {
}
```
-
-
+
+
```graphql
query {
@@ -284,7 +269,7 @@ query {
}
```
-
+
### Union Type
@@ -345,7 +330,7 @@ If an arg has been given a default value, then it will be used when the client p
#### Example: Default Nullability Settings
-
+
```ts
schema.queryType({
@@ -368,11 +353,11 @@ type Query {
}
```
-
+
#### Example: Nullability Flipped at Global Level
-
+
```ts
settings.change({
@@ -404,11 +389,11 @@ type Query {
}
```
-
+
#### Example: Nullability Flipped at Type Level
-
+
```ts
schema.queryType({
@@ -435,11 +420,11 @@ type Query {
}
```
-
+
#### Example: Nullability Flipped at Input & Field Level
-
+
```ts
schema.queryType({
@@ -466,13 +451,13 @@ type Query {
}
```
-
+
#### Example: Mixing Levels
It is possible to use type and input/field layers together. This provides flexibility to optimize for local sections of your API that have different characteristics. For example here, a type deviates from the global default for all but but one field and its input.
-
+
```ts
schema.queryType({
@@ -508,13 +493,13 @@ type Query {
}
```
-
+
#### Example: Args That Have Default Values
When an arg has a default you might think that then it should be nullable to the client but non-nullable within your resolver logic. However it turns out that if the client passes an _explicit_ `null` then that is considered an actual value, and hence is not subject to being assigned the default value. Thus, and then, the resolver still can observe null from the client. If you are curious about seeing this change and/or become configurable then please refer to [#485](https://github.com/graphql-nexus/nexus/issues/485).
-
+
```ts
schema.queryType({
@@ -542,8 +527,8 @@ type Query {
}}
```
-
-
+
+
```graphql
query {
@@ -561,7 +546,7 @@ query {
}
```
-
+
## Backing Types in Principal
diff --git a/website/content/02-guides/03-server.mdx b/website/content/02-guides/03-server.mdx
index 34bc725c9..52852bc45 100644
--- a/website/content/02-guides/03-server.mdx
+++ b/website/content/02-guides/03-server.mdx
@@ -3,32 +3,31 @@ title: 'Server'
metaTitle: 'Server'
---
-## Server
-
-[API Reference](/api/modules/main/exports/server) β [issues](https://nxs.li/issues/component/server) / [features](https://nxs.li/issues/components/server/features) | [bugs](https://nxs.li/issues/component/server/bugs)
+## Overview
## Serverless
-- Nexus has experimental support for serverless deployments.
-- Support for serverless is being tracked in [#782](https://github.com/graphql-nexus/nexus/issues/782).
-- Serverless features are not yet documented in the API docs.
-- The server component of Nexus exposes HTTP request handlers.
+Nexus has **experimental** support for serverless deployments. Support for serverless is being tracked in [GitHub issue #782](https://github.com/graphql-nexus/nexus/issues/782).
+
+> **Note**: API documentation for the serverless features is not yet available.
+
+The server component of Nexus exposes HTTP request handlers:
- ```ts
- import { server } from 'nexus'
+```ts
+import { server } from 'nexus'
- server.handlers.graphql // call with (req, res)
- server.handlers.playground // call with (req, res)
- ```
+server.handlers.graphql // call with (req, res)
+server.handlers.playground // call with (req, res)
+```
-* Use these to handle to requests in your serverless environment.
+Use these to handle to requests in your serverless environment:
- ```ts
- import { server } from 'nexus'
+```ts
+import { server } from 'nexus'
- export default (req, res) => {
- server.handlers.graphql(req, res)
- }
- ```
+export default (req, res) => {
+ server.handlers.graphql(req, res)
+}
+```
-* See the [Next.JS example](https://github.com/graphql-nexus/examples/tree/master/with-nextjs) for a functioning serverless reference.
+See the [Next.JS example](https://github.com/graphql-nexus/examples/tree/master/with-nextjs) for a functioning serverless reference.
diff --git a/website/content/02-guides/04-logger.mdx b/website/content/02-guides/04-logger.mdx
index c1bb72ad2..dbd626e9a 100644
--- a/website/content/02-guides/04-logger.mdx
+++ b/website/content/02-guides/04-logger.mdx
@@ -2,9 +2,7 @@
title: Logger
---
-## Logger
-
-[API Reference](/api/modules/main/exports/logger) β [issues](https://nxs.li/issues/component/logger) / [features](https://nxs.li/issues/components/logger/features) | [bugs](https://nxs.li/issues/component/logger/bugs)
+## Overview
Use the logger to output structured information about runtime activity.
@@ -14,7 +12,7 @@ Your app should only output logs via Nexus Logger. This ensures that you maintai
All logs are sent to stdout (not stderr). Logs are formatted as JSON but there is a pretty mode designed for development.
-## Child Loggers
+## Child loggers
```ts
log.addToContext({ user: 'Toto' })
@@ -33,6 +31,6 @@ foo.info('foo')
You can create child loggers recursively starting from the root logger. A child logger extends their parent's component path and inherits their parent's context. Children can add context that is visible to themselves and their descendents.
-Child loggers are useful when you want to pass a logger to something that should be tracked as its own subsystem and/or may add context that you want isolated from the rest of the system. For example a classic use-case is the logger-instance-per-request pattern where a request-scoped logger is used for all logs in a request-response code path. This makes it much easier in production to group logs in your logging platform by request-response lifecycles.
+Child loggers are useful when you want to pass a logger to something that should be tracked as its own sub-system and/or may add context that you want isolated from the rest of the system. For example a classic use-case is the logger-instance-per-request pattern where a request-scoped logger is used for all logs in a request-response code path. This makes it much easier in production to group logs in your logging platform by request-response lifecycles.
-All runtime logs in your app (including from plugins come from either the `logger` itself or descendents thereof. This means if you wish absolutely every log being emitted by your app to contain some additional context you can do so simply by adding context to the root logger.
+All runtime logs in your app (including from plugins come from either the `logger` itself or descendents thereof). This means if you wish absolutely every log being emitted by your app to contain some additional context you can do so simply by adding context to the root logger.
diff --git a/website/content/02-guides/05-testing.mdx b/website/content/02-guides/05-testing.mdx
index ec0867049..afad3b40c 100644
--- a/website/content/02-guides/05-testing.mdx
+++ b/website/content/02-guides/05-testing.mdx
@@ -1,12 +1,13 @@
---
title: Testing
+toc: true
---
## Testing
Testing is a first-class concern of Nexus. So far we ship a few primitives to help you run integration tests, but you can expect integrated higher level testing features in the future.
-> Note: This guide is written using [`jest`](https://jestjs.io/) because it is what we use internally and thus can speak to best. But you should be able to use your test framework of choice.
+> **Note**: This guide is written using [`jest`](https://jestjs.io/) because it is what we use internally and thus can speak to best. But you should be able to use your test framework of choice.
## Meet the Module
@@ -17,7 +18,7 @@ Nexus comes with a special testing module that you can import from `nexus/testin
> For the curious...
> Since `jest` runs test suites in parallel it means multiple instances of your `app` will be run in parallel too. The testing module takes care of abstracting the mechanics of making this work from you. For example it assigns random ports to each app to run its server and makes sure each test suite's app client is configured to be talking with its respective app instance. You should _never_ have to think about these kinds of details though, and if it turns out you do please open a GitHub issue so we can try to seal the leak you've found in Nexus' abstraction!
-##### A Little Helper {docsify-ignore}
+### A Little Helper
Before jumping into test suites we will wrap the `createTestContext` with a pattern that more tightly integrates it into `jest`. Nexus will probably ship something like as follows or better in the future, but for now you can copy this into your projects:
@@ -98,11 +99,11 @@ Integration testing with a database can add a lot of complexity to your test sui
Integration between Nexus' test and database systems is young and still missing many features. Below we will cover some utilities and patterns that you can copy into your project meanwhile.
-> Note: This assumes you have [setup a PostgreSQL database running locally](references/recipes?id=localql). You could use any database supported by Prisma though.
+> **Note**: This assumes you have [setup a PostgreSQL database running locally](references/recipes?id=localql). You could use any database supported by Prisma though.
1. Install new development dependencies for upcoming test utilities.
- ```cli
+ ```bash-symbol
npm add --save-dev nanoid pg jest-environment-node
```
diff --git a/website/content/02-guides/06-project-layout.mdx b/website/content/02-guides/06-project-layout.mdx
index 72ad08fbe..b2d988031 100644
--- a/website/content/02-guides/06-project-layout.mdx
+++ b/website/content/02-guides/06-project-layout.mdx
@@ -1,15 +1,15 @@
---
-title: Project Layout
+title: Project layout
---
-## Working With tsconfig.json
+## Working with `tsconfig.json`
- Nexus honours settings within `tsconfig.json`.
- This ensures that Nexus and your IDE perform identical static analysis.
- If no `tsconfig.json` is present in the project root then Nexus will scaffold one for you. This will make ([VSCode treat it as the project root too](https://vscode.readthedocs.io/en/latest/languages/typescript/#typescript-files-and-projects)).
- Nexus interacts with `tsconfig.json` in the following ways.
-### Source Root
+### Source root
- Source Root is the base from which your source code layout starts. So, all of your app code must live within the source root. Your JavaScript build output layout will mirror it.
- Source Root is defined by setting `compilerOptions.rootDir` and adding its value also to the `includes` array. For detail into why it works like this see [microsoft/TypeScript#9858](https://github.com/microsoft/TypeScript/issues/9858#issuecomment-533287263) and this [StackOverflow answer](https://stackoverflow.com/questions/57333825/can-you-pull-in-excludes-includes-options-in-typescript-compiler-api).
@@ -23,7 +23,7 @@ title: Project Layout
- If you do not specify it then Nexus will default to `.nexus/build`. Unlike with `rootDir` Nexus will not scaffold the default into your `tsconfig.json` because its presence has no impact upon VSCode.
- You can override its value interactively with `nexus build --out`.
-### Check-Only Builds
+### Check-only builds
if `compilerOptions.noEmit` is set to `true` then Nexus will not output the build. This makes `nexus build` effectively a checker. This option usually [represents user error](https://github.com/graphql-nexus/nexus/issues/702) so by default Nexus will warn when this option is used. In the future ([#800](https://github.com/graphql-nexus/nexus/issues/800)) there will be ways to disable this the warning if it is really your intent.
@@ -43,7 +43,7 @@ Autocomplete with Nexus TS LSP:
Nexus has some conventions about `tsconfig.json` settings designed to support your zero-config experience.
-#### Local Package Typings
+#### Local package typings
Sometimes you need to augment or provide outright types for some third party library. You can do this one of two ways.
@@ -57,11 +57,11 @@ If you have to write a lot of typings for multiple packages then you can create
index.d.ts <-- Typings
```
-#### noEmit
+#### `noEmit`
Nexus enforces that `compilerOptions.noEmit` is `true`. It handles this setting internally. If for some reason you want to run `tsc` you won't need to remember to pass the `--noEmit` flag.
-#### typeRoots
+#### `typeRoots`
Nexus enforces that your `compilerOptions.typeRoots` includes:
@@ -72,7 +72,7 @@ Nexus enforces that your `compilerOptions.typeRoots` includes:
Nexus imposes a few requirements about how you structure your codebase.
-### Project Root
+### Project root
The project root is the directory from which all all Nexus CLI commands base their CWD upon. It is also the directory that configuration paths in Nexus (e.g. `--entrypoint` flag) are often relative to as well (in other cases it can be source root).
diff --git a/website/content/02-guides/07-error-handling.mdx b/website/content/02-guides/07-error-handling.mdx
index 33de18322..0ce9fe2a8 100644
--- a/website/content/02-guides/07-error-handling.mdx
+++ b/website/content/02-guides/07-error-handling.mdx
@@ -2,8 +2,6 @@
title: Error Handling
---
-## Error Handling
-
-## Global
+## Overview
Nexus provides last-resort error handling for your app. It handles both of Node's [`uncaughtException`](https://nodejs.org/api/process.html#process_event_uncaughtexception) and [`unhandledRejection`](https://nodejs.org/api/process.html#process_event_unhandledrejection) process events. The error will be logged and then your app process will be terminated with exit code 1.
diff --git a/website/content/02-guides/08-plugins.mdx b/website/content/02-guides/08-plugins.mdx
index 1053063c9..298ff164c 100644
--- a/website/content/02-guides/08-plugins.mdx
+++ b/website/content/02-guides/08-plugins.mdx
@@ -1,9 +1,3 @@
---
title: Plugins
---
-
-## Plugins
-
-[API Reference](/api/modules/main/exports/use) β [issues](https://nxs.li/issues/component/plugins) / [features](https://nxs.li/issues/components/plugins/features) | [bugs](https://nxs.li/issues/component/plugins/bugs)
-
-todo
diff --git a/website/content/02-guides/09-recipes.mdx b/website/content/02-guides/09-recipes.mdx
index 11908c6d7..8aabc453c 100644
--- a/website/content/02-guides/09-recipes.mdx
+++ b/website/content/02-guides/09-recipes.mdx
@@ -8,7 +8,7 @@ title: Recipes
1. Install the prisma plugin
- ```cli
+ ```bash-symbol
npm add nexus-plugin-prisma
```
@@ -38,7 +38,7 @@ title: Recipes
1. Initialize your database
- ```cli
+ ```bash-symbol
yarn prisma migrate save --experimental && yarn prisma migrate up --experimental
```
@@ -83,13 +83,13 @@ title: Recipes
1. Scaffold Your plugin project
- ```cli
+ ```bash-symbol
npx nexus create plugin
```
2. Publish it
- ```cli
+ ```bash-symbol
yarn publish
```
@@ -99,7 +99,7 @@ title: Recipes
For trying things out in a deployed setting you can try Heroku's free postgres tier. Setting it up is simple:
-```bash
+```bash-symbol
heroku create
heroku addons:create heroku-postgresql
@@ -115,7 +115,7 @@ The recommended way to run postgres locally is with docker, because it is easy f
1. Start a postgres server for your app:
- ```cli
+ ```bash-symbol
docker run --detach --publish 5432:5432 -e POSTGRES_PASSWORD=postgres --name 'postgres' postgres:10.12
```
@@ -177,7 +177,7 @@ If you don't want to use a docker, here are some links to alternative approaches
1. Install `direnv`
- ```cli
+ ```bash-symbol
brew install direnv
```
@@ -190,7 +190,7 @@ If you don't want to use a docker, here are some links to alternative approaches
```
1. Approve the `.envrc` file (one time, every time the envrc file changes).
- ```cli
+ ```bash-symbol
direnv allow .
```
1. Done. Now when you work within your project with a shell, all your commands will be run with access to the environment variables defined in your `.envrc` file. The magic of `direnv` is that these environment variables are automatically exported to and removed from your environment based on you being within your project directory or not.
@@ -246,7 +246,7 @@ If you don't want to use a docker, here are some links to alternative approaches
We made it very simple to debug your app with VS Code.
-> Note: If you used `npx nexus` to initialize your project, jump straight to step 2.
+> **Note**: If you used `npx nexus` to initialize your project, jump straight to step 2.
1. Create a `.vscode/launch.json` file and paste the following content
diff --git a/website/content/02-guides/10-writing-plugins.mdx b/website/content/02-guides/10-writing-plugins.mdx
index 6e7ff9778..c18c4a67b 100644
--- a/website/content/02-guides/10-writing-plugins.mdx
+++ b/website/content/02-guides/10-writing-plugins.mdx
@@ -17,167 +17,169 @@ title: Writing Plugins
## How it Looks
-- Nexus CLI has a command to create new Nexus-plugin projects
- ```cli
- nexus create plugin
- ```
-- To write a plugin you create any of `testtime` `runtime` and `worktime` modules and import the respective plugin types to type your function. In each module export your plugin as `plugin`.
-
- ```ts
- // runtime.ts
- import { RuntimePlugin } from 'nexus/plugin'
-
- export const plugin: RuntimePlugin = () => (project) => {
- /* ... */
- }
- ```
-
- ```ts
- // testtime.ts
- import { TesttimePlugin } from 'nexus/plugin'
-
- export const plugin: TesttimePlugin = () => (project) => {
- /* ... */
- }
- ```
-
- ```ts
- // worktime.ts
- import { WorktimePlugin } from 'nexus/plugin'
-
- export const plugin: WorktimePlugin = () => (project) => {
- /* ... */
- }
- ```
-
-- The `project` parameter gives you access to utils and core components
-
- ```ts
- export const plugin: TesttimePlugin = () => (project) => {
- project.utils.log.trace('hello')
- }
- ```
-
-- With runtime plugins you can pass configuration to Nexus and contribute toward the graphql resolver context:
-
- ```ts
- export const plugin: RuntimePlugin = () => project => {
- return {
- context: {
- create: req => {
- return {
- token: req.headers.authorization.match(/^Bearer (.+)$/)?[1] ?? null
- }
- },
- typeGen: {
- fields: {
- token: 'null | string'
- }
+The Nexus CLI has a command to create new Nexus-plugin projects
+
+```bash-symbol
+nexus create plugin
+```
+
+To write a plugin you create any of `testtime` `runtime` and `worktime` modules and import the respective plugin types to type your function. In each module export your plugin as `plugin`.
+
+```ts
+// runtime.ts
+import { RuntimePlugin } from 'nexus/plugin'
+
+export const plugin: RuntimePlugin = () => project => {
+ /* ... */
+}
+```
+
+```ts
+// testtime.ts
+import { TesttimePlugin } from 'nexus/plugin'
+
+export const plugin: TesttimePlugin = () => project => {
+ /* ... */
+}
+```
+
+```ts
+// worktime.ts
+import { WorktimePlugin } from 'nexus/plugin'
+
+export const plugin: WorktimePlugin = () => project => {
+ /* ... */
+}
+```
+
+The `project` parameter gives you access to utils and core components
+
+```ts
+export const plugin: TesttimePlugin = () => project => {
+ project.utils.log.trace('hello')
+}
+```
+
+With runtime plugins you can pass configuration to Nexus and contribute toward the graphql resolver context:
+
+```ts
+export const plugin: RuntimePlugin = () => project => {
+ return {
+ context: {
+ create: req => {
+ return {
+ token: req.headers.authorization.match(/^Bearer (.+)$/)?[1] ?? null
}
},
- schema: {
- // ...
+ typeGen: {
+ fields: {
+ token: 'null | string'
+ }
}
+ },
+ schema: {
+ // ...
}
}
}
- ```
-
-- With worktime plugins you can hook onto various events grouped by subsystem:
-
- ```ts
- export const plugin: WorktimePlugin = () => project => {
- // Not all hooks shown here
- project.hooks.build.onStart = async () => { ... }
- project.hooks.create.onAfterBaseSetup = async () => { ... }
- project.hooks.generate.onStart = async () => { ... }
- project.hooks.dev.onStart = async () => { ... }
- project.hooks.dev.onFileWatcherEvent = async () => { ... }
- project.hooks.dev.addToSettings = { ... }
- project.hooks.db.init.onStart = async () => { ... }
- project.hooks.db.migrate.apply = async () => { ... }
- project.hooks.db.plan.onStart = async () => { ... }
- project.hooks.db.rollback.onStart = async () => { ... }
- project.hooks.db.ui.onStart = async () => { ... }
+}
+```
+
+With worktime plugins you can hook onto various events grouped by sub-system:
+
+```ts
+export const plugin: WorktimePlugin = () => project => {
+ // Not all hooks shown here
+ project.hooks.build.onStart = async () => { ... }
+ project.hooks.create.onAfterBaseSetup = async () => { ... }
+ project.hooks.generate.onStart = async () => { ... }
+ project.hooks.dev.onStart = async () => { ... }
+ project.hooks.dev.onFileWatcherEvent = async () => { ... }
+ project.hooks.dev.addToSettings = { ... }
+ project.hooks.db.init.onStart = async () => { ... }
+ project.hooks.db.migrate.apply = async () => { ... }
+ project.hooks.db.plan.onStart = async () => { ... }
+ project.hooks.db.rollback.onStart = async () => { ... }
+ project.hooks.db.ui.onStart = async () => { ... }
+}
+```
+
+Some worktime hooks give you contextual information to reflect upon:
+
+```ts
+export const plugin: WorktimePlugin = () => project => {
+ project.hooks.db.plan.onStart = async ctx => {
+ project.log.info(ctx.migrationName)
}
- ```
+})
+```
-- Some worktime hooks give you contextual information to reflect upon:
+Finally, for your plugin to be consumed by Nexus, you need to export an entrypoint which references your runtime or worktime or testtime plugin.
- ```ts
- export const plugin: WorktimePlugin = () => project => {
- project.hooks.db.plan.onStart = async ctx => {
- project.log.info(ctx.migrationName)
- }
- })
- ```
+**This entrypoint is what needs to be imported by users.**
-- Finally, for your plugin to be consumed by Nexus, you need to export an entrypoint which references your runtime or worktime or testtime plugin.
+We recommend you named export the entrypoint after the suffix `nexus-plugin-(*)` of your npm package name.
- **This entrypoint is what needs to be imported by users.**
+For instance, if your plugin is named `nexus-plugin-fancy-plugin`, your entrypoint should be named export `fancyPlugin`
- We recommend you named export the entrypoint after the suffix `nexus-plugin-(*)` of your npm package name.
+```ts
+import { PluginEntrypoint } from 'nexus/plugin'
- For instance, if your plugin is named `nexus-plugin-fancy-plugin`, your entrypoint should be named export `fancyPlugin`
-
- ```ts
- import { PluginEntrypoint } from 'nexus/plugin'
-
- export const fancyPlugin: PluginEntrypoint = () => ({
- packageJsonPath: require.resolve('../package.json'),
- runtime: {
- module: require.resolve('./runtime'),
- export: 'plugin',
- },
- worktime: {
- module: require.resolve('./worktime'),
- export: 'plugin',
- },
- testtime: {
- module: require.resolve('./testtime'),
- export: 'plugin',
- },
- })
- ```
+export const fancyPlugin: PluginEntrypoint = () => ({
+ packageJsonPath: require.resolve('../package.json'),
+ runtime: {
+ module: require.resolve('./runtime'),
+ export: 'plugin',
+ },
+ worktime: {
+ module: require.resolve('./worktime'),
+ export: 'plugin',
+ },
+ testtime: {
+ module: require.resolve('./testtime'),
+ export: 'plugin',
+ },
+})
+```
## Adding settings to your plugin
-- Create a `settings.ts` file and export a type `Settings` containing your settings
+1. Create a `settings.ts` file and export a type `Settings` containing your settings
- ```ts
- // settings.ts
- export type Settings = {
- myCustomOption?: boolean
- }
- ```
+```ts
+// settings.ts
+export type Settings = {
+ myCustomOption?: boolean
+}
+```
-- Import the `Settings` type in your entrypoint, and pass it as generic to `PluginEntrypoint`.
+2. Import the `Settings` type in your entrypoint, and pass it as generic to `PluginEntrypoint`.
- > Note: You must return the settings untouched in your entrypoint.
- > The framework is then responsible for passing the settings to your runtime/worktime/testtime plugins .
+> **Note**: You must return the settings untouched in your entrypoint.
+> The framework is then responsible for passing the settings to your runtime/worktime/testtime plugins .
- ```ts
- //entrypoint.ts
- import { PluginEntrypoint } from 'nexus/plugin'
- import { Settings } from './settings'
+```ts
+//entrypoint.ts
+import { PluginEntrypoint } from 'nexus/plugin'
+import { Settings } from './settings'
- export const fancyPlugin: PluginEntrypoint = settings => ({
- settings,
- ...
- })
- ```
+export const fancyPlugin: PluginEntrypoint = settings => ({
+ settings,
+ ...
+})
+```
-- Repeat the operation for your runtime/worktime/testtime plugins.
+3. Repeat the operation for your runtime/worktime/testtime plugins.
- ```ts
- // runtime.ts
- import { RuntimePlugin } from 'nexus/plugin'
- import { Settings } from './settings'
+```ts
+// runtime.ts
+import { RuntimePlugin } from 'nexus/plugin'
+import { Settings } from './settings'
- export const plugin: RuntimePlugin = (settings) => (project) => {
- // ...
- }
- ```
+export const plugin: RuntimePlugin = settings => project => {
+ // ...
+}
+```
- By default, settings will always be optional.
@@ -188,7 +190,7 @@ title: Writing Plugins
import { PluginEntrypoint } from 'nexus/plugin'
import { Settings } from './settings'
- export const fancyPlugin: PluginEntrypoint = (settings) => ({
+ export const fancyPlugin: PluginEntrypoint = settings => ({
settings,
// ...
})
@@ -197,7 +199,7 @@ title: Writing Plugins
import { RuntimePlugin } from 'nexus/plugin'
import { Settings } from './settings'
- export const plugin: RuntimePlugin = (settings) => (project) => {
+ export const plugin: RuntimePlugin = settings => project => {
// ...
}
```
@@ -211,20 +213,20 @@ title: Writing Plugins
- No longer does a plugin need rely on a lengthy readme that probably isn't complete and probably isn't read by most users to guide users through correct configuration, etc. usage of their plugin
- Nexus is fanatic about giving as much latitude as possible to plugin authors to craft plugins that forward the principal of the pit of success to Nexus app developers
-## Runtime vs Worktime
+## Runtime vs worktime
- runtime is for hooking into when your app is actually running
- so logic here can directly impact your production systems' reliability and performance characteristics
- worktime is for hooking into things like dev testing and building
- logic here is relatively free from concern over runtime impact, e.g. some slow running build-time extensions cannot impact latency experienced by end-users of the app in production.
-## Publishing for Consumption
+## Publishing for consumption
- You must name your plugin package `nexus-plugin-`
- Nexus plugin cli will rely on this convention to search install etc. plugins ([todo](https://github.com/graphql-nexus/nexus/issues/155))
- Nexus relies on this pattern to auto-use plugins in a user's project
-## A Code Reference
+## A code reference
- The most sophisticated real-world Nexus plugin is `nexus-plugin-prisma`.
- It currently drives many of the requirements of the plugin system where we want nexus-prisma users to feel prisma is as seamless a component as any core one.
diff --git a/website/content/02-guides/11-cli.mdx b/website/content/02-guides/11-cli.mdx
index b8675e766..f07e6ac82 100644
--- a/website/content/02-guides/11-cli.mdx
+++ b/website/content/02-guides/11-cli.mdx
@@ -10,21 +10,21 @@ If you prefer, you can install Nexus globally and then use the global CLI to wor
-```cli
+```bash-symbol
cd my-project
```
-```cli
+```bash-symbol
nexus dev
```
@@ -40,14 +40,14 @@ This is just a convenience. It is equivalent to:
}
```
-```cli
+```bash-symbol
npm run nexus:dev
```
-```cli
+```bash-symbol
yarn nexus dev
```
diff --git a/website/content/03-plugins/01-prisma.mdx b/website/content/03-nexus-plugins/01-prisma.mdx
similarity index 97%
rename from website/content/03-plugins/01-prisma.mdx
rename to website/content/03-nexus-plugins/01-prisma.mdx
index 3e187a5a1..8a97e1960 100644
--- a/website/content/03-plugins/01-prisma.mdx
+++ b/website/content/03-nexus-plugins/01-prisma.mdx
@@ -1,21 +1,24 @@
---
-title: '`prisma`'
+title: 'prisma'
---
-## Prisma
+## Overview
[`issues`](https://github.com/graphql-nexus/nexus/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Aplugin%2Fprisma) β [features](https://github.com/graphql-nexus/nexus/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Aplugin%2Fprisma+label%3Atype%2Ffeat) β¬ [bugs](https://github.com/graphql-nexus/nexus/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Aplugin%2Fprisma+label%3Atype%2Fbug)
Prisma is a next-generation developer-centric toolkit focused on making the data layer easy. This plugin gives you:
-1. **Workflow Integration**
- Nexus `build` and `dev` workflows are enhanced to run your Prisma generators.
+### Workflow integration
-1. **Runtime Integration**
- Nexus schema component [GraphQL type builders](/guides/schema#graphql-type-builders) are augmented with `.model` and `.crud` methods. These make it easy for you to project your Prisma models and expose operations against them in your GraphQL API. Resolvers are dynamically created for you removing the need for traditional ORMs/query builders like TypeORM, Sequelize, or Knex. Out-of-box features include pagination, filtering, and ordering. And when you do need to drop down to custom resolvers a [`Prisma Client`](https://github.com/prisma/prisma-client-js) instance on `context` is ready to go.
+Nexus `build` and `dev` workflows are enhanced to run your Prisma generators.
-1. **Testtime Integration**
- Nexus testing component is augmented with an instance of the [`Prisma Client`](https://github.com/prisma/prisma-client-js), to help you easily seed your database for your tests.
+### Runtime integration
+
+Nexus schema component [GraphQL type builders](/guides/schema#graphql-type-builders) are augmented with `.model` and `.crud` methods. These make it easy for you to project your Prisma models and expose operations against them in your GraphQL API. Resolvers are dynamically created for you removing the need for traditional ORMs/query builders like TypeORM, Sequelize, or Knex. Out-of-box features include pagination, filtering, and ordering. And when you do need to drop down to custom resolvers a [`Prisma Client`](https://github.com/prisma/prisma-client-js) instance on `context` is ready to go.
+
+### Testtime integration
+
+Nexus testing component is augmented with an instance of the [`Prisma Client`](https://github.com/prisma/prisma-client-js), to help you easily seed your database for your tests.
@@ -23,16 +26,15 @@ Prisma is a next-generation developer-centric toolkit focused on making the data
## Installation
-**1. Install the plugin**
+### 1. Install the plugin
-```cli
+```bash-symbol
npm add nexus-plugin-prisma
```
-
> Warning: All Prisma deps are bundled, so do _not_ install e.g. `@prisma/cli` or `@prisma/client`. If you are wondering _why_ you can read through [Nexus' philosophy on dependency management](/meta/architecture#dependency-philosophy). You can still find the the prisma CLI by running `npm run prisma` or `yarn prisma`. In an emergency you can still control version of prisma deps with Yarn [`"resolutions"`](https://classic.yarnpkg.com/en/docs/selective-version-resolutions).
-**2. Enable the plugin**
+### 2. Enable the plugin
```ts
import { use } from 'nexus'
@@ -68,7 +70,7 @@ We recommend you use Postgres but MySQL and SQLite are also supported.
To add your datasource, simply copy/paste one of the block below at the top of your `schema.prisma` file
-> Note: You can also pass the database credentials via a `.env` file. [Read more about it here](https://www.prisma.io/docs/reference/tools-and-interfaces/prisma-schema/prisma-schema-file#using-environment-variables)
+> **Note**: You can also pass the database credentials via a `.env` file. [Read more about it here](https://www.prisma.io/docs/reference/tools-and-interfaces/prisma-schema/prisma-schema-file#using-environment-variables)
**Using Postgres**
@@ -127,7 +129,7 @@ When starting from an existing database, you should use [Prisma's introspection]
Create a `schema.prisma` file and add your database credentials in it so that Prisma can introspect your database schema.
-> Note: You can also pass the database credentials via a `.env` file. [Read more about it here](https://www.prisma.io/docs/reference/tools-and-interfaces/prisma-schema/prisma-schema-file#using-environment-variables)
+> **Note**: You can also pass the database credentials via a `.env` file. [Read more about it here](https://www.prisma.io/docs/reference/tools-and-interfaces/prisma-schema/prisma-schema-file#using-environment-variables)
**Using Postgres**
@@ -188,7 +190,7 @@ You're ready to start working!
Given a [Prisma schema](https://github.com/prisma/prisma2/blob/master/docs/prisma-schema-file.md) (left), you will be able to project these Prisma models onto your API and expose operations against them (middle) resulting in the GraphQL Schema (right).
-> Note: `t.crud` is an experimental feature. You must explicitly enable it [via the plugin options](#type-definition).
+> **Note**: `t.crud` is an experimental feature. You must explicitly enable it [via the plugin options](#type-definition).
diff --git a/website/content/03-nexus-plugins/02-jwt-auth.mdx b/website/content/03-nexus-plugins/02-jwt-auth.mdx
new file mode 100644
index 000000000..d9345fb50
--- /dev/null
+++ b/website/content/03-nexus-plugins/02-jwt-auth.mdx
@@ -0,0 +1,7 @@
+---
+title: 'jwt-auth'
+---
+
+## Overview
+
+See: https://github.com/Camji55/nexus-plugin-jwt-auth
diff --git a/website/content/03-nexus-plugins/03-graphql-shield.mdx b/website/content/03-nexus-plugins/03-graphql-shield.mdx
new file mode 100644
index 000000000..c433a564f
--- /dev/null
+++ b/website/content/03-nexus-plugins/03-graphql-shield.mdx
@@ -0,0 +1,7 @@
+---
+title: 'shield'
+---
+
+## Overview
+
+See: https://github.com/lvauvillier/nexus-plugin-shield
diff --git a/website/content/03-plugins/index.mdx b/website/content/03-nexus-plugins/index.mdx
similarity index 100%
rename from website/content/03-plugins/index.mdx
rename to website/content/03-nexus-plugins/index.mdx
diff --git a/website/content/03-plugins/02-jwt-auth.mdx b/website/content/03-plugins/02-jwt-auth.mdx
deleted file mode 100644
index 1027fa46a..000000000
--- a/website/content/03-plugins/02-jwt-auth.mdx
+++ /dev/null
@@ -1,7 +0,0 @@
----
-title: '`jwt-auth` β₯'
----
-
-## `jwt-auth`
-
-https://github.com/Camji55/nexus-plugin-jwt-auth
diff --git a/website/content/03-plugins/03-graphql-shield.mdx b/website/content/03-plugins/03-graphql-shield.mdx
deleted file mode 100644
index 40dc52c0a..000000000
--- a/website/content/03-plugins/03-graphql-shield.mdx
+++ /dev/null
@@ -1,7 +0,0 @@
----
-title: '`shield` β₯'
----
-
-## `shield`
-
-https://github.com/lvauvillier/nexus-plugin-shield
diff --git a/website/content/04-api/01-nexus/01-schema.mdx b/website/content/04-api/01-nexus/01-schema.mdx
index 12b51d467..7c0e3e670 100644
--- a/website/content/04-api/01-nexus/01-schema.mdx
+++ b/website/content/04-api/01-nexus/01-schema.mdx
@@ -1,5 +1,5 @@
---
-title: '`schema`'
+title: 'schema'
---
## `import { schema }`
@@ -28,13 +28,9 @@ objectType(config: {
```
- `name` **(required)** The name of this object.
-
- `definition` **(required)** The function used to define the fields of this object. See below for the various field builders available.
-
- `description` The description of this object. Tools like GraphQL Playground can display this content.
-
- `nonNullDefaults` [NonNullConfig](#i-nonnullconfig)
-
- `rootTyping` [NexusGenBackingTypes](#s-nexusgenbackingtypes)
#### Example
@@ -972,7 +968,7 @@ schema.middleware((config: CreateFieldResolverInfo) => MiddlewareFn | undefined)
If the current middleware function does not end the request-response cycle, it must call `next` to pass control to the next middleware function, until the actual GraphQL resolver gets called.
-> Note: You can skip the creation of a middleware by returning `undefined` instead of a middleware.
+> **Note**: You can skip the creation of a middleware by returning `undefined` instead of a middleware.
#### Example: Simple middlewares
diff --git a/website/content/04-api/01-nexus/02-log.mdx b/website/content/04-api/01-nexus/02-log.mdx
index 654ea3bc1..cedf40802 100644
--- a/website/content/04-api/01-nexus/02-log.mdx
+++ b/website/content/04-api/01-nexus/02-log.mdx
@@ -1,5 +1,5 @@
---
-title: '`log`'
+title: 'log'
---
## `import { log }`
diff --git a/website/content/04-api/01-nexus/03-server.mdx b/website/content/04-api/01-nexus/03-server.mdx
index a3fa4bbab..bfe9f1730 100644
--- a/website/content/04-api/01-nexus/03-server.mdx
+++ b/website/content/04-api/01-nexus/03-server.mdx
@@ -1,5 +1,5 @@
---
-title: '`server`'
+title: 'server'
---
## `import { server }`
diff --git a/website/content/04-api/01-nexus/04-settings.mdx b/website/content/04-api/01-nexus/04-settings.mdx
index 01afcf603..0219e11f8 100644
--- a/website/content/04-api/01-nexus/04-settings.mdx
+++ b/website/content/04-api/01-nexus/04-settings.mdx
@@ -1,5 +1,5 @@
---
-title: '`settings`'
+title: 'settings'
---
## `import { settings }`
diff --git a/website/content/04-api/01-nexus/05-use.mdx b/website/content/04-api/01-nexus/05-use.mdx
index 7281e50da..9f5546cc1 100644
--- a/website/content/04-api/01-nexus/05-use.mdx
+++ b/website/content/04-api/01-nexus/05-use.mdx
@@ -1,5 +1,5 @@
---
-title: '`use`'
+title: 'use'
---
## `import { use }`
diff --git a/website/content/04-api/01-nexus/06-fixme.mdx b/website/content/04-api/01-nexus/06-fixme.mdx
deleted file mode 100644
index 0d471a1ab..000000000
--- a/website/content/04-api/01-nexus/06-fixme.mdx
+++ /dev/null
@@ -1,49 +0,0 @@
----
-title: fixme
----
-
-FIX ME: This page should be at the parent level
-
-## `nexus`
-
-The main module exports an application singleton. It is available as the default export. For convenience you can import the app components as named exports too.
-
-**Example of importing default export**
-
-```ts
-import app from 'nexus'
-
-app.log.info('hello world')
-
-app.settings.change({
- server: {
- port: 5689,
- },
-})
-
-app.schema.queryType({
- definition(t) {
- t.field('foo', { type: 'String' })
- },
-})
-```
-
-**Example of importing named exports**
-
-```ts
-import { schema, settings, log } from 'nexus'
-
-log.info('hello world')
-
-settings.change({
- server: {
- port: 5689,
- },
-})
-
-schema.queryType({
- definition(t) {
- t.field('foo', { type: 'String' })
- },
-})
-```
diff --git a/website/content/04-api/01-nexus/index.mdx b/website/content/04-api/01-nexus/index.mdx
index 75a16e3f6..01f84c62b 100644
--- a/website/content/04-api/01-nexus/index.mdx
+++ b/website/content/04-api/01-nexus/index.mdx
@@ -1,3 +1,47 @@
---
-title: '`nexus`'
+title: 'nexus'
---
+
+## Overview
+
+The main `nexus` module exports an application singleton. It is available as the default export. For convenience you can import the app components as named exports too.
+
+### Example of importing default export
+
+```ts
+import app from 'nexus'
+
+app.log.info('hello world')
+
+app.settings.change({
+ server: {
+ port: 5689,
+ },
+})
+
+app.schema.queryType({
+ definition(t) {
+ t.field('foo', { type: 'String' })
+ },
+})
+```
+
+### Example of importing named exports
+
+```ts
+import { schema, settings, log } from 'nexus'
+
+log.info('hello world')
+
+settings.change({
+ server: {
+ port: 5689,
+ },
+})
+
+schema.queryType({
+ definition(t) {
+ t.field('foo', { type: 'String' })
+ },
+})
+```
diff --git a/website/content/04-api/02-nexus-testing.mdx b/website/content/04-api/02-nexus-testing.mdx
index b09cde262..7759233d3 100644
--- a/website/content/04-api/02-nexus-testing.mdx
+++ b/website/content/04-api/02-nexus-testing.mdx
@@ -1,5 +1,5 @@
---
-title: '`nexus/testing`'
+title: 'nexus/testing'
metaTitle: 'nexus/testing'
---
diff --git a/website/content/04-api/03-nexus-plugin.mdx b/website/content/04-api/03-nexus-plugin.mdx
index d5c06728c..f4e8cdd41 100644
--- a/website/content/04-api/03-nexus-plugin.mdx
+++ b/website/content/04-api/03-nexus-plugin.mdx
@@ -1,5 +1,5 @@
---
-title: '`nexus/plugin`'
+title: 'nexus/plugin'
---
## `nexus/plugin`
diff --git a/website/content/05-meta/01-roadmap.mdx b/website/content/05-meta/01-roadmap.mdx
index e489ca533..a1ff32718 100644
--- a/website/content/05-meta/01-roadmap.mdx
+++ b/website/content/05-meta/01-roadmap.mdx
@@ -1,7 +1,7 @@
---
-title: Roadmap β₯
+title: Roadmap
---
-## Roadmap
+## Overview
[Please refer to the Nexus Roadmap kanban](https://github.com/orgs/graphql-nexus/projects/1)
diff --git a/website/content/05-meta/02-changelog.mdx b/website/content/05-meta/02-changelog.mdx
index 2b6222714..562d41377 100644
--- a/website/content/05-meta/02-changelog.mdx
+++ b/website/content/05-meta/02-changelog.mdx
@@ -2,7 +2,7 @@
title: Changelog
---
-## Changelog
+## Overview
You can find notes for all releases at the [Nexus GitHub repo releases](https://github.com/graphql-nexus/nexus/releases) page.
diff --git a/website/content/05-meta/03-spec-sheet.mdx b/website/content/05-meta/03-spec-sheet.mdx
index b4004f182..81ad18d46 100644
--- a/website/content/05-meta/03-spec-sheet.mdx
+++ b/website/content/05-meta/03-spec-sheet.mdx
@@ -2,7 +2,7 @@
title: Spec Sheet
---
-## Lay of the Land
+## Lay of the land
- **Website** https://nexusjs.org
- **Twitter** https://twitter.com/nexusgql
@@ -10,7 +10,7 @@ title: Spec Sheet
- **Discussions** https://github.com/graphql-nexus/nexus/discussions
- **Changelog** https://github.com/graphql-nexus/nexus/releases ([canary](https://github.com/graphql-nexus/nexus/releases/tag/next))
-## Repos & Packages
+## Repositories and packages
@@ -60,7 +60,7 @@ title: Spec Sheet
- Enhanced IDE Experience via TypeScript Language Service Plugin
- Refined nexus lib autocomplete
-## Future Features
+## Future features
- Integrated query complexity analysis
- Integrated Bundler
@@ -87,7 +87,7 @@ We plan to lift these limitations one day.
- Subscriptions [#447](https://github.com/graphql-nexus/nexus/issues/447)
- Interface Extensions [#713](https://github.com/graphql-nexus/nexus/issues/713)
-## Non-Goals
+## Non-goals
We do not plan to lift these limitations.
diff --git a/website/content/05-meta/04-architecture.mdx b/website/content/05-meta/04-architecture.mdx
index 50c45c521..0c9a1dbf6 100644
--- a/website/content/05-meta/04-architecture.mdx
+++ b/website/content/05-meta/04-architecture.mdx
@@ -3,7 +3,7 @@ title: 'Architecture'
metaTitle: 'Architecture'
---
-## Repos & Packages
+## Repositories and packages
diff --git a/website/content/06-components-standalone/01-schema/01-api/99-fixme.mdx b/website/content/06-components-standalone/01-schema/01-api/99-fixme.mdx
deleted file mode 100644
index eb666664f..000000000
--- a/website/content/06-components-standalone/01-schema/01-api/99-fixme.mdx
+++ /dev/null
@@ -1,20 +0,0 @@
----
-title: __fixme__
----
-
-FIXME this content should be at parent level
-
-## API
-
-The API has been carefully designed with the following goals in mind:
-
-1. Type-Safety [by default](type-generation.md)
-1. Readability
-1. Developer ergonomics
-1. Playing nicely with Prettier formatting
-
-The API has evolved over the last few months of early development and internal use, and outside of implementing [additional features](future-features.md) is unlikely to undergo major structural changes.
-
-That is, before you open a GitHub issue or pull-request with a suggested change to the API, ensure that it meets all four of those criteria listed above and be able to explain why a change is necessary.
-
-Each public API is documented. Find them in the sidebar.
diff --git a/website/content/06-components-standalone/01-schema/01-api/index.mdx b/website/content/06-components-standalone/01-schema/01-api/index.mdx
index 9af5745d9..3e26e46c9 100644
--- a/website/content/06-components-standalone/01-schema/01-api/index.mdx
+++ b/website/content/06-components-standalone/01-schema/01-api/index.mdx
@@ -1,3 +1,18 @@
---
title: API
---
+
+## Overview
+
+The API has been carefully designed with the following goals in mind:
+
+1. Type-Safety [by default](type-generation.md)
+1. Readability
+1. Developer ergonomics
+1. Playing nicely with Prettier formatting
+
+The API has evolved over the last few months of early development and internal use, and outside of implementing [additional features](future-features.md) is unlikely to undergo major structural changes.
+
+That is, before you open a GitHub issue or pull-request with a suggested change to the API, ensure that it meets all four of those criteria listed above and be able to explain why a change is necessary.
+
+Each public API is documented. Find them in the sidebar.
diff --git a/website/content/06-components-standalone/01-schema/03-plugins/05-prisma.mdx b/website/content/06-components-standalone/01-schema/03-plugins/05-prisma.mdx
index 13e54591a..63d06f6c7 100644
--- a/website/content/06-components-standalone/01-schema/03-plugins/05-prisma.mdx
+++ b/website/content/06-components-standalone/01-schema/03-plugins/05-prisma.mdx
@@ -8,7 +8,7 @@ Refer to the [framework Prisma plugin docs](/plugins/prisma#runtime-integration)
## Installation {docsify-ignore}
-```cli
+```bash-symbol
npm add nexus-prisma
```
@@ -33,7 +33,7 @@ const schema = makeSchema({
You can find runnable examples in the [repo examples folder](https://github.com/graphql-nexus/nexus-schema-plugin-prisma/tree/master/examples).
-> Note: If you're looking for CRUD capabilities, you must enable the `experimentalCRUD` option.
+> **Note**: If you're looking for CRUD capabilities, you must enable the `experimentalCRUD` option.
## Configuration {docsify-ignore}
diff --git a/website/content/06-components-standalone/01-schema/99-fixme.mdx b/website/content/06-components-standalone/01-schema/99-fixme.mdx
deleted file mode 100644
index 5a996fc10..000000000
--- a/website/content/06-components-standalone/01-schema/99-fixme.mdx
+++ /dev/null
@@ -1,55 +0,0 @@
----
-title: __fixme__
----
-
-FIXME this content should be at the parent level
-
-## `@nexus/schema`
-
-```cli
-npm add @nexus/schema
-```
-
-#### Why Nexus?
-
-Words from the original author, Tim Griesser;
-
-Nexus Schema was born out of my experience building several production GraphQL APIs, in different languages and frameworks. The first with vanilla [graphql-js](https://github.com/graphql/graphql-js), another schema-first with [graph.ql](https://github.com/matthewmueller/graph.ql) and later [graphql-tools](https://github.com/apollographql/graphql-tools). Following that with [graphene-python](https://docs.graphene-python.org/en/latest/) and most recently with a bit of [graphql-ruby](http://graphql-ruby.org/).
-
-After working with the toolkits in other scripting languages, it felt like there was a gap in the JavaScript approaches. Schema-first development starts out great, by simply expressing your schema in the GraphQL Schema Definition Language (SDL) and providing resolvers matching to the types as needed you are up and running fast! No need for tons of requires or "overhead" to get a GraphQL server running.
-
-As your schema then grows to hundreds or thousands of types, manually curating these SDL fragments becomes tedious. Documentation changes can be tough. Modifying fields on interfaces can require manual changes to many implementing types, a process that can be quite error prone.
-
-_If only there were a way to combine the simplicity of schema-first development, with the long-term maintainability of a definition-first approach._
-
-GraphQL Nexus aims to fill that void, making the process as simple as possible while also making good use of the runtime to introduce powerful ways of composing types, introducing type or schema wide changes, and much more.
-
-The core idea of GraphQL Nexus draws from basing the schema off the SDL - keeping things declarative and simple to understand. It allows you to reference the type names as string literals rather than always need to import to reference types (you can do that too if you prefer).
-
-By combining automatic type generation with some of the more powerful features of TypeScript - type merging, conditional types, and type inference, we can know exactly which type names we are referring to and able to use throughout our code. We can know both the parameters and the return type of resolvers without providing any type annotation. It takes a little getting used to, but it ends up leading to a great feedback loop of the types annotating themselves.
-
-## Type Generation Details
-
-This is the most important piece to understand to get the most out of Nexus. It is relevant to JavaScript as well as TypeScript users, as tools like VSCode and `// @ts-check` can utilize these types to aid in autocomplete or type-checking. A core goal of Nexus is to have the best possible type coverage with the least possible manual type annotation.
-
-### Overview
-
-Nexus was designed with TypeScript in mind. In order to fully typecheck our GraphQL objects, we need to generate a number of types that combine the schema, any type or field configuration provided, and the GraphQL resolution algorithm to create as much type-safety as possible without any additional work importing and assigning types throughout the codebase.
-
-### Root Types
-
-A **root type** is a type representation of the value used to resolve the fields of an object type. It is the object that will be passed as the first argument of `resolve`. It can be a plain JS object, a database model, a mongoose document, a JS class, anything that fulfills the contract defined by the GraphQL object type, based on the field definitions.
-
-Scalars can also have backing types, representing the value they are parsed into.
-
-Sometimes GraphQL types are passthrough, and don't have a dedicated type backing them. One such case would be in the `Edge` of a Relay style pagination. In this case, Nexus will generate a type-definition which makes assumptions of the necessary value to fulfill the contract. If this is incorrect, you can always provide a concrete type for the object.
-
-### Field Type
-
-A **field type** is the valid return value used to a field on an object type. In GraphQL, promises can be returned at every level of the type resolution, so we wrap the types in a `MaybePromiseDeep` type to express this.
-
-### Configuring our types
-
-The [Ghost Example](https://github.com/prisma-labs/nexus/blob/develop/examples/ghost/src/ghost-schema.ts) is the best to look at for an example of how we're able to capture the types from existing runtime objects or definitions and merge them with our schema.
-
-The `makeSchema` takes several options which helps us find the types we need to import into our generated schema, and customize where these generated types are output.
diff --git a/website/content/06-components-standalone/01-schema/index.mdx b/website/content/06-components-standalone/01-schema/index.mdx
index 6740c5d49..e95731c2e 100644
--- a/website/content/06-components-standalone/01-schema/index.mdx
+++ b/website/content/06-components-standalone/01-schema/index.mdx
@@ -1,3 +1,53 @@
---
-title: '`@nexus/schema`'
+title: '@nexus/schema'
---
+
+## `@nexus/schema`
+
+```bash-symbol
+npm add @nexus/schema
+```
+
+#### Why Nexus?
+
+Words from the original author, Tim Griesser;
+
+Nexus Schema was born out of my experience building several production GraphQL APIs, in different languages and frameworks. The first with vanilla [graphql-js](https://github.com/graphql/graphql-js), another schema-first with [graph.ql](https://github.com/matthewmueller/graph.ql) and later [graphql-tools](https://github.com/apollographql/graphql-tools). Following that with [graphene-python](https://docs.graphene-python.org/en/latest/) and most recently with a bit of [graphql-ruby](http://graphql-ruby.org/).
+
+After working with the toolkits in other scripting languages, it felt like there was a gap in the JavaScript approaches. Schema-first development starts out great, by simply expressing your schema in the GraphQL Schema Definition Language (SDL) and providing resolvers matching to the types as needed you are up and running fast! No need for tons of requires or "overhead" to get a GraphQL server running.
+
+As your schema then grows to hundreds or thousands of types, manually curating these SDL fragments becomes tedious. Documentation changes can be tough. Modifying fields on interfaces can require manual changes to many implementing types, a process that can be quite error prone.
+
+_If only there were a way to combine the simplicity of schema-first development, with the long-term maintainability of a definition-first approach._
+
+GraphQL Nexus aims to fill that void, making the process as simple as possible while also making good use of the runtime to introduce powerful ways of composing types, introducing type or schema wide changes, and much more.
+
+The core idea of GraphQL Nexus draws from basing the schema off the SDL - keeping things declarative and simple to understand. It allows you to reference the type names as string literals rather than always need to import to reference types (you can do that too if you prefer).
+
+By combining automatic type generation with some of the more powerful features of TypeScript - type merging, conditional types, and type inference, we can know exactly which type names we are referring to and able to use throughout our code. We can know both the parameters and the return type of resolvers without providing any type annotation. It takes a little getting used to, but it ends up leading to a great feedback loop of the types annotating themselves.
+
+## Type Generation Details
+
+This is the most important piece to understand to get the most out of Nexus. It is relevant to JavaScript as well as TypeScript users, as tools like VSCode and `// @ts-check` can utilize these types to aid in autocomplete or type-checking. A core goal of Nexus is to have the best possible type coverage with the least possible manual type annotation.
+
+### Overview
+
+Nexus was designed with TypeScript in mind. In order to fully typecheck our GraphQL objects, we need to generate a number of types that combine the schema, any type or field configuration provided, and the GraphQL resolution algorithm to create as much type-safety as possible without any additional work importing and assigning types throughout the codebase.
+
+### Root Types
+
+A **root type** is a type representation of the value used to resolve the fields of an object type. It is the object that will be passed as the first argument of `resolve`. It can be a plain JS object, a database model, a mongoose document, a JS class, anything that fulfills the contract defined by the GraphQL object type, based on the field definitions.
+
+Scalars can also have backing types, representing the value they are parsed into.
+
+Sometimes GraphQL types are passthrough, and don't have a dedicated type backing them. One such case would be in the `Edge` of a Relay style pagination. In this case, Nexus will generate a type-definition which makes assumptions of the necessary value to fulfill the contract. If this is incorrect, you can always provide a concrete type for the object.
+
+### Field Type
+
+A **field type** is the valid return value used to a field on an object type. In GraphQL, promises can be returned at every level of the type resolution, so we wrap the types in a `MaybePromiseDeep` type to express this.
+
+### Configuring our types
+
+The [Ghost Example](https://github.com/prisma-labs/nexus/blob/develop/examples/ghost/src/ghost-schema.ts) is the best to look at for an example of how we're able to capture the types from existing runtime objects or definitions and merge them with our schema.
+
+The `makeSchema` takes several options which helps us find the types we need to import into our generated schema, and customize where these generated types are output.
diff --git a/website/content/06-components-standalone/02-logger/99-fixme.mdx b/website/content/06-components-standalone/02-logger/99-fixme.mdx
deleted file mode 100644
index 397b467d3..000000000
--- a/website/content/06-components-standalone/02-logger/99-fixme.mdx
+++ /dev/null
@@ -1,13 +0,0 @@
----
-title: __fixme__
----
-
-FIXME this content should be at the parent level
-
-# `@nexus/logger`
-
-Delightful logging library that is pretty practical & performant
-
-```cli
-npm add @nexus/logger
-```
diff --git a/website/content/06-components-standalone/02-logger/index.mdx b/website/content/06-components-standalone/02-logger/index.mdx
index 055cf00b0..02d8dadb2 100644
--- a/website/content/06-components-standalone/02-logger/index.mdx
+++ b/website/content/06-components-standalone/02-logger/index.mdx
@@ -1,3 +1,11 @@
---
-title: '`@neuxs/logger`'
+title: '@nexus/logger'
---
+
+## Overview
+
+Delightful logging library that is pretty practical & performant
+
+```bash-symbol
+npm add @nexus/logger
+```
diff --git a/website/content/index.mdx b/website/content/index.mdx
index c8d7d646a..8f17489cf 100644
--- a/website/content/index.mdx
+++ b/website/content/index.mdx
@@ -6,14 +6,4 @@ metaDescription: ''
## Overview
-Welcome to the Nexus documentation! You can find an overview of the available content in the sections below.
-
-## Table of contents
-
----
-
-### Example usage of MDX
-
-Please refer to this page for understanding the MDX docs available:
-
-[Example MDX](getting-started/example)
+Welcome to the Nexus documentation!
diff --git a/website/src/components/customMdx/code.tsx b/website/src/components/customMdx/code.tsx
index c5b870a35..0201458d7 100644
--- a/website/src/components/customMdx/code.tsx
+++ b/website/src/components/customMdx/code.tsx
@@ -196,8 +196,9 @@ const LineNo = styled.span`
const LineContent = styled.span`
padding: 0 1em;
&.break-words {
- display: table-cell;
+ display: inline-table;
white-space: break-spaces;
+ width: 95%;
}
&.token-line {
diff --git a/website/src/components/footer.tsx b/website/src/components/footer.tsx
index bca7eb74f..2a9aae627 100644
--- a/website/src/components/footer.tsx
+++ b/website/src/components/footer.tsx
@@ -126,8 +126,8 @@ const Footer = ({ footerProps }: FooterViewProps) => {
products,
resources,
community,
- company,
- newsletter,
+ /* company,
+ newsletter, */
findus,
} = footerProps
return (
@@ -148,14 +148,14 @@ const Footer = ({ footerProps }: FooterViewProps) => {
{title}