SPA & Static Framework Guide

Introduction

This guide is meant to address deploying a SPA (single-page application) or any statically generated project on our Headless Platform. Some examples are Create React App or Eleventy, or even Astro in static mode.

Deploy Steps

Since there are many possible SPA or static site generators, you should follow the getting started guides relevant to your chosen tools.

Push Initial Commits to Your Repository

To deploy your project to our Headless Platform, it will need to be available on a remote GitHub, Bitbucket or GitLab repository.

Create a new remote repository, and then run the following commands to initalize and configure your local and remote repositories:

# Add remote repository
$ git remote add origin https://<your-git-provider>.com/<username>/<repo>

# Stage all changed files
$ git add -A

# Commit the files to the current branch
$ git commit -m "initial commit"

# Push changes to remote repository
$ git push -u origin main

Build Details

When our Headless Platform deploys your project, it will first run npm install followed by npm run build to build your application. Depending on your framework, this typically produces a directory of static assets like build or dist.

Since our Headless Platform is based on Node.js containers, it does not serve these static assets automatically.

Serving Static Assets

There are multiple ways to accomplish this step, so if you have a Node.js HTTP server you already like, chances are it will work fine on our Headless Platform. The following steps will show and example using Express.

To serve a SPA in a Node.js container we can install the express package and create a server.js file in the root of your project. Next, modify the npm run start command to run node server.js, which should start the express server.

SPA Config

The contents of server.js should look like this for a SPA that uses client-side routing. It will respond with index.html regardless of the path, allowing the client-side app to take over routing. This config is made specifically for a Create React App project:

const express = require('express');
const path = require('path');
const app = express();

app.use(express.static(path.join(__dirname, 'build')));

app.get('/*', function (req, res) {
  res.sendFile(path.join(__dirname, 'build', 'index.html'));
});

app.listen(8080);

Deploy Your Repository

Once your project is in your remote repository, you can follow the directions in our getting started guide to deploy your project to our Headless Platform.