Netlify

• Introduction
• Preparation
  • 1. Create a Netlify project
  • 2. Turn off Pretty URLs
  • 3. Create an access token
• Configuration
  • Netlify Access Token
  • Netlify Site ID
• How Deployment Works
  • Redirects, Headers and the 404 Page
• Troubleshooting
  • Connection check messages
  • Remote deployment still awaits required files
  • Missing required option
  • The site did not change after a deployment

Introduction

The Netlify deployment method uploads the generated static site directly to an existing Netlify site.

Use this method when Netlify is responsible for serving the static site and you want Staatic to publish directly to the Netlify deploy API.

This deployment method supports:

• Deployment to a Netlify site;
• Support for HTTP redirects;
• Support for generated Content-Type header rules where needed;
• Support for custom error page through generated Netlify configuration.

Preparation

1. Create a Netlify project

Create an account on https://www.netlify.com/ and add a new project with Deploy manually, dropping a folder that holds a placeholder index.html. The first Staatic publication replaces it. Netlify used to call projects sites, which is why the Staatic setting is still named Netlify Site ID.

The project does not need a Git repository or build settings, because Staatic uploads the finished files. If you do connect a repository, every production build from it replaces the deploy that Staatic published.

2. Turn off Pretty URLs

Staatic already writes the final URLs into the generated pages, so Netlify should not rewrite them. In the Netlify App, go to Project configuration > Developer settings > Post processing and make sure Pretty URLs is disabled.

3. Create an access token

In the Netlify App, open your user settings, go to Applications > Personal access tokens and click New access token. Copy the token immediately, because Netlify only shows it once.

Netlify asks for an expiration date. When the token expires, deployments fail until you enter a new token in Staatic. If your team signs in with SAML single sign-on, also give the token access to that team, or Netlify will deny Staatic’s requests.

Configuration

In order to configure the Netlify deployment method, head over to the WordPress Admin and click Staatic > Settings > Deployment. Choose Netlify as the deployment method and make sure the following fields are entered correctly.

Netlify Access Token

The personal access token you created in step 3. Staatic stores it encrypted.

Netlify Site ID

The Project ID of your Netlify project. You can find it in the Netlify App under Project configuration > General > Project details > Project information.

After you save the access token, a connection check appears below the fields. Once you enter the Project ID, it shows which project Staatic will deploy to.

How Deployment Works

Every deployed publication becomes a new deploy of your Netlify project. Staatic only uploads the files that Netlify does not have yet, so later publications upload only the files that changed. The HTTP Concurrency setting controls how many uploads run in parallel. Staatic then waits for Netlify to process the deploy, which can take longer than the upload itself. When it is done, Staatic adds the deploy URL and Netlify’s messages to the publication log.

The new deploy goes live right away, unless auto publishing is locked for the project.

A deploy contains only the files of that publication. Unlike Amazon S3 and GitHub, Netlify has no option to keep other files. A selective publication that is not merged therefore replaces your site with the selected files only. Publish Changes in Staatic Premium merges with the active publication first, so its deploy still contains the complete site.

Redirects, Headers and the 404 Page

Staatic adds a generated netlify.toml file to each deployment:

Developers can change the generated configuration with Staatic hooks, but most sites do not need to.

Troubleshooting

Connection check messages

Remote deployment still awaits required files

Some uploads failed, and the publication log shows the reason for each one. Netlify rate limits API requests, which mostly affects the first deployment of a large site, when every file is uploaded. Lower HTTP Concurrency and publish again.

Missing required option

Missing required option "accessToken" or Missing required option "siteId" means one of the two fields is empty. Enter both and save the settings before you publish.

The site did not change after a deployment

Open the Deploys list of your project in Netlify:

• If the deploy failed, Netlify’s reason is in the deploy messages in the publication log. Staatic does not detect failed deploys, so the publication itself still shows as finished.
• If the deploy is ready but not published, auto publishing is locked. Publish the deploy in Netlify, or unlock auto publishing.
• If a newer deploy came from Git, a repository build replaced the Staatic deploy.