From f6a46e772c898b41735da03f5b5b2120df552140 Mon Sep 17 00:00:00 2001 From: David Glasser Date: Thu, 17 Jun 2021 15:13:04 -0700 Subject: [PATCH] Mark doc areas that should be fixed for AS3 with "FIXME AS3" --- docs/source/api/apollo-server.md | 1 + docs/source/data/file-uploads.md | 4 ++++ docs/source/data/subscriptions.mdx | 2 ++ docs/source/deployment/azure-functions.md | 2 ++ docs/source/deployment/gcp-functions.mdx | 6 ++++++ docs/source/deployment/heroku.md | 2 ++ docs/source/deployment/lambda.md | 4 ++++ docs/source/deployment/netlify.md | 2 ++ docs/source/getting-started.mdx | 1 + docs/source/migration-engine-plugins.md | 2 ++ docs/source/migration.md | 1 + docs/source/testing/graphql-playground.mdx | 2 +- 12 files changed, 28 insertions(+), 1 deletion(-) diff --git a/docs/source/api/apollo-server.md b/docs/source/api/apollo-server.md index 4a4ba0b9e34..49437b4b023 100644 --- a/docs/source/api/apollo-server.md +++ b/docs/source/api/apollo-server.md @@ -279,6 +279,7 @@ An object containing configuration options for connecting Apollo Server to [Apol An array of [plugins](../integrations/plugins) to install in your server instance. Each array element can be either a valid plugin object or a zero-argument function that _returns_ a valid plugin object. In certain cases, Apollo Server installs some of its built-in plugins automatically (for example, when you provide an Apollo Studio API key with the `APOLLO_KEY` environment variable). For details, see the API references for these plugins: [usage reporting](./plugin/usage-reporting/), [schema reporting](./plugin/schema-reporting/), and [inline trace](./plugin/inline-trace/). +FIXME AS3: More things are installable plugins now (cache control, landing pages) which should be documented on their own pages and mentioned here. diff --git a/docs/source/data/file-uploads.md b/docs/source/data/file-uploads.md index 13937ae33c5..b6b9b70c26b 100644 --- a/docs/source/data/file-uploads.md +++ b/docs/source/data/file-uploads.md @@ -5,6 +5,8 @@ description: Enabling file uploads in Apollo Server > Note: As of Apollo Server 3.0, in order to allow the `graphql-upload` package to evolve and live on its own, uploads are no longer enabled by default and are not an integrated part of Apollo Server. +FIXME AS3: Need to verify that the code below still works. Should note that federation does not support uploads. + File uploads can be enabled by using the third-party [`graphql-upload`](https://npm.im/graphql-upload) package. Using this package will introduce support for the `multipart/form-data` content-type. The instructions below demonstrate how to do this on Express. Those wishing to implement similar functionality on other Node.js HTTP frameworks (e.g., Koa) should see the [`graphql-upload` repository's documentation](https://github.com/jaydenseric/graphql-upload) for more information. Some integrations may need to use `graphql-upload`'s `processRequest` directly. @@ -69,6 +71,8 @@ const server = new ApolloServer({ typeDefs, resolvers, }); +// FIXME AS3: Missing `await server.start()` though that implies we should refactor +// into a larger async function. const app = express(); diff --git a/docs/source/data/subscriptions.mdx b/docs/source/data/subscriptions.mdx index 834b6dfa973..c62fd48b2dd 100644 --- a/docs/source/data/subscriptions.mdx +++ b/docs/source/data/subscriptions.mdx @@ -5,6 +5,8 @@ description: Persistent GraphQL read operations import {ExpansionPanel} from 'gatsby-theme-apollo-docs'; +FIXME AS3: Whole file needs to be rewritten, as we don't have built in subscription support any more, and probably shouldn't recommend using `subscriptions-transport-ws` at this time. + > **Subscriptions are not currently supported in [Apollo Federation](https://www.apollographql.com/docs/federation/).** **Subscriptions** are long-lasting GraphQL read operations that can update their result whenever a particular server-side event occurs. Most commonly, updated results are _pushed_ from the server to subscribing clients. For example, a chat application's server might use a subscription to push newly received messages to all clients in a particular chat room. diff --git a/docs/source/deployment/azure-functions.md b/docs/source/deployment/azure-functions.md index 2c7aa0e6e6e..ff4005015ac 100644 --- a/docs/source/deployment/azure-functions.md +++ b/docs/source/deployment/azure-functions.md @@ -5,6 +5,8 @@ description: Deploying your GraphQL server to Azure Functions --- This is the Azure Functions integration for the Apollo community GraphQL Server. [Read Docs](https://www.npmjs.com/package/apollo-server-azure-functions) +FIXME AS3: Walk through and test this whole file. Ensure README.md reflects changes here (or remove the duplication). + All examples below was created using Linux environments, if you are working with Windows-based platforms some commands couldn’t work fine. ## Prerequisites diff --git a/docs/source/deployment/gcp-functions.mdx b/docs/source/deployment/gcp-functions.mdx index 5d20dcf4ee8..2a53f3d8f64 100644 --- a/docs/source/deployment/gcp-functions.mdx +++ b/docs/source/deployment/gcp-functions.mdx @@ -3,6 +3,8 @@ title: Deploying with Google Cloud Functions sidebar_title: Google Cloud Functions --- +FIXME AS3: Walk through and test this whole file. Ensure README.md reflects changes here (or remove the duplication). + import { ExpansionPanel, } from 'gatsby-theme-apollo-docs/src/components/expansion-panel'; @@ -64,6 +66,8 @@ Paste the example code at the top of this page into the contents of `index.js` i Edit `package.json` so that it lists `apollo-server-cloud-functions` and `graphql` in its dependencies: +FIXME AS3: can we make this just be an `npm install` somehow? Otherwise we have to keep the version up to date here. At the very least we have to get this to 3.0.0. + ```json:title=package.json "dependencies": { "apollo-server-cloud-functions": "^2.24.0", @@ -180,6 +184,8 @@ exports.handler = server.createHandler(); ## Modifying the GCF Response (CORS) +FIXME AS3: I think CORS is now enabled by default so at least part of this can be removed. + To enable CORS, you need to modify your HTTP response headers. To do so, use the `cors` option: ```javascript{23-26} diff --git a/docs/source/deployment/heroku.md b/docs/source/deployment/heroku.md index 8ed288f21e9..632e55b03c3 100644 --- a/docs/source/deployment/heroku.md +++ b/docs/source/deployment/heroku.md @@ -4,6 +4,8 @@ sidebar_title: Heroku description: Deploying your GraphQL server to Heroku --- +FIXME AS3: Walk through and test this whole file. + Heroku is a common Platform as a Service solution that allows users to deploy and have a functioning GraphQL endpoint running in a matter of minutes. ## Prerequisites diff --git a/docs/source/deployment/lambda.md b/docs/source/deployment/lambda.md index ed7a889497e..4a0c715f1d8 100644 --- a/docs/source/deployment/lambda.md +++ b/docs/source/deployment/lambda.md @@ -4,6 +4,8 @@ sidebar_title: Lambda description: How to deploy Apollo Server with AWS Lambda --- +FIXME AS3: Walk through and test this whole file. Ensure README.md reflects changes here (or remove the duplication). + AWS Lambda is a service that allows users to run code without provisioning or managing servers. Cost is based on the compute time that is consumed, and there is no charge when code is not running. This guide explains how to setup Apollo Server 2 to run on AWS Lambda using Serverless Framework. To use CDK and SST instead, [follow this tutorial](https://serverless-stack.com/examples/how-to-create-an-apollo-graphql-api-with-serverless.html). @@ -191,6 +193,8 @@ exports.graphqlHandler = server.createHandler(); ## Modifying the Lambda response (Enable CORS) +FIXME AS3: I think CORS is now enabled by default so at least part of this can be removed. + To enable CORS, the response HTTP headers need to be modified. To accomplish this, use the `cors` options. ```js diff --git a/docs/source/deployment/netlify.md b/docs/source/deployment/netlify.md index 3fe5c2b2b05..d863a583fbb 100644 --- a/docs/source/deployment/netlify.md +++ b/docs/source/deployment/netlify.md @@ -4,6 +4,8 @@ sidebar_title: Netlify description: How to run your API using Netlify Functions on AWS Lambda --- +FIXME AS3: Walk through and test this whole file. + [Netlify Functions](https://www.netlify.com/docs/functions/) allow deploying server-side code, directly from GitHub, to AWS Lambda. This guide demonstrates how to use Netlify Functions to deploy a GraphQL server and reference the server in Apollo Client. Some benefits of Netlify Functions include: 1. Use the same platform to deploy your frontend and API code. diff --git a/docs/source/getting-started.mdx b/docs/source/getting-started.mdx index ca61cf85ac2..bc1ad4f094e 100644 --- a/docs/source/getting-started.mdx +++ b/docs/source/getting-started.mdx @@ -185,6 +185,7 @@ We're up and running! We can now execute GraphQL queries on our server. To execute our first query, we can use **Apollo Sandbox**. +FIXME AS3: Should we instead tell folks to go to the printed localhost URL and click through the landing page to Sandbox? With your server still running, visit [studio.apollographql.com/sandbox](https://studio.apollographql.com/sandbox) to open Sandbox: Apollo Sandbox diff --git a/docs/source/migration-engine-plugins.md b/docs/source/migration-engine-plugins.md index 72afb68b9a7..54bf84f596d 100644 --- a/docs/source/migration-engine-plugins.md +++ b/docs/source/migration-engine-plugins.md @@ -2,6 +2,8 @@ title: Migrating from the "engine" option --- +FIXME AS3: We can probably remove this but also have the first step in the migration guide say "if you're using `engine:`, then before migrating to 2.0, stop setting `engine` based on this page in the v2 migration guide" + Apollo Server v2.18 deprecates the `engine` option to the `ApolloServer` constructor and provides a new way of configuring its communication with Apollo Studio. The `engine` option continues to work for existing functionality, but you will eventually want to update to the new API. If you don't explicitly pass `engine` to the `ApolloServer` constructor, you don't have to do anything. Apollo Server ships with several plugins that help it integrate with Apollo Studio: the [usage reporting plugin](./api/plugin/usage-reporting/) plugin, the [schema reporting plugin](./api/plugin/schema-reporting/), and the [inline trace plugin](./api/plugin/inline-trace/). Apollo Server has some heuristics to install these plugins by default in certain circumstances (documented in the individual plugin reference pages), but otherwise they are standard [Apollo Server plugins](./integrations/plugins/). They are configured by passing arguments to the constructor functions. Some overall graph configuration (such as your graph API key and graph variant name) is set via the `apollo` option to the `ApolloServer` constructor (or via environment variables). diff --git a/docs/source/migration.md b/docs/source/migration.md index b4b9e9a718f..ade4c8b970a 100644 --- a/docs/source/migration.md +++ b/docs/source/migration.md @@ -3,6 +3,7 @@ title: Migrating to v3.0 description: How to migrate to Apollo Server 3.0 --- +FIXME AS3: Lots more is needed here. ## Subscriptions > *Note:* Currently, these instructions are only for the Express integration. diff --git a/docs/source/testing/graphql-playground.mdx b/docs/source/testing/graphql-playground.mdx index 533aa57b2ff..eadb8f804bb 100644 --- a/docs/source/testing/graphql-playground.mdx +++ b/docs/source/testing/graphql-playground.mdx @@ -30,7 +30,7 @@ Sandbox automatically attempts to connect to a GraphQL server running at `http:/ [GraphQL Playground](https://github.com/graphql/graphql-playground) is a graphical, interactive, in-browser GraphQL IDE, created by [Prisma](https://www.prisma.io/) and based on [GraphiQL](https://github.com/graphql/graphiql). -(Note: This whole page needs to be updated for AS3 now that Playground is not the default.) +(FIXME AS3: This whole page needs to be updated for AS3 now that Playground is not the default.) In development, Apollo Server enables GraphQL Playground on the same URL as the GraphQL server itself (e.g. `http://localhost:4000/graphql`) and automatically serves the GUI to web browsers. When `NODE_ENV` is set to `production`, GraphQL Playground (as well as introspection) is disabled as a production best-practice. It does this by installing the `ApolloServerPluginLandingPageGraphQLPlayground` plugin with default settings.