docs(wiki): workshop

Author: Kian Khoshnoodpour

internals/wiki/00-development-environment.md

@@ -0,0 +1,12 @@
+# Setting up your development environment
+
+This part is optional, you can use your own development environment and tools.
+
+The development environment described here is the most commonly used one and the one we recommend.
+
+1. Download and install [Visual Studio Code](https://code.visualstudio.com/) together with the [GraphQL plugin](https://marketplace.visualstudio.com/items?itemName=Prisma.vscode-graphql).
+1. Clone the [repository](https://kkhoshnoodpour@scm.ecom.ahold.nl/stash/scm/~maarten.van.oudenniel/sandbox-graphql.git).
+1. Run `yarn` from the root folder of the cloned folder
+1. Open the cloned folder using VSCode
+
+Now we're all set to use GraphQL!

internals/wiki/01-my-first-query.md

@@ -0,0 +1,153 @@
+# Chapter 1: My first query
+
+> [Frontend, Backend]
+
+In this assignment we're going to add a new query that we can use in our application. We do this by:
+
+1. Defining a new query and type in the GraphQL schema
+1. Implementing the resolver logic that actually gets and returns the data
+
+Let's get started!
+
+Create a new branch from `master`
+
+```
+git checkout -b graphql-tutorial
+```
+
+Then start the application.
+
+```sh
+yarn dev
+```
+
+## Assignment 1.1: Add a new query to the GraphQL schema
+
+The GraphQL schema is the complete definition of the GraphQL API. Similar to swagger documentation it tells the developer what operations (queries) they can perform. And what the return types are for these operations.
+
+Our demo application uses NextJS and its convention to store the schema in: `pages/api/graphql/schema.ts`.
+
+**Update this file to contain**:
+
+- A new type that defines what we want to show in our UI. Examples of types could be: A favorite list, a product, an order
+- A new query that returns a collection
+
+Assuming you started the application before saving the file, you will see that the running process will pickup your changes and update the files:
+
+- `_schema.graphql`
+- `codegen/_graphql.tsx`
+- `codegen/_resolvers.tsx`
+
+> Alternatively you can run the command: `yarn generate` to manually run the update. These files are auto-generated from the GraphQL schema. And are used to strongly-type the application, as well as provide utility functions we can use in our app. For more information on how this works see the `codegen` section in the setup docs.
+
+In these files you should now see the generated GraphQL definitions and TypeScript types that were generated based on what you defined in `schema.ts`.
+
+## Assignment 1.2: Implement the resolver logic for our new query
+
+Now that we have our query and type in place, we have to write the code that gets the data and returns it.
+
+**Open the file `pages/api/graphql/resolvers.ts`**
+
+If you're running the app your editor should already tell you there's something wrong in this file, **The new query we just added isn't included in the resolver**.
+
+Add the missing query, using the exact same name used as in the `schema.ts` file. Return an array of your defined object.
+
+## Assignment 1.3: Run your query in the playground
+
+Now you should be able to run your query in the GraphQL playground environment: <http://localhost:3000/api/graphql>.
+
+> The playground provides an environment to test queries. It includes auto-complete, as you start typing it will provide suggestions. Click on the `schema` button on the right to see the entire schema.
+
+Enter your query then, click the run button and see your data!
+
+> GraphQL supports _query-what-you-need_, removing fields from your query will prevent that data being sent to you.
+
+Do you see data? Great! You just wrote your first query.
+
+If you didn't. No worries, check out the solution for a working example. Try to fix your code by looking at the example. You can also use the solution branch from chapter 1 to continue with chapter 2.
+
+# Chapter 1 - Solution: My first query
+
+Branch `chapter-1-solution`
+
+A possible solution would be to display the users favorite lists. Users create favorite lists to store their favorite products. When they're shopping they can use their favorite lists to fill their shopping cart quickly.
+
+## Assignment 1.1 - Solution: Add a new query to the GraphQL schema
+
+For our query and type we defined the following in
+
+`pages/api/graphql/schema.ts`:
+
+```
+# all our queries are defined on the type Query
+type Query {
+ """
+ Have a simple example
+ """
+ simple: String
+ """
+ Get all the favorite lists this user has made
+ """
+ lists: [List!]
+}
+
+"""
+Favorite list
+"""
+type List {
+ """
+ Id of list
+ """
+ id: Int! # a field named id with type integer that may not be null
+ """
+ Description entered by user
+ """
+ description: String!
+}
+```
+
+We have two types: **Query** and **List**.
+
+All queries must be defined under the **Query** type.
+
+Custom types get their own type definition.
+
+## Assignment 1.2 - Solution: Implement the resolver logic for our new query
+
+To implement the resolver logic we return some mocked data
+
+`pages/api/graphql/resolvers.ts`
+
+```typescript
+const query: QueryResolvers = {
+ simple: () => {
+ console.log('[server] GraphQL server query: simple');
+ return 'Welcome to the AH GraphQL workshop';
+ },
+ lists: () => [
+ {
+ id: 0,
+ description: 'Shopping List',
+ },
+ {
+ id: 1,
+ description: 'Chocolate',
+ },
+ ],
+};
+```
+
+## Assignment 1.3 - Solution: Run your query in the playground
+
+Now we can query the fields on type **List** from the playground, using the **lists** query.
+
+<http://localhost:3000/api/graphql>:
+
+```graphql
+{
+ lists {
+ id
+ description
+ }
+}
+```

internals/wiki/02-calling-graphql-from-react.md

@@ -0,0 +1,214 @@
+# Chapter 2 - Calling GraphQL from React
+
+> [Frontend]
+
+In this chapter we'll use the GraphQL query we defined in chapter 1 and display it in our React application.
+
+## Assignment 2.1: Write the query
+
+Create a new module folder in `modules/my-module` and add a file called `query.graphql`
+
+`modules/my-module/query.graphql`
+
+In this file we're going to write our first query. We write the query in GraphQL, when writing queries in our application we have to name our query:
+
+```graphql
+query myQuery {
+ ...the_actual_query
+}
+```
+
+For example, taking the schema from the `chapter-1-solution` our query could look like this:
+
+```graphql
+query lists {
+ lists {
+ id
+ description
+ }
+}
+```
+
+> If you're using VSCode together with the GraphQL plugin you will get auto-complete suggestions in the editor as you're typing queries. Use cmd+space to trigger suggestions manually.
+
+After saving this file, the running application will pick up the changes and generate TypeScript types and React hooks. These can be found in: `codegen/graphql.tsx`. We'll be using these hooks and types to build our UI. See the appendix to learn more about code generation.
+
+## Assignment 2.2: Use the query in a component
+
+Next let's create a component and display our data. Create a React component:
+
+`modules/my-module/my-component.tsx`
+
+A blank component looks like this:
+
+```tsx
+import React from 'react';
+
+export const MyComponent: React.FC = () => {
+ return null;
+};
+```
+
+Now we can the generated React hook imported from `schema/graphql.tsx` to connect to GraphQL:
+
+```ts
+import { useMyQuery } from '../../codegen/_graphql';
+
+// add to the body of your component
+const { loading, error, data } = useMyQuery();
+```
+
+The generated hook among others will give you 3 state variables: `loading`, `error`, `data`. These state variables describe the state of the GraphQL query you're trying to perform.
+
+> Tip: Write down `,[space]` after `data` and press `ctrl+space` to get suggestions for other values you can use.
+
+You can use these state variables to determine what to display, for instance you can show a loading spinner if the query is still running and hasn't received data. Or you can display an error message. For example:
+
+```tsx
+if (loading) {
+ return <p>Loading...</p>;
+}
+
+if (error) {
+ return <p>Error: {error}</p>;
+}
+
+if (!data || !data.queryName) {
+ return <p>Erorr: Unknown</p>;
+}
+
+return; // do something with the data
+```
+
+To style the components you can either use [styled components](https://styled-components.com/docs) or include the css as a style attribute on the JSX element:
+
+```tsx
+// using styled components
+import styled from 'styled-components';
+
+// we define a simple box
+const Box = styled.div`
+ padding: 8px;
+ margin: 0 0 24px;
+ border: 1px solid #eee;
+`;
+
+// or just use the style tag:
+<div
+ style={{
+ padding: '8px',
+ margin: '0 0 24px',
+ border: '1px solid #eee',
+ }}
+>
+ ...your content
+</div>;
+```
+
+To finish the assignment display your data in some way in the component. Then create another component in `pages` and use your newly created component:
+
+`pages/my-page.tsx`
+
+```tsx
+import { NextPage } from 'next';
+import { withApollo } from '../lib/apollo';
+import { MyComponent } from '../modules/my-module/my-component';
+
+const MyPage: NextPage = () => {
+ return <MyComponent />;
+};
+
+// be sure to include this line
+export default withApollo(MyPage);
+```
+
+You can now see your page, component and hopefully your data from GraphQL at <http://localhost:3000/my-page>.
+
+# Chapter 2 - Solution: Calling GraphQL from React
+
+Branch `chapter-2-solution`
+
+Continued from the solution from chapter 1 on branch `chapter-1-solution`.
+
+## Assignment 2.1 - Solution: Write the query
+
+We create a query to retrieve all our favorite lists:
+
+`modules/list/lists.graphql`
+
+```graphql
+query lists {
+ lists {
+ id
+ description
+ }
+}
+```
+
+## Assignment 2.2 - Solution: Use the query in a component
+
+Next we create a component that displays all the favorite lists in a box.
+
+`modules/list/list-overview.tsx`
+
+```tsx
+import React from 'react';
+import styled from 'styled-components';
+// we're importing a generated React hook
+// the hook is actually a wrapper around the useQuery hook found in the apollo client
+import { useListsQuery } from '../../codegen/_graphql';
+
+// create a simple box to show our data in using styled components
+const List = styled.div`
+ padding: 8px;
+ margin: 0 0 24px;
+ border: 1px solid #eee;
+`;
+
+export const ListOverview: React.FC = () => {
+ // the hook performs the call to the graphql server
+ // and gives us state variables that we can use in our app
+ const { loading, error, data } = useListsQuery();
+
+ // we can decide what to show based on the state
+ if (loading) {
+ return <p>Loading...</p>;
+ }
+
+ if (error) {
+ return <p>Error: {error}</p>;
+ }
+
+ if (!data || !data.lists) {
+ return <p>Erorr: Unknown</p>;
+ }
+
+ // and tells us when we really have data
+ // now we really have data that we can use
+ return (
+ <>
+ {data.lists.map((list) => (
+ <List key={list.id}>{list.description}</List>
+ ))}
+ </>
+ );
+};
+```
+
+Finally we create a page.
+
+`pages/favorites.tsx`:
+
+```tsx
+import { NextPage } from 'next';
+import { withApollo } from '../lib/apollo';
+import { ListOverview } from '../modules/list/list-overview';
+
+const ListsPage: NextPage = () => {
+ return <ListOverview />;
+};
+
+export default withApollo(ListsPage);
+```
+
+Now we can go to <http://localhost:3000/favorites> and see all the users favorite lists in a nice box.