Installing a Private Starter Kit in Statamic

Why Use Statamic Starter Kits?

A while back I already wrote a post explaining how Starter Kits are similar but not exactly the same as WordPress Themes, so I won't get into too much detail here.

In short, Starter Kits allow you to gather all the files and settings you end up repeating for new Statamic projects and adding them to a new site with a single command. That way you won't have to create the same blueprints, fieldsets, and templates every single time and you can also be sure that settings such as your .gitignore, your webpack.mix.js, or especially your tailwind.config.js are the same across all projects.

For the Starter Kit I use for client sites I have also added a bunch of sample pages, navigation entries and dummy content. This way I can start changing the basics such as fonts and colors and see the results right away, which saves me from having to copy and paste a bunch of lorem ipsum every time.

If you want to learn more about Statamic's Starter Kits, read the official documentation or check out existing ones on the Statamic Marketplace.

My Super Secret Starter Kit

While it's super useful and saves me loads of time, I'm currently not looking to make my personal Starter Kit publicly available. It's simply nowhere near polished enough to show it to the general public. Also it's very tailored to my personal workflow and there are a ton of tweaks and gotchas you need to know to start working with it.

Maybe at some point in the future I will make a version I can share, but for now the Starter Kit lives in a private GitHub repository: https://github.com/stoffelio/secret-starter-kit

This keeps it safe from other people, but creates a new issue: installing my Starter Kit using the CLI command simply doesn't work anymore, as composer has no way of finding my private repository.

No real surprise here. When you run the install command, under the hood composer simply checks Packagist for a package matching the provided name. But you didn't publish your repository there, so as far as composer is concerned, your repository doesn't exist.

Let's change that.

Tell Composer Where to Find Your Starter Kit

Since we don't want to publish our repository, we will need to give composer an alternative way of finding it. To do so, we need to head to our composer.json file and tell composer that we also want to check out our specific repository, which only takes a few lines of code.

At this point composer is aware of our repository, but you might get an error like in my following code snippet. Simply add .git to the end of your repo name to proceed, no point arguing with composer, it knows better.

So next we have to try and run php please starter-kit:install stoffelio/secret-starter-kit.git, which will lead to one of two outcomes.

On my primary development server the Starter Kit was now installed without any further issue. The reason is simple: since I worked on this server before, the server's SSH key was already added to my GitHub account and granted access to all my repositories, which composer was able to use to retrieve the files.

If this isn't the case for you, then there are just a couple extra steps to take.

Generating a Personal Access Token

The second way to grant composer access to your repo is via a personal access token, which works like ordinary OAuth access tokens for authentication without a password.

If this is what you need to do, composer will give you the instructions you need.

Heading over to https://github.com/settings/tokens/new gives you a form to create a new token.

There is a whole list of scopes you can chose from to determine what the token owner is allowed to do. In my experience, simply activating the repo category (full control of private repositories) is what's needed for our use case.

It shouldn't matter too much as long as you don't give that token out to anybody else. You can also limit the time that the token is valid, or simply manually delete it right after successfully installing the Starter Kit.

Once you're done you will receive a short key, which you need to copy since it won't be shown again. Simply use that token and the command provided by composer before to set up your token on the server:

Note that this will be globally installed, meaning that other people on the same machine could now also access your repos.

Now you can run the install command again, and since composer can access your private repository, everything should go as planned.

If you create a long living access token for your development server, you only have to do this once and can then simply add the repository to your composer.json and install the Starter Kit for each new projects in a matter of seconds.