docs: add Cloudflare Workers documentation (#21658)

* Add Cloudflare Workers documentation * fix link, reorder recipe Co-authored-by: Kyle Gill <[email protected]> Co-authored-by: gatsbybot <[email protected]>
gatsbyjs · Mar 11, 2020 · dce6e11 · dce6e11
1 parent 5fcfc93
commit dce6e11
Show file tree

Hide file tree

Showing 5 changed files with 155 additions and 0 deletions.
diff --git a/docs/docs/deploying-to-cloudflare-workers.md b/docs/docs/deploying-to-cloudflare-workers.md
@@ -0,0 +1,124 @@
+---
+title: Deploying to Cloudflare Workers
+---
+
+[Cloudflare Workers](https://workers.cloudflare.com/) is a serverless platform for creating entirely new applications or augmenting existing ones without configuring or maintaining infrastructure. With [Workers Sites](https://developers.cloudflare.com/workers/sites/start-from-existing/) you can deploy any static site including your Gatsby projects to a domain on Cloudflare or for free with on your [workers.dev](workers.dev) subdomain.
+
+To enable the KV store required to serve the Gatsby files, you'll need the [Workers Unlimited plan](https://developers.cloudflare.com/workers/about/pricing/) for \$5/month.
+
+This guide will get you started in a few steps:
+
+1. Installing wrangler CLI
+
+Workers Sites requires [wrangler](https://developers.cloudflare.com/workers/tooling/wrangler/). The more straight forward way to install wrangler is with [npm](https://www.npmjs.com/), run the following command:
+
+```shell
+npm i -g @cloudflare/wrangler
+```
+
+2. Initialize the Project
+
+To create the Worker code that will serve your Gatsby files, from the root of your Gatsby project run:
+
+```
+wrangler init --site
+```
+
+You'll notice your project structure should now look something like:
+
+```diff
++ ├── workers-site
++ └── wrangler.toml
++ │   ├── index.js
++ │   ├── package-lock.json
++ │   └── package.json
+  ├── src
+  │   ├── components
+  │   ├── images
+  │   └── pages
+  ├── gatsby-config.js
+  ├── package.json
+```
+
+3. Configure
+
+To authenticate into your Cloudflare account run:
+
+```
+wrangler config
+```
+
+Follow the [Quick Start](https://developers.cloudflare.com/workers/quickstart/#configure) for steps on gathering the correct account ID and API token to link wrangler to your Cloudflare account.
+
+If you don't already have a workers.dev domain run:
+
+```
+wrangler subdomain
+```
+
+Then, add your account ID to the `wrangler.toml` file, and set `bucket` to `"./public"`, which is where Gatsby's built files are output by default:
+
+```
+name = "gatsby-project"
+type = "webpack"
+account_id = "abcd..."
+workers_dev = true
+
+[site]
+bucket = "./public"
+entry-point = "workers-site"
+```
+
+This deploys to your workers.dev subdomain. For a custom domain see [Quick Start](https://developers.cloudflare.com/workers/quickstart/#publish-to-your-domain).
+
+4. Deploy
+
+You can deploy your application by running the following command in the root of the project directory:
+
+```shell
+wrangler publish
+```
+
+Now your site is available at gatsby-project.subdomain.workers.dev!
+
+5. CI with Github Actions
+
+Use wrangler's Github action [plugin](https://github.com/cloudflare/wrangler-action) to automatically deploy to Workers every time you push to master.
+
+Once Github Actions is enabled on your repo, add a file to your project's root called `.github/workflows/main.yml` with the contents:
+
+```
+name: Deploy production site
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v1
+    - name: Navigate to repo
+      run: cd $GITHUB_WORKSPACE
+    - uses: actions/setup-node@v1
+      with:
+        node-version: '10.x'
+    - name: Install deps
+      run: npm install
+    - name: Build docs
+      run: npm run build
+    - name: Publish
+      uses: cloudflare/[email protected]
+      with:
+        apiToken: ${{ secrets.CF_API_TOKEN }}
+        environment: "production"
+```
+
+Set up `CF_API_TOKEN` in Github secrets with appropriate values from [Quick Start](https://developers.cloudflare.com/workers/quickstart/#configure).
+
+## Additional resources
+
+- [Quickstart for Workers Sites](https://developers.cloudflare.com/workers/sites/start-from-existing/)
+- [Github Action wrangler plugin](https://github.com/cloudflare/wrangler-action)
diff --git a/docs/docs/preparing-for-deployment.md b/docs/docs/preparing-for-deployment.md
@@ -47,6 +47,7 @@ If you have a server from one of the following providers, you should read the in
 - [Aerobatic](/docs/deploying-to-aerobatic)
 - [Heroku](/docs/deploying-to-heroku)
 - [ZEIT Now](/docs/deploying-to-zeit-now)
+- [Cloudflare Workers](/docs/deploying-to-cloudflare-workers)
 - [GitLab Pages](/docs/deploying-to-gitlab-pages)
 - [Netlify](/docs/deploying-to-netlify)
 - [Render](/docs/deploying-to-render)

diff --git a/docs/docs/recipes.md b/docs/docs/recipes.md
@@ -117,3 +117,4 @@ Showtime. Once you are happy with your site, you are ready to go live with it!
 - [Preparing for deployment](/docs/recipes/deploying-your-site#preparing-for-deployment)
 - [Deploying to Netlify](/docs/recipes/deploying-your-site#deploying-to-netlify)
 - [Deploying to ZEIT Now](/docs/recipes/deploying-your-site#deploying-to-zeit-now)
+- [Deploying to Cloudflare Workers](/docs/recipes/deploying-your-site#deploying-to-cloudflare-workers)
diff --git a/docs/docs/recipes/deploying-your-site.md b/docs/docs/recipes/deploying-your-site.md
@@ -104,3 +104,29 @@ Use [Now CLI](https://zeit.co/download) to deploy your Gatsby application withou
 ### Additional resources
 
 - [Deploying to ZEIT Now](/docs/deploying-to-zeit-now/)
+
+## Deploying to Cloudflare Workers
+
+Use [`wrangler`](https://developers.cloudflare.com/workers/tooling/wrangler/) to deploy your Gatsby application globally without leaving the command-line interface.
+
+### Prerequisites
+
+- An account on [Cloudflare](https://dash.cloudflare.com/sign-up)
+- A [Workers Unlimited plan](https://developers.cloudflare.com/workers/about/pricing/) for \$5/month to enable the KV store, which is required to serve the Gatsby files.
+- A [Gatsby site](/docs/quick-start) set up with Gatsby's CLI
+- [wrangler](https://developers.cloudflare.com/workers/tooling/wrangler/install/) installed globally (`npm i -g @cloudflare/wrangler`)
+
+### Directions
+
+1. Build your Gatsby application using `gatsby build`
+2. Run `wrangler config` where you'll be prompted for your [Cloudflare API token](https://developers.cloudflare.com/workers/quickstart/#api-token)
+3. Run `wrangler init --site`
+4. Configure `wrangler.toml`. First add [account ID](https://developers.cloudflare.com/workers/quickstart/#account-id-and-zone-id) field and then either
+   1. A free workers.dev domain by setting `workers_dev = true`
+   2. A custom domain on Cloudflare by setting `workers_dev = false`, `zone_id = "abdc..` and `route = customdomain.com/*`
+5. In `wrangler.toml` set `bucket = "./public"`
+6. Run `wrangler publish` and your site will be deployed in seconds!
+
+### Additional resources
+
+- [Hosting on Cloudflare](/docs/deploying-to-cloudflare-workers)
diff --git a/www/src/data/sidebars/doc-links.yaml b/www/src/data/sidebars/doc-links.yaml
@@ -76,6 +76,9 @@
             - title: Deploying to ZEIT Now
               link: /docs/deploying-to-zeit-now/
               breadcrumbTitle: ZEIT Now
+            - title: Deploying to Cloudflare Workers
+              link: /docs/deploying-to-cloudflare-workers/
+              breadcrumbTitle: Cloudflare Workers
             - title: Deploying to GitLab Pages
               link: /docs/deploying-to-gitlab-pages/
               breadcrumbTitle: GitLab Pages