In this blog post we'll setup a Docusaurus site locally, host the source code on Github private repository and finally publish the site using Cloudflare Pages.
Docusaurus is a static-site generator. Cloudflare Pages is a JAMstack platform that we'll use to host the Docusaurus site.
Let's get started.
Install Docusaurus Locally
Follow the Official Installation Guide to install Docusaurus.
Run locally to verify:
Upload the Local Docusaurus Project to Github
Create a new repository on Github.
Copy the Github repository url from Github.
Stop the Docusaurus local server (if still running) and run the following commands in the terminal (or command prompt on windows).
git init
git add .
git commit -m "initial commit"
git branch -M main
git remote add origin https://github.com/YOUR_USERNAME/docusaurus-on-cloudflare-pages.git
git push -u origin main
Reload the Github page and you should see the local project source code is synced to Github repository.
Deploy the Docusaurus Site to Cloudflare Pages
Go to Cloudflare Pages website and sign in to your Cloudflare account (or sign up for a new account).
Once signed in, click on Pages on the left sidebar.
Click on Create a project.
Connect your Github account and select the repository and click on Save (on Github).
You'll be redirected back to Cloudflare Pages. Select the Github repository and click on Begin Setup.
Under Build settings, change the Framework preset to Docusaurus. Click on Save and Deploy.
Build Failed
If you have followed all the previous steps, you'll end up with a Build failed error screen.
The error log:
12:11:09.800 Initializing build environment. This may take up to a few minutes to complete
12:11:11.685 Success: Finished initializing build environment
12:11:11.685 Cloning repository...
12:11:13.380 Success: Finished cloning repository files
12:11:13.719 Installing dependencies
12:11:13.731 Python version set to 2.7
12:11:17.651 v12.18.0 is already installed.
12:11:19.045 Now using node v12.18.0 (npm v6.14.4)
12:11:19.387 Started restoring cached build plugins
12:11:19.404 Finished restoring cached build plugins
12:11:20.110 Attempting ruby version 2.7.1, read from environment
12:11:25.960 Using ruby version 2.7.1
12:11:26.326 Using PHP version 5.6
12:11:26.514 5.2 is already installed.
12:11:26.540 Using Swift version 5.2
12:11:26.542 Started restoring cached node modules
12:11:26.564 Finished restoring cached node modules
12:11:26.802 Installing NPM modules using NPM version 6.14.4
12:11:27.736 npm WARN read-shrinkwrap This version of npm is compatible with lockfileVersion@1, but package-lock.json was generated for lockfileVersion@2. I'll try to do my best with it!
12:11:44.663
12:11:44.664 > core-js@3.22.4 postinstall /opt/buildhome/repo/node_modules/core-js
12:11:44.664 > node -e "try{require('./postinstall')}catch(e){}"
12:11:44.664
12:11:44.766 [96mThank you for using core-js ([94m https://github.com/zloirock/core-js [96m) for polyfilling JavaScript standard library
How to Use NodeJS v14 or v16 or v17 on Cloudflare Pages ?
To use a different but supported version of NodeJS on Cloudflare Pages, you need
to create an Environment Variable scoped to the project.
From the Cloudflare dashboard, click on Pages and select the pages project.
Go to Settings tab and click on Environment variables. Click on Add variables.
Enter NODE_VERSION as the Variable name and 16.14.0 as the Value.
Click on Save.
Question: How do I know that an Environment Variable needs to be created in this case ?
It's mentioned on the official documentation
If you need to use a specific version of a language, (for example, Node.js or Ruby) you can specify it by providing an associated environment variable in your build configuration, or setting the relevant file in your source code.
Hence, always read the documentation.
Question: Why is the Environment Variable Value written as 16.14.0 and not as v16.14.0 ?
It's because the Default version on the documentation is written as 12.18.0
and not as v12.18.0. Hence, using the same format makes sense.
Retry Deployment
Switch to the Deployments tab and click on Retry deployment.
Finally, the deployment is successful and the Docusaurus site is deployed to Cloudflare Pages.
What's Next ?
Your Docusaurus site is live now. Go ahead and update your site. When done, just commit your changes to Github and that's it. Cloudflare Pages will rebuild your site whenever you push new commits to Github.
That's all for now!
In this blog post, we've deployed a Docusaurus site to Cloudflare Pages. The idea for this blog post is not just to provide a solution for a problem but to provide an understanding of how you should approach to solve a problem.