Open navClose nav

Preview Commands

Instant previews allow for you to spin up a development server in our preview environment which will drastically reduce preview times in most cases.

To help you get started, we provide default commands. You can then tailor preview settings to your needs, if your website source lives in a subdirectory for example or if you use a different script to run your preview.

How to use instant previews.

Preview Environment

All sites are built in a Linux container and have access by default to the following tools:

  • Ruby / Bundler for Jekyll websites
  • Go / Hugo
  • NodeJS, NPM, Yarn for NodeJS based SSG like Gatsby, Gridsome, Nuxt, Eleventy, etc.

Hugo and Jekyll users relying on node modules for their asset pipeline can also use a preview environment embedding NodeJS.

If your project has a package.json file, your node_modules will be installed automatically. You should use NPM or Yarn scripts in your build commands.

In the advanced settings, you can also provide any custom Docker image hosted on https://hub.docker.com if your project has specific dependencies.

Preview Command settings

Preview command configuration in Forestry consists of the command, the output directory, advanced settings, and any number of environment variables.

Command

The Command is a shell command that will be run inside the build environment to generate your site.

Output Directory

You will use the Output Directory setting to tell Forestry where to find the generated HTML of your site after the build runs. For example, if you set your command to npm run develop, and that your site will be generated into a folder named dist, you should set your Output Directory to dist.

Why do I need to set the output directory in two places?

When we build your site, we treat your build command as a black box. In the above example, Forestry doesn’t know that the HTML is being generated in the dist folder. We use the output directory setting to tell Forestry to look in the dist/ directory to host the preview .

Environment Variables

Environment variables are values that will be passed into the preview environment. Depending on the static site generator you’re using and how your site is coded, you can control different behaviors with environment variables.

Additionally, you can override the following variables to control the preview environment:

Variable Description Default
HUGO_VERSION Version of Hugo to use Version selected when importing site
HUGO_ENV Environment used by Hugo staging for previews
JEKYLL_ENV Environment used by Jekyll staging for preview

Customizing the Preview Command

To modify your site’s preview command, head to Settings > Previews. The Configuration section will contain fields to configure the command, output directory, and environment variables.

Alternatively, you can configure preview commands directory in your .forestryio/settings.yml file under the build namespace.

Examples

JS-based static site generators: Gatsby, Gridsome, Eleventy, Next, etc.

For a JS-based static site generator build from a src subfolder and aliasing npm start to the development command in the package.json, you would write:

build:
  preview_docker_image: node:10
  install_dependencies_command: npm install
  instant_preview_command: npm start
  mount_path: "/srv"
  working_dir: "/srv/src"
  preview_output_directory: "src/dist"
  preview_env:
  - ENV=staging

Here the preview environment will launch the NodeJS 10 official Docker image, install dependencies with NPM, build the site from the srcsubfolder with the npm start command and output the site in src/site. We also pass a global ENV variable here to avoid production optimizations.

Hugo example

For a Hugo website, .forestry/settings.yml will default to:

build:
  preview_docker_image: forestryio/hugo:latest
  install_dependencies_command:
  instant_preview_command: hugo server -D -E -F --port 8080 --bind 0.0.0.0 --renderToDisk -d public
  mount_path: "/srv"
  working_dir: "/srv"
  preview_output_directory: "public"
  preview_env:
  - HUGO_VERSION=0.57.2
  - HUGO_ENV=staging

Jekyll example

For a Jekyll website, .forestry/settings.yml will default to:

build:
  preview_docker_image: forestryio/ruby:2.6
  install_dependencies_command: bundle install --path vendor/bundle
  instant_preview_command: bundle exec jekyll serve --drafts --unpublished --future --port 8080 --host 0.0.0.0 -d _site
  mount_path: "/srv"
  working_dir: "/srv"
  preview_output_directory: "_site"
  preview_env:
  - JEKYLL_ENV=staging

Hexo example

Provided you added an npm script to run Hexo server on 0.0.0.0:8080, .forestry/settings.yml for an Hexo site could look like:

build:
  preview_output_directory: public
  install_dependencies_command: npm install
  preview_docker_image: node:10
  mount_path: "/srv"
  working_dir: "/srv"
  instant_preview_command: npm run forestry:preview

Default commands

build:
  instant_preview_command: hugo server -D -E -F --port 8080 --bind 0.0.0.0 --renderToDisk -d public
build:
  instant_preview_command: bundle exec jekyll serve --drafts --unpublished --future --port 8080 --host 0.0.0.0 -d _site
build:
  instant_preview_command: npm run forestry:preview
build:
  instant_preview_command: npm run forestry:preview
build:
  instant_preview_command: npm run forestry:preview
HugoJekyllGatsbyVuePressGeneric

Using NPM scripts as Build Commands

Of course, many modern frontend stacks leverage NPM libraries and might have a build process managed by a tool like Gulp or Webpack. Our build environment will automatically install your NPM packages and can run NPM scripts defined in a package.json file.

When using custom build tools not already supported by our build environment, using NPM scripts is the recommended way to incorporate these tools into your preview or publish command.

In the following example, we will run our instant previews as an NPM script:

1. Install SSG in your project

This step is important, as you could otherwise run node packages on your local machine by installing them globally, but Forestry won’t have these global packages installed.

npm install --save gatsby-cli
npm install --save @11ty/eleventy
npm install --save @gridsome/cli
npm install --save vuepress
npm install --save next react react-dom
GatsbyEleventyGridsomeVuePressNext

2. Configure a build script in package.json

Commands run as NPM scripts will automatically include any installed node modules in your PATH. Adapt those commands if you site source lives in a subfolder.

"scripts": {
  "forestry:preview": "gatsby develop -H 0.0.0.0 -p 8080"
}
"scripts": {
  "forestry:preview": "eleventy --serve"
}
"scripts": {
  "forestry:preview": "gridsome develop"
}
"scripts": {
  "forestry:preview": "vuepress dev"
}
"scripts": {
  "forestry:preview": "next -p 8080 -H 0.0.0.0"
}
GatsbyEleventyGridsomeVuePressNext

3. Run the NPM script in your build command

build:
  instant_preview_command: npm run forestry:preview
  preview_output_directory: dist
build:
  instant_preview_command: npm run forestry:preview
  preview_output_directory: _site
build:
  instant_preview_command: npm run forestry:preview
  preview_output_directory: _site
build:
  instant_preview_command: npm run forestry:preview
  preview_output_directory: .vuepress/dist
build:
  instant_preview_command: npm run forestry:preview
  preview_output_directory: .next
GatsbyEleventyGridsomeVuePressNext

Last updated on August 7, 2019