21
Running Tighten's Jigsaw on Vercel
For more than two years, my website was hosted on Netlify. This summer, the poor loading performance got on my nerves, and I decided to migrate the site to Vercel. The results are stunning! The average response time dropped from ~500ms to ~100ms.
My site is built with Jigsaw, a PHP static site builder.
That is the first problem: PHP. You can't run a PHP binary in Vercel's build process. The community PHP runtime can't be used either: I need to run a PHP CLI; not deploy a PHP lambda function.
So how did I deploy this site to Vercel? If you know me well, you know the answer already: GitHub Actions.
I've created a GitHub Actions workflow that checks out my repository, installs the composer and NPM dependencies, builds the site, tests the site for common errors and then – finally – uploads the site to Vercel's edge network.
Before we begin: this setup looks intimidating. If you would like to host your Jigsaw websites in a simpler way, I can recommend following Michael Dyrynda's blog post on how to deploy a Jigsaw site to Netlify.
GitHub Actions workflow to deploy the site#
Before switching to Vercel as my website host, I already used GitHub Actions to create a new build of the website on every commit push. The workflow acted like a test runner. It ensured, that my changes – or dependeny updates created by Dependabot – didn't break the site.
All I had to add was a new job that uploaded the prepared website to Vercel. Below is the stripped down workflow annotated with comments, to explain what each step does.
I've removed a couple of steps that do the quality control (look for weasel words, validate RSS feed, etc.) for me. I will share more about these steps in the future.
To use the workflow you will need to create a couple of secrets in your repository. You will need a VERCEL_TOKEN, VERCEL_PROJECT_ID and VERCEL_ORG_ID.
# integrate.yml
name: Integrate
# Run workflow when commits are pushed to pull requests or main branch
on:
pull_request: null
push:
branches:
- main
jobs:
# Build Job
# This job install necessary dependencies, generate a new production build
# of the website and make the build available to other jobs in the workflow.
build:
name: Build
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Restore node_modules folder
id: cache-node
uses: actions/cache@v2
with:
path: node_modules
key: ${{ runner.os }}-node-v2-${{ hashFiles('**/yarn.lock') }}
restore-keys: |
${{ runner.os }}-node-v2
- name: Install frontend dependencies
if: steps.cache-node.outputs.cache-hit != 'true'
run: yarn install
env:
CI: true
- name: Create production build of CSS and JS
run: yarn run prod
- name: Restore Composer dependencies
id: cache-php
uses: actions/cache@v2
with:
path: vendor
key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}
restore-keys: |
${{ runner.os }}-php-
# If no Composer cache exists, install Composer dependencies
- name: Install Composer dependencies
if: steps.cache-php.outputs.cache-hit != 'true'
run: composer install -n --ignore-platform-reqs
- name: Create new production build of website
run: composer run build:prod
- name: Create ZIP file of production build
run: zip -r build_production.zip build_production/
- name: Keep ZIP file as artifact
uses: actions/upload-artifact@v2
with:
name: build_production_zip
path: build_production.zip
retention-days: 1
# Deploy Preview Job
# This job will deploy the website to a preview domain and is only executed
# when a commit has been pushed to a pull request and the author of the pull
# request is not Dependabot.
deploy_preview:
name: Deployment Preview
if: github.event_name == 'pull_request' && github.actor != 'dependabot[bot]'
runs-on: ubuntu-latest
# The job is only run, when the `build`-job is finished.
needs:
- build
steps:
- uses: actions/checkout@v2
- name: Download build artifact
uses: actions/download-artifact@v2
with:
name: build_production_zip
path: ./build
- name: Unzip production build
run: unzip ./build/build_production.zip -d ./build_production
# Start tracking the deployment status using GitHub deployments
- name: Start deployment
uses: bobheadxi/deployments@master
id: deployment_pr
with:
step: start
token: ${{ secrets.GITHUB_TOKEN }}
env: "Pull Request #${{ github.event.number }} Preview"
# `head_ref` has to be used here, as otherwhise the
# deployments are not shown near the status overview inside
# a pull request
ref: ${{ github.head_ref }}
- name: Setup Node.js
uses: actions/setup-node@v2
with:
node-version: 16
- name: Restore node_modules folder
id: cache-node
uses: actions/cache@v2
with:
path: node_modules
key: ${{ runner.os }}-node-v2-${{ hashFiles('**/yarn.lock') }}
restore-keys: |
${{ runner.os }}-node-v2
- name: Install frontend dependencies
if: steps.cache-node.outputs.cache-hit != 'true'
run: yarn install
env:
CI: true
# Deploy website as a preview to Vercel.
- name: Deploy to Vercel
uses: amondnet/vercel-action@v20
id: vercel_action_pr
with:
vercel-token: ${{ secrets.VERCEL_TOKEN }}
github-token: ${{ secrets.GITHUB_TOKEN }}
vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
# Disable GitHub comments. I don't need a comment telling me
# that a deployment is happening.
github-comment: false
# This is not a typo. This structure is created by unzipping
# the production build artifact.
working-directory: ./build_production/build_production
# Set the deployment status in GitHub to finished.
- name: Update Deployment Status
uses: bobheadxi/deployments@master
if: always()
with:
step: finish
token: ${{ secrets.GITHUB_TOKEN }}
status: ${{ job.status }}
# We use the deployment ID of a previous step here
deployment_id: ${{ steps.deployment_pr.outputs.deployment_id }}
# We pass Vercel's own preview URL to the environment. This
# way we can easily visit the deployed site from the pull
# request.
env_url: ${{ steps.vercel_action_pr.outputs.preview-url }}
- name: Delete production build artifact
uses: geekyeggo/delete-artifact@v1
if: always()
with:
name: build_production_zip
# Deploy Production Job
# This job will deploy the website to production and will only be executed
# when a commit is pushed to the default `main`-branch.
deploy_prod:
name: Deployment
if: github.event.ref == 'refs/heads/main'
runs-on: ubuntu-latest
# The job is only run, when the `build`-job is finished.
needs:
- build
steps:
- uses: actions/checkout@v2
- name: Download build artifact
uses: actions/download-artifact@v2
with:
name: build_production_zip
path: ./build
- name: Unzip production build
run: unzip ./build/build_production.zip -d ./build_production
# Start tracking the deployment status using GitHub deployments.
# Instead of using a dynamic environment name, we use production
- name: Start Deployment
uses: bobheadxi/deployments@master
id: deployment
with:
step: start
token: ${{ secrets.GITHUB_TOKEN }}
env: production
- uses: actions/setup-node@v2
with:
node-version: 16
- name: Restore node_modules folder
id: cache-node
uses: actions/cache@v2
with:
path: node_modules
key: ${{ runner.os }}-node-v2-${{ hashFiles('**/yarn.lock') }}
restore-keys: |
${{ runner.os }}-node-v2
- name: Install frontend dependencies
if: steps.cache-node.outputs.cache-hit != 'true'
run: yarn install
env:
CI: true
# Deploy website for production to Vercel.
- name: Deploy to Vercel
uses: amondnet/vercel-action@v20
id: vercel-action
with:
vercel-token: ${{ secrets.VERCEL_TOKEN }}
github-token: ${{ secrets.GITHUB_TOKEN }}
vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
github-comment: false
working-directory: ./build_production/build_production
# This argument tells the Vercel Action to mark the deployment
# for production
vercel-args: '--prod'
# Set the deployment status in GitHub to finished.
- name: Update Deployment Status
uses: bobheadxi/deployments@master
if: always()
with:
step: finish
token: ${{ secrets.GITHUB_TOKEN }}
status: ${{ job.status }}
deployment_id: ${{ steps.deployment.outputs.deployment_id }}
env_url: ${{ steps.vercel-action.outputs.preview-url }}
- name: Delete production build artifact
uses: geekyeggo/delete-artifact@v1
if: always()
with:
name: build_production_zipAdd the root of my project, I have the following vercel.json file.
// vercel.json
{
"github": {
"enabled": false,
"silent": true
}
}By setting github.enabled to false, I tell Vercel to not automatically deploy my site on every push through Vercel. GitHub Actions does that for me. By setting github.silent to true, Vercel will stop commenting on commits and pull requests.
Deactivate Environments when closing Pull Requests#
The big workflow above creates a new GitHub environment whenever a pull request is being deployed.
These environments will stay arround forever, if we don't deactivate them.
If you would like to keep things tidy, you can add this additional workflow to your repository. It will be triggered when a pull request is closed or merged and will delete the environment associated with it. (If you have updated the environment name in the workflow above, you have to update this workflow as well.)
# prune-environments.yml
on:
pull_request:
types: [closed]
jobs:
prune:
runs-on: ubuntu-latest
steps:
- name: Deactivate GitHub environment
uses: bobheadxi/[email protected]
with:
step: deactivate-env
token: ${{ secrets.GITHUB_TOKEN }}
env: "Pull Request #${{ github.event.number }} Preview"
desc: Deployment was prunedWrap up#
It took a couple of tries to get the workflow to behave as expected; but I really like the end result. I'm now much more in control how the website is built and have access to a more frequently updated Linux machine (another reason I was looking for a different host, as the Netlify base image was stuck on PHP 7.4).
The best thing: The workflow can be applied to any other language.
A framework you like is not compatible with Vercel? Use the workflow above and adjust it so that the build step uses the language or tool of your choosing.
Another cool benefit of having everything in GitHub Actions? I can just chain other Actions to this workflow.
For example, after each deploy I automatically run an Oh Dear check to check if any link on my website is broken.
I hope this article inspired you to give Vercel and GitHub Actions a try. If you have any questions regarding the workflow, let me know!
21