As some of you may know, we love to present tech talks at Clever Cloud, and this often comes with visual presentations slides. There are numerous tools to help you do that, but one particularly caught my attention as it is also destined to developers first. MDX-deck allows you to write React components and content in Markdown among other cool stuffs. Check out the official repo to find out more about the capabilities of the project.
Wether you're doing presentations or not, read carefully, we are about to deploy a static application made out of a React build and use the Clever Cloud hooks to do so. Ready? Let's go.
Requirements
- you need to have npm and git installed on your machine.
- you need a Clever Cloud account with at least a validated email to benefit the free credits.
Setting up our MDX-Deck
Go to your console and type in
$ mkdir presentation //creating a new folder
$ cd presentation
$ git init // creating fresh git folder
$ npm init //creating new project
Just type enter for eveything you're prompted of except for description if you would like to provide one, author that you must fill, license that you can edit to the licence you want your project to be under.
Now we will create our presentation file with $ touch deck.mdx and add the package to the project with $ npm i -D mdx-deck.
Open the project in your text editor and start with fine tuning package.json Here we want to remove the line
"main": "index.js",
and add a start and a build command using the mxd-deck CLI with the file we just created to our scripts
"scripts": {
"start": "mdx-deck deck.mdx",
"build": "mdx-deck build deck.mdx",
"test": "echo \"Error: no test specified\" && exit 1"
},
We will only use start to test locally and use build to deploy. We are done with package.json, we can now move to deck.mdx. Add this in the file:
# Congratulations!
---
## You're up and live on Clever Cloud!
---
You can note that we have just created two slides, each one ending with --- and that we are using the Markdown syntax. Let's see how it renders with npm start. Your browser will open at http://localhost:8000 displaying our first slide. Use side arrows to navigate between pages.
Deploy to clever cloud as static with hooks
Now we will create a static application in the Clever Cloud console. Under the organization of our choice, we will click the Create button and select application, then Static. Follow the instructions, and just select git when you have the choice between it and FTP. A git remote will be provided to you. Add it to your local repository with the provided command and get back to the Clever Cloud console. Select Environment variables in the left menu of your application and add CC_PRE_RUN_HOOK with value npm run build and CC_WEBROOT with value /public. Do not forget to add each new variable and to update changes when you are done editing.
Now we can push our sources to the clever git remote we set previously by adding and committing them, then pushing with $ git push clever master. It is also possible to du it using the Clever Cloud CLI with clever deploy. Documentation here
In the Clever Cloud console, the deployment logs will appear and after a little you will be able to navigate to your application by going to the overview page of your application and clicking the link icon on the top right. Use right arrow to navigate to slide two. But what did just happen?
Explanation
The CC_PRE_RUN_HOOK is a command run only if specified. This hook is run before the dependencies are fetched and has the specificity to make your deployment fail if it no successful. This is helpful as we do not want to try running a failed build result and have confusing errors harder to debug.
Here, we gave it the value of npm run-script build, this basically tells npm to run our build command specified in package.json. Build command which runs mdx-deck build cli. That leaves us with a new /public folder containing our website static web pages. The other environment variable we used is CC_WEBROOT. This variable tells the server to set the DocumentRoot to the /public folder wich contains your web pages. This is where a visitor will end up when visiting your website.
You can, of course adapt, it to any other npm project static build.