Deploy a Docusaurus App on Azure Static Web Apps

In this article, we are going to build a simple app using Docusaurus and deploying the application to Azure Static Web App. So please grab a cup of coffee and start learning.

Table of Content

1. What is Docusaurus?
2. What is Azure Static Web App?
3. Build a simple app using Docusaurus
4. Deploy app into Azure Static Web App

What is Docusaurus?

Do you want to create great documentation for your project then Docusaurus is best option for building a documentation websites. It uses Markdown for documentation. Docusaurus is built using React so you can always customize the website as you want. It also supports Localization and document versioning.

What is Azure Static Web App?

Azure Static Web App is first launched as a preview in Microsoft Build 2020.

According to Azure Static Web App doc:

Azure Static Web Apps is a service that automatically builds and deploys full stack web apps to Azure from a GitHub repository.

With Azure Static Web App you can deploy any static application which is build using any Javascript framework or library or SSG. It uses Github actions to do the deployment out of the box. We can also host Azure function with the same application. Microsoft has created very good documentation so you can read more about Azure Static Web App here. Currently, Azure Static Web Apps are in preview. We can learn how to create Azure Static web app resources and how to configure our app deployed later in the article.

The azure static web app uses Github actions to do a deployment of the application. We have to just create Azure static web app resource and set up our application such as the location of the folder after prod build of our app, default app directory, if you any custom build command then you can also specify. Once you provide all the data and create resource then Azure static web app create a github action workflow into our repository and deploy our application. So after that every time you push commits or accept pull requests into the watched branch, the GitHub Action automatically builds and deploys your app and its API to Azure.

Features

1. Free SSL certificates
2. It has the support of Azure Functions for adding some dynamic content into our app.
3. All the static content is globally distributed
4. It also provides 1 pre-production i.e. staging environment to preview our changes before pushing to production.

You can read more features here.

Build a simple app using Docusaurus

Prerequisites

You need to have installed the latest stable version of Node JS and NPM. You can also install Yarn as well.

Install Docusaurus cli using below command:

npm install --global docusaurus-init

or

yarn global add docusaurus-init

Now create a folder for our app docusaurus-swa-app and navigate inside that into folder.

 mkdir docusaurus-swa-app
 cd docusaurus-swa-app

Now run the below command to create Docusaurus app

docusaurus-init

After completion of the above step, the docusaurus installation script creates two new directories: docs and website.

To run the app navigate to website folder and run below command.

npm start

or

yarn start

Open http://localhost:3000 to see the basic app.

Open the package.json file under website folder add dependencies section as below:

{
  "scripts": {
    "examples": "docusaurus-examples",
    "start": "docusaurus-start",
    "build": "docusaurus-build",
    "publish-gh-pages": "docusaurus-publish",
    "write-translations": "docusaurus-write-translations",
    "version": "docusaurus-version",
    "rename-version": "docusaurus-rename-version"
  },
 "dependencies": {
    "docusaurus": "^1.14.6"
  }
}

So we have created our app successfully, next step is to push the code to Github.

Login to Github and create new repository.

Follow the below steps for commit and push the project into Git.

git init
git add .
git commit -m "first commit"
git remote add origin <your repo address>
git push -u origin master

Deploy app into Azure Static Web App

Prerequisites

An Azure account with an active subscription. If you don't have one, you can create an account for free.

1. Navigate to the Azure portal
2. Click Create a Resource
3. Search for Static Web Apps
4. Click Static Web Apps (Preview)
5. Click Create

6. For Subscription, accept the subscription that is listed or select a new one from the drop-down list.

7. In Resource group, select New. In New resource group name, enter docusaurus-swa-app and select OK.

8. Next, a name for your app in the Name box. Valid characters include a-z, A-Z, 0-9 and -.

9. For Region, select an available region close to you.

10. For SKU, select Free.

1. Click the Sign in with GitHub button.

2. Select the Organization under which you created the repository.

3. Select the docusaurus-swa-app as the Repository .

4. For the Branch select master.

Next, add configuration settings that the build process uses to build your app.

1. Click the Next: Build > button to edit the build configuration

2. To configure the settings of the step in GitHub Actions, set the App location to /website.

3. Set App artifact location to build/test-site.

A value for API location isn't necessary as you aren't deploying an API at the moment.

1. Click the Review + Create button to verify the details are all correct.

2. Click Create to start the creation of the App Service Static Web App and provision a GitHub Action for deployment.

3. Once the deployment completes click, Go to resource.

4. On the resource screen, click the URL link to open your deployed application. You may need to wait a minute or two for the GitHub Action to complete.

That's it. We have successfully deployed our Docusaurus on Azure Static Web App.

Conclusion

In this article, We have created a basic app using Docusaurus. We have also deployed the same application on Azure Static Web App.

I really hope that you enjoyed this article, share it with friends and please do not hesitate to send me your thoughts or comments.

You can reach out to me on twitter @sumitkharche01.

Happy Coding!!