In order to work with Kirby locally to develop our site, we need a local server capable of running a version of PHP and the necessary extensions available that are supported by Kirby.

There are a number of options here depending on the operating system you are using. Valet is popular due to its ease of use and speed. This is a good choice if you are comfortable using the command line. There are Windows and Linux ports of Valet available. MAMP is popular for bother Windows and Mac users whilst Laragon is Windows only.

Alternatively, Herd, another tool from Laravel is built on the same principles as Valet, without needing to use the command line. This is by no means an exhustive list of options with local servers. For the purposes of illustration, we use Herd and MacOS going forward in this guide, but you should be able to follow along regardless of your chosen operating system / server combination.

First things first - lets create a simple build system to allow us to work quickly locally, with the help of ESbuild and BrowserSync.

Build System

Now we have that installed we can continue to make our boilerplate that can re-used for other projects going forward. There are a number of options here in terms compilers and CSS frameworks, but in this case we will keep it simple by using ESBuild to complle SCSS and Vanilla JavaScript. Let's put it together.

The first peice of the puzzle is Node.js, since we need to be able install a few other tools that come as NPM packages. Head on over to the Node website and grab the installer for your operating system. Once that is installed, we need to enable Corepack which will give us access to Yarn. You can do this with the following terminal command:

corepack enable

Initialising Yarn

Now we are all set to create some files. Create a folder somewhere sensible on your system called "Boilerplate". Open this folder in Visual Studio Code. Whilst we can use any editor we like, VS Code is useful as it contains a built in Terminal that will save us flitting between more seperarte programs than neccessary. Feel free to use another editor if you prefer.

The first thing we need is to do is setup Yarn's package.json file so that we can add a few development dependencies to it.

Open up the terminal via Terminal > New Terminal from the main menu, which will open in the lowr half of the programs main window. Initialise Yarn by entering the folllowing in to the terminal:

yarn init

It will ask a series of basic questions about your project. Answer as best you can and you will end up with a package.json in the root of your project containing something like the following:

{
  "name": "boilerplatehtml",
  "version": "1.0.0",
  "description": "A boilerplate for HTML, SCSS and ESBuild",
  "author": "Hash&Salt",
  "email": "hello@hashandsalt.com",
  "license": "MIT",
}

Now we can install the following depenendencies that will helps us build and run our project.

@fullhuman/postcss-purgecss
autoprefixer
browser-sync
dotenv
esbuild
esbuild-copy-static-files
esbuild-sass-plugin
postcss

We can do this in one shot with the follwing single line terminal command:

yarn add @fullhuman/postcss-purgecss autoprefixer browser-sync dotenv esbuild esbuild-copy-static-files esbuild-sass-plugin postcss -D

Configure Vite

Iside the public folder create an blank html file containing the following:

Configure local domain

We just have a couple of final steps now before we can see the result of all this hardwork! We need to set up a local domain name so that we can see what we are working with during development. As discussed previously, we will be using Herd for the purposes of demonstration. If you decide to use another local server, the steps below will differ slightly.

In the root of the project create a .env file containing the following:

APP_URL = "boilerplatehtml.test"

Open up a terminal. Make sure you are inside the public folder when you run the following command:

herd link boilerplatehtml

This will map the public folder to a local domain called boilerplatehtml. If you open up a browser and visit boilerplatehtml.test you should see a Hello World! message in all it's glory! Awesome.

Triggering the build

So far so good, but how do we actually kick off a development or production build? Well, NPM scripts to the rescue. Open up the package.json file and add the following under the license entry:

"scripts": {
    "build": "NODE_ENV=production node ./config/esbuild.mjs",
    "start": "NODE_ENV=development node ./config/esbuild.mjs"
},

Finally, it's moment of truth time! Head on over the termainal and enter the following command to launch the site in a browser with live reload enabled.

yarn start

If all went well, you should see a Hello World! message again in the browser. However, try changing the HTML, CSS or JS file and you should see it live update when you save changes.

Now we have the foundations working, we can take it a bit further, replacing the static HTML file with Kirby.