|
| 1 | +# <a href='https://www.apollographql.com/'><img src='https://user-images.githubusercontent.com/841294/53402609-b97a2180-39ba-11e9-8100-812bab86357c.png' height='100' alt='Apollo Server'></a> |
| 2 | +## A TypeScript GraphQL Server for Express, Koa, Hapi, Lambda, and more. |
| 3 | + |
| 4 | +[](https://badge.fury.io/js/apollo-server-core) |
| 5 | +[](https://circleci.com/gh/apollographql/apollo-server/tree/main) |
| 6 | +[](https://community.apollographql.com) |
| 7 | +[](https://github.com/apollographql/apollo-server/blob/HEAD/CHANGELOG.md) |
| 8 | + |
| 9 | +Apollo Server is a community-maintained open-source GraphQL server. It works with many Node.js HTTP server frameworks, or can run on its own with a built-in Express server. Apollo Server works with any GraphQL schema built with [GraphQL.js](https://github.com/graphql/graphql-js)--or define a schema's type definitions using schema definition language (SDL). |
| 10 | + |
| 11 | +[Read the documentation](https://www.apollographql.com/docs/apollo-server/) for information on getting started and many other use cases and [follow the CHANGELOG](https://github.com/apollographql/apollo-server/blob/HEAD/CHANGELOG.md) for updates. |
| 12 | + |
| 13 | +## Principles |
| 14 | + |
| 15 | +Apollo Server is built with the following principles in mind: |
| 16 | + |
| 17 | +- **By the community, for the community**: Its development is driven by the needs of developers. |
| 18 | +- **Simplicity**: By keeping things simple, it is more secure and easier to implement and contribute. |
| 19 | +- **Performance**: It is well-tested and production-ready. |
| 20 | + |
| 21 | +Anyone is welcome to contribute to Apollo Server, just read [CONTRIBUTING.md](./CONTRIBUTING.md), take a look at the [roadmap](./ROADMAP.md) and make your first PR! |
| 22 | + |
| 23 | +## Getting started |
| 24 | + |
| 25 | +To get started with Apollo Server: |
| 26 | + |
| 27 | +* Install with `npm install apollo-server-<integration> graphql` |
| 28 | +* Write a GraphQL schema |
| 29 | +* Use one of the following snippets |
| 30 | + |
| 31 | +There are two ways to install Apollo Server: |
| 32 | + |
| 33 | +* **[Standalone](#installation-standalone)**: For applications that do not require an existing web framework, use the `apollo-server` package. |
| 34 | +* **[Integrations](#installation-integrations)**: For applications with a web framework (e.g. `express`, `koa`, `hapi`, etc.), use the appropriate Apollo Server integration package. |
| 35 | + |
| 36 | +For more info, please refer to the [Apollo Server docs](https://www.apollographql.com/docs/apollo-server/v2). |
| 37 | + |
| 38 | +### Installation: Standalone |
| 39 | + |
| 40 | +In a new project, install the `apollo-server` and `graphql` dependencies using: |
| 41 | + |
| 42 | + npm install apollo-server graphql |
| 43 | + |
| 44 | +Then, create an `index.js` which defines the schema and its functionality (i.e. resolvers): |
| 45 | + |
| 46 | +```js |
| 47 | +const { ApolloServer, gql } = require('apollo-server'); |
| 48 | + |
| 49 | +// The GraphQL schema |
| 50 | +const typeDefs = gql` |
| 51 | + type Query { |
| 52 | + "A simple type for getting started!" |
| 53 | + hello: String |
| 54 | + } |
| 55 | +`; |
| 56 | + |
| 57 | +// A map of functions which return data for the schema. |
| 58 | +const resolvers = { |
| 59 | + Query: { |
| 60 | + hello: () => 'world', |
| 61 | + }, |
| 62 | +}; |
| 63 | + |
| 64 | +const server = new ApolloServer({ |
| 65 | + typeDefs, |
| 66 | + resolvers, |
| 67 | +}); |
| 68 | + |
| 69 | +server.listen().then(({ url }) => { |
| 70 | + console.log(`🚀 Server ready at ${url}`); |
| 71 | +}); |
| 72 | +``` |
| 73 | + |
| 74 | +> Due to its human-readability, we recommend using [schema-definition language (SDL)](https://www.apollographql.com/docs/apollo-server/essentials/schema/#schema-definition-language) to define a GraphQL schema--[a `GraphQLSchema` object from `graphql-js`](https://github.com/graphql/graphql-js/#using-graphqljs) can also be specified instead of `typeDefs` and `resolvers` using the `schema` property: |
| 75 | +> |
| 76 | +> ```js |
| 77 | +> const server = new ApolloServer({ |
| 78 | +> schema: ... |
| 79 | +> }); |
| 80 | +> ``` |
| 81 | +
|
| 82 | +Finally, start the server using `node index.js` and go to the URL returned on the console. |
| 83 | +
|
| 84 | +For more details, check out the Apollo Server [Getting Started guide](https://www.apollographql.com/docs/apollo-server/getting-started.html) and the [fullstack tutorial](https://www.apollographql.com/docs/tutorial/introduction.html). |
| 85 | +
|
| 86 | +For questions, the [Apollo community forum](https://community.apollographql.com) is a great place to get help. |
| 87 | +
|
| 88 | +## Installation: Integrations |
| 89 | +
|
| 90 | +While the standalone installation above can be used without making a decision about which web framework to use, the Apollo Server integration packages are paired with specific web frameworks (e.g. Express, Koa, hapi). |
| 91 | +
|
| 92 | +The following web frameworks have Apollo Server integrations, and each of these linked integrations has its own installation instructions and examples on its package `README.md`: |
| 93 | +
|
| 94 | +- [Express](https://github.com/apollographql/apollo-server/tree/main/packages/apollo-server-express) _(Most popular)_ |
| 95 | +- [Koa](https://github.com/apollographql/apollo-server/tree/main/packages/apollo-server-koa) |
| 96 | +- [Hapi](https://github.com/apollographql/apollo-server/tree/main/packages/apollo-server-hapi) |
| 97 | +- [Fastify](https://github.com/apollographql/apollo-server/tree/main/packages/apollo-server-fastify) |
| 98 | +- [Amazon Lambda](https://github.com/apollographql/apollo-server/tree/main/packages/apollo-server-lambda) |
| 99 | +- [Micro](https://github.com/apollographql/apollo-server/tree/main/packages/apollo-server-micro) |
| 100 | +- [Azure Functions](https://github.com/apollographql/apollo-server/tree/main/packages/apollo-server-azure-functions) |
| 101 | +- [Google Cloud Functions](https://github.com/apollographql/apollo-server/tree/main/packages/apollo-server-cloud-functions) |
| 102 | +- [Cloudflare](https://github.com/apollographql/apollo-server/tree/main/packages/apollo-server-cloudflare) _(Experimental)_ |
| 103 | +
|
| 104 | +## Context |
| 105 | +
|
| 106 | +A request context is available for each request. When `context` is defined as a function, it will be called on each request and will receive an object containing a `req` property, which represents the request itself. |
| 107 | +
|
| 108 | +By returning an object from the `context` function, it will be available as the third positional parameter of the resolvers: |
| 109 | +
|
| 110 | +```js |
| 111 | +new ApolloServer({ |
| 112 | + typeDefs, |
| 113 | + resolvers: { |
| 114 | + Query: { |
| 115 | + books: (parent, args, context, info) => { |
| 116 | + console.log(context.myProperty); // Will be `true`! |
| 117 | + return books; |
| 118 | + }, |
| 119 | + } |
| 120 | + }, |
| 121 | + context: async ({ req }) => { |
| 122 | + return { |
| 123 | + myProperty: true |
| 124 | + }; |
| 125 | + }, |
| 126 | +}) |
| 127 | +``` |
| 128 | +
|
| 129 | +## Documentation |
| 130 | + |
| 131 | +The [Apollo Server documentation](https://apollographql.com/docs/apollo-server/) contains additional details on how to get started with GraphQL and Apollo Server. |
| 132 | + |
| 133 | +The raw Markdown source of the documentation is available within the `docs/` directory of this monorepo--to contribute, please use the _Edit on GitHub_ buttons at the bottom of each page. |
| 134 | + |
| 135 | +## Development |
| 136 | + |
| 137 | +If you wish to develop or contribute to Apollo Server, we suggest the following: |
| 138 | + |
| 139 | +- Fork this repository |
| 140 | + |
| 141 | +- Install [Direnv](https://direnv.net/) (a tool that automatically sets up environment variables in project directories) or [nvm](https://github.com/nvm-sh/nvm). We use nvm to ensure we're running the expected version of Node (and we use Direnv to install and run nvm automatically). |
| 142 | + |
| 143 | +- Install the Apollo Server project on your computer |
| 144 | + |
| 145 | +``` |
| 146 | +git clone https://github.com/[your-user]/apollo-server |
| 147 | +cd apollo-server |
| 148 | +direnv allow # sets up nvm for you; if you installed nvm yourself, try `nvm install` instead |
| 149 | +``` |
| 150 | + |
| 151 | +- Build and test |
| 152 | + |
| 153 | +``` |
| 154 | +npm install |
| 155 | +npm test |
| 156 | +``` |
| 157 | + |
| 158 | +- To run individual test files, run `npm run pretest && npx jest packages/apollo-server-foo/src/__tests__/bar.test.ts`. Note that you do need to re-compile TypeScript before each time you run a test, or changes across packages may not be picked up. Instead of running `npm run pretest` from scratch before each test run, you can also run `tsc --build tsconfig.json --watch` in another shell, or use the VSCode `Run Build Task` to run that for you. |
| 159 | + |
| 160 | +## Community |
| 161 | + |
| 162 | +Are you stuck? Want to contribute? Come visit us in the [Apollo community forum!](https://community.apollographql.com) |
| 163 | + |
| 164 | + |
| 165 | +## Maintainers |
| 166 | + |
| 167 | +- [David Glasser](https://github.com/glasser/) |
| 168 | +- [Trevor Scheer](https://github.com/trevorscheer/) |
| 169 | + |
| 170 | +## Who is Apollo? |
| 171 | + |
| 172 | +[Apollo](https://apollographql.com/) builds open-source software and a graph platform to unify GraphQL across your apps and services. We help you ship faster with: |
| 173 | + |
| 174 | +* [Apollo Studio](https://www.apollographql.com/studio/develop/) – A free, end-to-end platform for managing your GraphQL lifecycle. Track your GraphQL schemas in a hosted registry to create a source of truth for everything in your graph. Studio provides an IDE (Apollo Explorer) so you can explore data, collaborate on queries, observe usage, and safely make schema changes. |
| 175 | +* [Apollo Federation](https://www.apollographql.com/apollo-federation) – The industry-standard open architecture for building a distributed graph. Use Apollo’s gateway to compose a unified graph from multiple subgraphs, determine a query plan, and route requests across your services. |
| 176 | +* [Apollo Client](https://www.apollographql.com/apollo-client/) – The most popular GraphQL client for the web. Apollo also builds and maintains [Apollo iOS](https://github.com/apollographql/apollo-ios) and [Apollo Android](https://github.com/apollographql/apollo-android). |
| 177 | +* [Apollo Server](https://www.apollographql.com/docs/apollo-server/) – A production-ready JavaScript GraphQL server that connects to any microservice, API, or database. Compatible with all popular JavaScript frameworks and deployable in serverless environments. |
| 178 | + |
| 179 | +## Learn how to build with Apollo |
| 180 | + |
| 181 | +Check out the [Odyssey](https://odyssey.apollographql.com/) learning platform, the perfect place to start your GraphQL journey with videos and interactive code challenges. Join the [Apollo Community](https://community.apollographql.com/) to interact with and get technical help from the GraphQL community. |
0 commit comments