Setting up Your Mac for Local Statamic Development

I recently picked up a new Macbook, as my old 2017 model was breaking down more and more. I wanted to get back to work as quickly as possible, so first I set up everything I need to develop Statamic sites on my own computer.

It really is amazing how simple and fast this process is thanks to modern tools. A hand full of terminal commands and less than half an hour and you're done. Here are the steps that I followed, in case you're in the same boat.

Get All the Package Managers!

Okay, maybe only three of them. Setting up and working with package managers may take a few days to get used to, but they will save you loads of time and frustration going forward.

If you're not as old as me, let me just tell you: you don't want to go back to the times where we had to manually install and version match all our programs and libraries. Just thank the programming gods for these amazing tools and take the time to get comfortable with them.

Homebrew - macOS Package Manager

Yes, we will be using a package manager to install other package managers (amongst other things), but trust me, it's the easiest way. Just head on over to the Homebrew website to copy the installation command and paste it to your terminal, as it might change by the time you read this post.

This command will install Homebrew itself, but also some other tools that we will need to develop on our mac - like Xcode. The process will take a bit, once it's finished you can double check the successful installation by running brew -v in your terminal, this should return the version of Homebrew that you just installed.

I wasn't so lucky, instead I got an error message starting with: Warning: /opt/homebrew/bin is not in your PATH. But with my secret super power of reading the full error message, I was able to fix this by simply running the two additional commands provided by the installation dialogue.

Composer - PHP Package Manager

Statamic is built on top of Laravel which is written in PHP, and both require installing a whole host of PHP libraries. So we use Composer to manage all of these dependencies for us so we can sleep at night.

Normally you'd have to manually download and install Composer, but thanks to the previous step we can just use Homebrew, by running brew install composer in our terminal. Once again there will be lots of super informative output, but in the end you can run composer -V to make sure everything went according to plan. You might once again have to add it to your PATH via echo 'export PATH="$PATH:$HOME/.composer/vendor/bin"' >> ~/.zshrc.

Normally you would still have to install PHP on your laptop now, but since Composer requires a current version of it anyways, Homebrew took the liberty of setting up the latest stable version of PHP at the same time as well. Neat!

NPM - Frontend Package Manager

The operating system and PHP are now taken care off, now it's on to the frontend part of web development. To use and compile all those neat CSS frameworks and JS libraries, we will need NodeJS. And to keep them up to date and working well, we will use the corresponding package manager NPM.

Once again Homebrew will come in handy. But this time we will not just run brew install node, as that would install the newest version which might not be supported everywhere. Instead I'm going with version 16, which the NodeJS website recommends for most users at the time of writing.

After running brew install node@16 it will again give you some output, including a command that will add npm to your path so you can simply use it in your terminal. After running it, restart your terminal and enter npm -v to make sure everything worked.

Turn your Mac into a Web Server

If you've been working with PHP before, you will know that (unlike HTML files for example) you can't just open a PHP file in your browser. Instead there always needs to be a web server that executes the PHP and sends the output to whoever is accessing the site.

There are a lot of options for this, from good old MAMP to fancy Docker environments. But if you're using a Mac, you're lucky enough to be able to use a super simple yet powerful option called Laravel Valet.

Setting up Laravel Valet

This development environment will install Nginx as a webserver and configure it to serve any site on your computer via a *.test domain. And it can even add an SSL certificate so you can develop just as you would on a server.

It's not only super easy to use, but equally quick to install. Since we already have Homebrew, Composer and PHP installed, just run composer global require laravel/valet in your terminal to install it globally as a Composer package.

Now just run valet install, and everything will be set up for you. Lastly we just need to tell Valet where to look for sites, e.g. in the ~/Sites folder, simply because that's what that folder is traditionally for.

It probably doesn't exist yet, so set it up with mkdir ~/Sites, change into it cd ~/Sites and run the valet park command. This will automatically turn every folder inside Sites into a website that can be accessed via the folder name + .test.

To try it out, let's set up a simple PHP file that should be accessible like a website. Create a project folder via mkdir myproject, and switch into it via cd myproject. Next create a file with touch index.php and open it in the editor via nano index.php.

I simply added the line <?php echo "<h1>Eureka!</h1>"; ?> and saved the file with Ctrl+X. Now going to myproject.test in any browser will bring up the desired output.

Installing a First Statamic Project and SSH

That's pretty much it, the magic is done. So now while in our Sites folder, we can simply setup a new project by running composer create-project --prefer-dist statamic/statamic example. Next, point your browser to example.test and you should see your brand new site is already working.

Since browsers are really pushing for secure connections, forms and some other features may not work as expected without an SSL certificate. To fix that, you can simply run valet secure example (with example being the name of the folder) to have Valet add one for you.

Note that Firefox currently does not accept these certificates, but Chrome does.

If you've followed all the steps in this guide you now have everything you need to start developing Statamic sites on your local machine. Simply install your favorite IDE and go get stuff done!