|
| 1 | +--- |
| 2 | +title: Bootstrapping |
| 3 | +id: version-1.0.0-rc.1-bootstrap |
| 4 | +original_id: bootstrap |
| 5 | +--- |
| 6 | + |
| 7 | +After creating our resolvers, type classes, and other business-related code, we need to make our app run. First we have to build the schema, then we can expose it with an HTTP server, WebSockets or even MQTT. |
| 8 | + |
| 9 | +## Create Executable Schema |
| 10 | + |
| 11 | +To create an executable schema from type and resolver definitions, we need to use the `buildSchema` function. |
| 12 | +It takes a configuration object as a parameter and returns a promise of a `GraphQLSchema` object. |
| 13 | + |
| 14 | +In the configuration object we must provide a `resolvers` property, which can be an array of resolver classes: |
| 15 | + |
| 16 | +```typescript |
| 17 | +import { FirstResolver, SecondResolver } from "../app/src/resolvers"; |
| 18 | +// ... |
| 19 | +const schema = await buildSchema({ |
| 20 | + resolvers: [FirstResolver, SecondResolver], |
| 21 | +}); |
| 22 | +``` |
| 23 | + |
| 24 | +Be aware that only operations (queries, mutation, etc.) defined in the resolvers classes (and types directly connected to them) will be emitted in schema. |
| 25 | + |
| 26 | +So if we have defined some object types (that implements an interface type [with disabled auto registering](interfaces.md#registering-in-schema)) but are not directly used in other types definition (like a part of an union, a type of a field or a return type of an operation), we need to provide them manually in `orphanedTypes` options of `buildSchema`: |
| 27 | + |
| 28 | +```typescript |
| 29 | +import { FirstResolver, SecondResolver } from "../app/src/resolvers"; |
| 30 | +import { FirstObject } from "../app/src/types"; |
| 31 | +// ... |
| 32 | +const schema = await buildSchema({ |
| 33 | + resolvers: [FirstResolver, SecondResolver], |
| 34 | + // here provide all the types that are missing in schema |
| 35 | + orphanedTypes: [FirstObject], |
| 36 | +}); |
| 37 | +``` |
| 38 | + |
| 39 | +However, when there are several resolver classes, manual imports can be cumbersome. |
| 40 | +So we can also provide an array of paths to resolver module files instead, which can include globs: |
| 41 | + |
| 42 | +```typescript |
| 43 | +const schema = await buildSchema({ |
| 44 | + resolvers: [__dirname + "/modules/**/*.resolver.{ts,js}", __dirname + "/resolvers/**/*.{ts,js}"], |
| 45 | +}); |
| 46 | +``` |
| 47 | + |
| 48 | +> Be aware that in case of providing paths to resolvers files, TypeGraphQL will emit all the operations and types that are imported in the resolvers files or their dependencies. |
| 49 | +
|
| 50 | +There are also other options related to advanced features like [authorization](authorization.md) or [validation](validation.md) - you can read about them in docs. |
| 51 | + |
| 52 | +To make `await` work, we need to declare it as an async function. Example of `main.ts` file: |
| 53 | + |
| 54 | +```typescript |
| 55 | +import { buildSchema } from "type-graphql"; |
| 56 | + |
| 57 | +async function bootstrap() { |
| 58 | + const schema = await buildSchema({ |
| 59 | + resolvers: [__dirname + "/**/*.resolver.{ts,js}"], |
| 60 | + }); |
| 61 | + |
| 62 | + // other initialization code, like creating http server |
| 63 | +} |
| 64 | + |
| 65 | +bootstrap(); // actually run the async function |
| 66 | +``` |
| 67 | + |
| 68 | +## Create an HTTP GraphQL endpoint |
| 69 | + |
| 70 | +In most cases, the GraphQL app is served by an HTTP server. After building the schema we can create the GraphQL endpoint with a variety of tools such as [`graphql-yoga`](https://github.com/prisma/graphql-yoga) or [`apollo-server`](https://github.com/apollographql/apollo-server). Here is an example using [`apollo-server`](https://github.com/apollographql/apollo-server): |
| 71 | + |
| 72 | +```typescript |
| 73 | +import { ApolloServer } from "apollo-server"; |
| 74 | + |
| 75 | +const PORT = process.env.PORT || 4000; |
| 76 | + |
| 77 | +async function bootstrap() { |
| 78 | + // ... Building schema here |
| 79 | + |
| 80 | + // Create the GraphQL server |
| 81 | + const server = new ApolloServer({ |
| 82 | + schema, |
| 83 | + playground: true, |
| 84 | + }); |
| 85 | + |
| 86 | + // Start the server |
| 87 | + const { url } = await server.listen(PORT); |
| 88 | + console.log(`Server is running, GraphQL Playground available at ${url}`); |
| 89 | +} |
| 90 | + |
| 91 | +bootstrap(); |
| 92 | +``` |
| 93 | + |
| 94 | +Remember to install the `apollo-server` package from npm - it's not bundled with TypeGraphQL. |
| 95 | + |
| 96 | +Of course you can use the `express-graphql` middleware, `graphql-yoga` or whatever you want 😉 |
| 97 | + |
| 98 | +## Create typeDefs and resolvers map |
| 99 | + |
| 100 | +TypeGraphQL provides a second way to generate the GraphQL schema - the `buildTypeDefsAndResolvers` function. |
| 101 | + |
| 102 | +It accepts the same `BuildSchemaOptions` as the `buildSchema` function but instead of an executable `GraphQLSchema`, it creates a typeDefs and resolversMap pair that you can use e.g. with [`graphql-tools`](https://github.com/apollographql/graphql-tools): |
| 103 | + |
| 104 | +```typescript |
| 105 | +import { makeExecutableSchema } from "graphql-tools"; |
| 106 | + |
| 107 | +const { typeDefs, resolvers } = await buildTypeDefsAndResolvers({ |
| 108 | + resolvers: [FirstResolver, SecondResolver], |
| 109 | +}); |
| 110 | + |
| 111 | +const schema = makeExecutableSchema({ typeDefs, resolvers }); |
| 112 | +``` |
| 113 | + |
| 114 | +Or even with other libraries that expect the schema info in that shape, like [`apollo-link-state`](https://github.com/apollographql/apollo-link-state): |
| 115 | + |
| 116 | +```typescript |
| 117 | +import { withClientState } from "apollo-link-state"; |
| 118 | + |
| 119 | +const { typeDefs, resolvers } = await buildTypeDefsAndResolvers({ |
| 120 | + resolvers: [FirstResolver, SecondResolver], |
| 121 | +}); |
| 122 | + |
| 123 | +const stateLink = withClientState({ |
| 124 | + // ...other options like `cache` |
| 125 | + typeDefs, |
| 126 | + resolvers, |
| 127 | +}); |
| 128 | + |
| 129 | +// ...the rest of `ApolloClient` initialization code |
| 130 | +``` |
| 131 | + |
| 132 | +Be aware that some of the TypeGraphQL features (i.a. [query complexity](complexity.md)) might not work with the `buildTypeDefsAndResolvers` approach because they use some low-level `graphql-js` features. |
0 commit comments