Merge pull request rubengrill#2 from rubengrill/cra-examples

CRA examples

Author: rubengrill

.eslintignore

@@ -1,3 +1,3 @@
-examples/docs/apolloMock.js
-examples/docs/codegenTypedDocuments.d.ts
-examples/docs/codegenTypes.ts
+examples/**/apolloMock.js
+examples/**/codegenTypedDocuments.d.ts
+examples/**/codegenTypes.d.ts

.prettierignore

@@ -1,3 +1,4 @@
-examples/docs/apolloMock.js
-examples/docs/codegenTypedDocuments.d.ts
-examples/docs/codegenTypes.ts
+examples/**/apolloMock.js
+examples/**/codegenTypedDocuments.d.ts
+examples/**/codegenTypes.d.ts
+README.md

README.md

@@ -20,57 +20,62 @@ The difference is that is uses generic types, so that you have type safety with
 
 ### Install
 
+```sh
+$ yarn add @graphql-codegen/add @graphql-codegen/typescript @graphql-codegen/typescript-operations
+$ yarn add apollo-typed-documents
+```
+
 `codegen.yml`:
 
 <!-- AUTO-GENERATED-CONTENT:START (CODE:src=./examples/docs/codegenTypedDocuments.yml) -->
 <!-- The below code snippet is automatically added from ./examples/docs/codegenTypedDocuments.yml -->
 ```yml
-schema: ./schema.graphql
-documents: ./documents/*.graphql
+schema: schema.graphql
+documents: src/**/*.graphql
 generates:
-  ./codegenTypedDocuments.d.ts:
+  ./src/codegenTypedDocuments.d.ts:
     plugins:
       - apollo-typed-documents/lib/codegenTypedDocuments
     config:
       typesModule: "@codegen-types"
-  ./codegenTypes.ts:
+  ./src/codegenTypes.d.ts:
     plugins:
+      - add: 'declare module "@codegen-types" {'
+      - add:
+          placement: append
+          content: "}"
       - typescript
       - typescript-operations
 ```
 <!-- AUTO-GENERATED-CONTENT:END -->
 
 `tsconfig.json`:
 
+Add `node_modules/apollo-typed-documents/lib/reactHooks.d.ts` in `include` to override the typings for `@apollo/react-hooks`, so that types can be inferred from typed documents.
+
+<!-- AUTO-GENERATED-CONTENT:START (CODE:src=./examples/docs/tsconfig.json) -->
+<!-- The below code snippet is automatically added from ./examples/docs/tsconfig.json -->
 ```json
 {
   "compilerOptions": {
-    "baseUrl": ".",
-    "paths": {
-      "@codegen-types": ["codegenTypes.ts"],
-      "@apollo/react-hooks": [
-        "./node_modules/apollo-typed-documents/lib/reactHooks.d.ts"
-      ]
-    }
-  }
+    "noEmit": true,
+    "allowJs": true,
+    "checkJs": true,
+    "strict": true,
+    "jsx": "react",
+    "esModuleInterop": true
+  },
+  "include": ["src", "node_modules/apollo-typed-documents/lib/reactHooks.d.ts"]
 }
 ```
-
-`@codegen-types` points to the output of `typescript-operations` graphql-codegen plugin.
-
-This alias is required, because in ambient module declarations (`.d.ts`) only non relative imports are allowed.
-
-`@apollo/react-hooks` overrides the types to have generic hooks in your code: [reference](src/reactHooks.ts)
-
-If you don't have a TypeScript project but instead just want to get type safety and code completion,
-the configuration needs to have more options set: [reference](examples/docs/tsconfig.json)
+<!-- AUTO-GENERATED-CONTENT:END -->
 
 ### Example
 
-`./documents/authors.graphql`:
+`src/authors.graphql`:
 
-<!-- AUTO-GENERATED-CONTENT:START (CODE:src=./examples/docs/documents/authors.graphql) -->
-<!-- The below code snippet is automatically added from ./examples/docs/documents/authors.graphql -->
+<!-- AUTO-GENERATED-CONTENT:START (CODE:src=./examples/docs/src/authors.graphql) -->
+<!-- The below code snippet is automatically added from ./examples/docs/src/authors.graphql -->
 ```graphql
 query authors {
   authors {
@@ -86,10 +91,10 @@ query authors {
 ```
 <!-- AUTO-GENERATED-CONTENT:END -->
 
-`./documents/createAuthor.graphql`:
+`src/createAuthor.graphql`:
 
-<!-- AUTO-GENERATED-CONTENT:START (CODE:src=./examples/docs/documents/createAuthor.graphql) -->
-<!-- The below code snippet is automatically added from ./examples/docs/documents/createAuthor.graphql -->
+<!-- AUTO-GENERATED-CONTENT:START (CODE:src=./examples/docs/src/createAuthor.graphql) -->
+<!-- The below code snippet is automatically added from ./examples/docs/src/createAuthor.graphql -->
 ```graphql
 mutation createAuthor($input: AuthorInput!) {
   createAuthor(input: $input) {
@@ -105,10 +110,10 @@ mutation createAuthor($input: AuthorInput!) {
 ```
 <!-- AUTO-GENERATED-CONTENT:END -->
 
-`./codegenTypedDocuments.d.ts` (generated):
+`src/codegenTypedDocuments.d.ts` (generated):
 
-<!-- AUTO-GENERATED-CONTENT:START (CODE:src=./examples/docs/codegenTypedDocuments.d.ts) -->
-<!-- The below code snippet is automatically added from ./examples/docs/codegenTypedDocuments.d.ts -->
+<!-- AUTO-GENERATED-CONTENT:START (CODE:src=./examples/docs/src/codegenTypedDocuments.d.ts) -->
+<!-- The below code snippet is automatically added from ./examples/docs/src/codegenTypedDocuments.d.ts -->
 ```ts
 declare module "*/authors.graphql" {
   import { TypedDocumentNode } from "apollo-typed-documents";
@@ -126,16 +131,16 @@ declare module "*/createAuthor.graphql" {
 ```
 <!-- AUTO-GENERATED-CONTENT:END -->
 
-`./AuthorList.js`:
+`src/AuthorList.js`:
 
-<!-- AUTO-GENERATED-CONTENT:START (CODE:src=./examples/docs/AuthorList.js) -->
-<!-- The below code snippet is automatically added from ./examples/docs/AuthorList.js -->
+<!-- AUTO-GENERATED-CONTENT:START (CODE:src=./examples/docs/src/AuthorList.js) -->
+<!-- The below code snippet is automatically added from ./examples/docs/src/AuthorList.js -->
 ```js
 import { useMutation, useQuery } from "@apollo/react-hooks";
 import React from "react";
 
-import authorsQuery from "./documents/authors.graphql";
-import createAuthorMutation from "./documents/createAuthor.graphql";
+import authorsQuery from "./authors.graphql";
+import createAuthorMutation from "./createAuthor.graphql";
 
 const AuthorList = () => {
   // Type of `data` is inferred (AuthorsQuery)
@@ -169,24 +174,26 @@ export default AuthorList;
 
 ### Notes for `create-react-app` users
 
-`create-react-app` uses `graphql.macro` for loading of `.graphql` files (https://create-react-app.dev/docs/loading-graphql-files/).
+`create-react-app` supports `graphql.macro` for loading `.graphql` files (https://create-react-app.dev/docs/loading-graphql-files/).
 
-Because the `codegenTypedDocuments` plugin generates ambient module declarations for those `.graphql` files, they must be imported as regular modules (`commonjs`), otherwise TypeScript can't know its type.
+The `codegenTypedDocuments` plugin generates ambient module declarations for `.graphql` files, which means that `.graphql` files must be imported as regular modules (`import` syntax) so that TypeScript knows about the types.
 
-You can use the babel plugin `babel-plugin-import-graphql`, but then you need to either `eject` or use `react-app-rewired`/`customize-cra`.
+You can use the babel plugin `babel-plugin-import-graphql` (https://github.com/detrohutt/babel-plugin-import-graphql), but then you need to use `react-app-rewired` (https://github.com/timarney/react-app-rewired/) and `customize-cra` (https://github.com/arackaf/customize-cra) so that you can define custom babel plugins.
 
-Follow install instructions for `react-app-rewired`/`customize-cra`:
+```sh
+$ yarn add react-app-rewired customize-cra
+$ yarn add babel-plugin-import-graphql
+```
 
-- https://github.com/timarney/react-app-rewired/
-- https://github.com/arackaf/customize-cra
+`config-overrides.js`
 
-Install `babel-plugin-import-graphql`
+```js
+const { override, useBabelRc } = require("customize-cra");
 
-```
-$ yarn add babel-plugin-import-graphql
+module.exports = override(useBabelRc());
 ```
 
-Add to `.babelrc`:
+`.babelrc`
 
 ```json
 {
@@ -195,58 +202,57 @@ Add to `.babelrc`:
 }
 ```
 
-Also, if you have a `create-react-app` project without TypeScript, the `tsconfig.json` must not be placed in your app root folder, because `create-react-app` uses this file to detect a TypeScript project: [reference](https://github.com/facebook/create-react-app/blob/v3.4.1/packages/react-scripts/scripts/utils/verifyTypeScriptSetup.js#L49).
+`package.json`
+
+```js
+"scripts": {
+  "start": "react-app-rewired start",
+  "build": "react-app-rewired build",
+  "test": "react-app-rewired test",
+  ...
+}
+```
 
-All `.ts`/`.d.ts` files must be outside of your `src` folder: [reference](https://github.com/facebook/create-react-app/blob/v3.4.1/packages/react-scripts/scripts/utils/verifyTypeScriptSetup.js#L50)
+If you have a TypeScript app, you need to override the `@apollo/react-hooks` types in `tsconfig.json`:
 
-A solution is to put the `tsconfig.json` in the parent folder:
+`tsconfig.json`
 
-```
-tsconfig.json
-backend/
-frontend/
-  codegen.yml
-  codegenTypedDocuments.d.ts
-  codegenTypes.ts
-  src/
-    apolloMock.js
+```js
+{
+  "compilerOptions": {
     ...
+  },
+  "include": ["src", "node_modules/apollo-typed-documents/lib/reactHooks.d.ts"]
+}
 ```
 
-An example `tsconfig.json`:
+If you don't have a TypeScript app (you just want TypeScript support within your IDE) you can't create a `tsconfig.json` in your app folder, because `create-react-app` uses that file to detect if this is a TypeScript project.
 
+Instead, you have to create the `tsconfig.json` in your `src` folder:
+
+`src/tsconfig.json`
+
+<!-- AUTO-GENERATED-CONTENT:START (CODE:src=./examples/cra/src/tsconfig.json) -->
+<!-- The below code snippet is automatically added from ./examples/cra/src/tsconfig.json -->
 ```json
 {
-  "comment": "File is in root folder so that create-react-app doesn't detect a typescript app",
   "compilerOptions": {
-    "rootDir": "frontend",
-    "typeRoots": ["frontend/node_modules/@types"],
-    "baseUrl": "frontend",
-    "paths": {
-      "@codegen-types": ["codegenTypes.ts"],
-      "@apollo/react-hooks": [
-        "node_modules/apollo-typed-documents/lib/reactHooks.d.ts"
-      ]
-    },
+    "noEmit": true,
     "allowJs": true,
     "checkJs": true,
-    "noEmit": true,
+    "strict": true,
     "jsx": "react",
-    "esModuleInterop": true,
-    "moduleResolution": "node",
-    "alwaysStrict": true,
-    "strictNullChecks": true,
-    "target": "ES2018"
+    "esModuleInterop": true
   },
-  "include": [
-    "frontend/src/**/*",
-    "frontend/*.ts",
-    "frontend/*.d.ts",
-    "frontend/node_modules/react-scripts/lib/react-app.d.ts",
-    "frontend/node_modules/babel-plugin-react-intl-auto/types.d.ts"
-  ]
+  "include": [".", "../node_modules/apollo-typed-documents/lib/reactHooks.d.ts"]
 }
 ```
+<!-- AUTO-GENERATED-CONTENT:END -->
+
+Please see the following example projects for more details:
+
+- [`create-react-app` with TypeScript](examples/cra-ts)
+- [`create-react-app` without TypeScript](examples/cra)
 
 ## codegenApolloMock
 
@@ -270,23 +276,27 @@ When used together with `codegenTypedDocuments` the data and variables are type
 
 ### Install
 
+```sh
+$ yarn add apollo-typed-documents
+```
+
 `codegen.yml`
 
 <!-- AUTO-GENERATED-CONTENT:START (CODE:src=./examples/docs/codegenApolloMock.yml) -->
 <!-- The below code snippet is automatically added from ./examples/docs/codegenApolloMock.yml -->
 ```yml
-schema: ./schema.graphql
-documents: ./documents/*.graphql
+schema: schema.graphql
+documents: src/**/*.graphql
 generates:
-  ./apolloMock.js:
+  ./src/apolloMock.js:
     plugins:
       - apollo-typed-documents/lib/codegenApolloMock
 ```
 <!-- AUTO-GENERATED-CONTENT:END -->
 
 ### Example
 
-`./schema.graphql`:
+`schema.graphql`:
 
 <!-- AUTO-GENERATED-CONTENT:START (CODE:src=./examples/docs/schema.graphql) -->
 <!-- The below code snippet is automatically added from ./examples/docs/schema.graphql -->
@@ -328,10 +338,10 @@ schema {
 ```
 <!-- AUTO-GENERATED-CONTENT:END -->
 
-`./documents/authors.graphql`:
+`src/authors.graphql`:
 
-<!-- AUTO-GENERATED-CONTENT:START (CODE:src=./examples/docs/documents/authors.graphql) -->
-<!-- The below code snippet is automatically added from ./examples/docs/documents/authors.graphql -->
+<!-- AUTO-GENERATED-CONTENT:START (CODE:src=./examples/docs/src/authors.graphql) -->
+<!-- The below code snippet is automatically added from ./examples/docs/src/authors.graphql -->
 ```graphql
 query authors {
   authors {
@@ -347,10 +357,10 @@ query authors {
 ```
 <!-- AUTO-GENERATED-CONTENT:END -->
 
-`./documents/createAuthor.graphql`:
+`src/createAuthor.graphql`:
 
-<!-- AUTO-GENERATED-CONTENT:START (CODE:src=./examples/docs/documents/createAuthor.graphql) -->
-<!-- The below code snippet is automatically added from ./examples/docs/documents/createAuthor.graphql -->
+<!-- AUTO-GENERATED-CONTENT:START (CODE:src=./examples/docs/src/createAuthor.graphql) -->
+<!-- The below code snippet is automatically added from ./examples/docs/src/createAuthor.graphql -->
 ```graphql
 mutation createAuthor($input: AuthorInput!) {
   createAuthor(input: $input) {
@@ -366,18 +376,18 @@ mutation createAuthor($input: AuthorInput!) {
 ```
 <!-- AUTO-GENERATED-CONTENT:END -->
 
-`./apolloMock.js` (generated):
+`src/apolloMock.js` (generated):
 
-See: [reference](examples/docs/apolloMock.js)
+See: [reference](examples/docs/src/apolloMock.js)
 
-`./apolloMock.test.js`:
+`src/apolloMock.test.js`:
 
-<!-- AUTO-GENERATED-CONTENT:START (CODE:src=./examples/docs/apolloMock.test.js) -->
-<!-- The below code snippet is automatically added from ./examples/docs/apolloMock.test.js -->
+<!-- AUTO-GENERATED-CONTENT:START (CODE:src=./examples/docs/src/apolloMock.test.js) -->
+<!-- The below code snippet is automatically added from ./examples/docs/src/apolloMock.test.js -->
 ```js
 import apolloMock from "./apolloMock";
-import authors from "./documents/authors.graphql";
-import createAuthor from "./documents/createAuthor.graphql";
+import authors from "./authors.graphql";
+import createAuthor from "./createAuthor.graphql";
 
 describe("apolloMock", () => {
   it("produces the minimal output that is valid according to graphql schema", () => {

examples/cra-ts/.babelrc

@@ -0,0 +1,4 @@
+{
+  "presets": ["react-app"],
+  "plugins": ["babel-plugin-import-graphql"]
+}