Hosting Static HTML, CSS, and JavaScript Websites

Deploying a static website is usually simpler than deploying a backend application. A website built with HTML, CSS, and JavaScript does not need a database connection, application server, or complex backend infrastructure. It only needs a web server that can deliver files to visitors.

However, deployment can become confusing when developers try to host a static website on a platform traditionally used for backend applications. They may encounter missing build directories, incorrect start commands, routing errors, or deployment failures because the platform expects a running web process.

Heroku supports static website deployment through its Front-End Web Cloud Native Buildpack. This allows developers to serve static files without writing a custom Express or PHP server.

In this article, we will build a static website, configure the required files, deploy it to Heroku, and troubleshoot common problems. We will also look at what happens when the website uses a frontend framework such as React or Vite.

What Is a Static Website?

A static website delivers files directly to the browser without generating HTML through server-side application code for every request.

A typical static website contains three main technologies:

For example, consider a company website containing a homepage, an About page, a Services page, and a Contact page.

If these pages are already written as HTML files, the server does not need to execute backend code to generate them.

A static website can be useful for:

• Personal portfolios.

• Company websites.

• Product landing pages.

• Documentation websites.

• Marketing pages.

• Frontend applications that consume external APIs.

However, static websites have limitations. They cannot securely access private database credentials or perform server-side operations directly. Those responsibilities must be handled by a backend service.

How Static Website Hosting Works on Heroku

Heroku traditionally runs applications through processes defined in a Procfile or through platform-specific buildpack configuration.

For static websites, the Front-End Web Cloud Native Buildpack provides a web server that delivers the generated frontend files.

The deployment process follows this structure:

HTML, CSS, JavaScript
          |
          v
     Git Repository
          |
          v
   Heroku Build Process
          |
          v
   Static Web Buildpack
          |
          v
    Static Web Server
          |
          v
       Browser

The buildpack identifies the directory containing the website files and prepares the application to serve them.

For a basic website, developers do not need to create a separate Node.js server just to return HTML files.

One important distinction is that the buildpack serves static content. It does not automatically provide backend functionality, database operations, or server-side rendering.

Creating a Static Website Project

Let's create a simple website using HTML, CSS, and JavaScript.

Start by creating a project directory:

mkdir heroku-static-site
cd heroku-static-site

Create the following directory structure:

heroku-static-site/
│
├── public/
│   ├── index.html
│   ├── about.html
│   ├── style.css
│   └── app.js
│
└── project.toml

The public directory contains the files that the web server will deliver to visitors.

Creating the Homepage

Create a file named index.html inside the public directory.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">

    <meta name="viewport"
          content="width=device-width, initial-scale=1.0">

    <title>My Static Website</title>

    <link rel="stylesheet" href="/style.css">
</head>
<body>

    <header>
        <h1>Welcome to My Website</h1>
        <p>A simple website built with HTML, CSS, and JavaScript.</p>
    </header>

    <main>
        <section>
            <h2>About This Website</h2>

            <p>
                This is a static website that does not require
                a backend application server.
            </p>

            <button id="welcomeButton">
                Click Me
            </button>

            <p id="message"></p>
        </section>

        <a href="/about.html">About Us</a>
    </main>

    <script src="/app.js"></script>

</body>
</html>

The page contains a heading, description, button, and navigation link.

The CSS and JavaScript files are loaded directly by the browser.

Adding CSS

Create style.css:

body {
    margin: 0;
    font-family: Arial, sans-serif;
    background: #f4f6f8;
    color: #333;
}

header {
    background: #354b9c;
    color: white;
    padding: 40px 20px;
    text-align: center;
}

main {
    max-width: 900px;
    margin: 40px auto;
    padding: 20px;
    background: white;
    border-radius: 8px;
}

button {
    padding: 10px 20px;
    border: none;
    background: #354b9c;
    color: white;
    cursor: pointer;
    border-radius: 5px;
}

This stylesheet controls the appearance of the website.

Adding JavaScript

Create app.js:

const button = document.getElementById("welcomeButton");

const message = document.getElementById("message");

button.addEventListener("click", () => {
    message.textContent = "The website is working correctly!";
});

This code adds a browser-side interaction.

There is no need to run an Express application because the JavaScript executes in the visitor's browser.

Configuring the Heroku Static Web Buildpack

After creating the website, configure the buildpack to identify the directory containing the static files.

Create a project.toml file in the root directory.

[_]
schema-version = "0.2"

[[io.buildpacks.group]]
id = "heroku/static-web-server"

[com.heroku.static-web-server]
root = "public"
index = "index.html"

There are two important configuration properties.

The root property identifies the directory containing the website files.

The index property identifies the default HTML document returned when someone opens the website's root address.

In this example, Heroku serves files from the public directory and uses index.html as the homepage.

A common mistake is setting the root directory to the project directory instead of the directory containing the actual website files. This can cause missing pages or unexpected file responses.

Deploying the Website to Heroku

Once the project is ready, prepare the deployment environment.

Step 1: Install and Configure Heroku CLI

Install the Heroku CLI and authenticate:

heroku login

Verify that authentication is successful before continuing.

Step 2: Create a Heroku Application

Create an application:

heroku create my-static-site

Use an available application name.

Step 3: Initialize Git

If the project is not already a Git repository, initialize it:

git init

Add the project files:

git add .

Create a commit:

git commit -m "Add static website"

Step 4: Deploy the Application

Push the application to Heroku:

git push heroku main

During deployment, Heroku reads the buildpack configuration and prepares the static web server.

If your local branch is named master, use the appropriate Git push command for that branch.

Step 5: Open the Website

After deployment, open the application:

heroku open --app my-static-site

The homepage should now be available through the application's Heroku address.

If the website does not load, inspect the deployment logs:

heroku logs --tail --app my-static-site

The logs help identify build failures, startup problems, and missing configuration.

Deploying React and Vite Applications

A static website does not have to contain manually written HTML files.

Modern frontend frameworks generate static files during their production build process.