Using Statamic as a CMS alongside a Laravel App

“So, when will we get WordPress and Yoast installed” I’m asked in our weekly standup.

I’ve just finishing the MVP of a Laravel SaaS I’m building. A few too many redesigns has buried the original conversation about using Statamic as CMS on this project.

So we’re using Statamic. The much hyped, much loved, super fast, flat-filed, version-controlled, radical CMS. If you're not sure what I'm on about, this page has a good explainer on what makes it different.

The latest version 3 works alongside your Laravel application. It was in early beta when we first started the discovery process and I was confident back then it would be a good fit for this project. Now we’re closer to launch I’m feeling confident about that choice. But how does it stack up in practice?

Don’t worry... I just want A WordPress and great SEO I’m told — well, there is a whole separate blog post needed to unpack that.

WordPress is to CMS as Hoover is to Vacuum Cleaner. What they want is a great CMS and Statamic fits the bill on paper. It has a fantastic marketplace and lots of SEO alternatives to Yoast I explain. Most importantly it can slide in next to our application on the same domain and use the tailwind config I've already used, so we have less overhead and can keep all links pointing to the same domain.

Yesterday I delved in. I got frustrated in places and in other places loved the simplicity. Despite these frustrations I can’t deny I’ve built quickly and it’s all within the same system as my existing Laravel project. Perfect! It also made me realise WordPress gets a lot right out of the box.

I’m going to do two things in this post:

1. I’m going go through the files I think are needed for the majority of sites needing a blog and a page CMS, with default fields set up a la WordPress.
2. Outline some of the new terminology and confusion spots I found.

If you prefer, head to this repository to take a look around the code.

Creating basic blog and CMS with Statamic

Hats off, the Documentation for the beta is pretty good. It’s funny, knows it's audience and has some good hot tips. It suffers a little bit with jargon and expects you to know your way around. I think the onboarding in general could be much improved. I suspect once they complete their blog tutorial section it will be a lot easier.

Anyway, no worries, I’m here to run through how I got on and my process.

I used the Discord chat channel quite a lot and it has a really friendly and helpful community if you get stuck. I also pestered a few other Laravel/Statamic developers I know (thanks!).

I installed Statamic alongside an existing Laravel app. I first had a headache because I had my config settings cached, but once I’d cleared that I had Statamic installed. Then head to this domain to access your control panel: https://domain.local/cp

You’ll need a new user account, so create one using the Statamic please command:

php please make:user

Ok, now we are in, let’s look around and get started and build a basic CMS. I just want to create a blog and place for pages/landing pages.

Step 1. Creating Collections

Collections are Post Types (or CPTs if you are uber-geeky, Custom Post Types)

I created these collections and created them via the control panel:

• Articles
• Pages

Most of the settings are fairly well explained so fill in as expected. These settings are saved as .yaml files in the /content/collections/ directory. This is also where the file’s of your content will be saved.

By default Statamic doesn't interact with your database. As I already had Users and Auth setup, I setup my Statamic instance to work from the User db, but I digress!

Further settings include assigning which view files are going to be used for your collections. We’ll be creating a layout file and then a specific collection file later and when we do this is where we get to assign them.

You can add your routing as you require. For posts I chose /slug and for the blog I chose /blog/slug

Step 2. Creating Blueprints

Blueprints belong to Collections. They determine the fields used on a collection. Statamic will save your settings in the resources/blueprints folder.

I created a Blueprint for Articles and Pages. Both had similar setups

• Bard is the name for your content area. Think TinyMCE if you are coming from WP
• Assets can be used for Featured image
• Users can be added to add an Author field (probably not needed for pages)

I also wanted to have some custom fields for my Users/Authors (such as Avatar). I was unable to create a blueprint via the control panel for my Users (errored!), so I created the file manually with the additional avatar field and that worked fine.

You could create this all by writing yaml files, but for someone not familiar with the yaml requirements of Statamic it was easier to build via the control panel.

Step 3. Setup Assets

Your asset container is where your assets are saved and you will need to get this setup. Head to the Assets section of your Control Panel where you can add this. I chose a local file driver and linked my created Articles Blueprint.

Step 4. Let’s code our view files

We can create a new page or article from the control panel, but we won’t see anything until we build out our view files.

We can use blade or antlers for our templates. I started to use blade as it’s what I know but I saw a hot tip from the blog that explained there was more core functionality. So I've been using Antlers and can confirm it's a doddle.

I’ve built my application in Inertia/Vue so already have the layout files created. I didn’t want to duplicate these Vue files but didn’t see a way around it. So now I have two headers and two footers. This means I will have to be mindful of updating in multiple places in the future.

If I had built using Blade perhaps I wouldn’t have this issue.

I wanted to keep my Statamic files separate so I created a directory called

resources/views/statamic/

In here I created :

/view.antlers.html
/layout.antlers.html

/articles
  /index.antlers.html
  /layout.antlers.html
  /single.antlers.html

/pages
  /blog.antlers.html
  /single.antlers.html

Within our Collection settings we can then set these layout and the template files.

Step 4. Styling with Tailwind

This might not apply from you, but if you are already deep down the Laravel and Statamic route the chances are you’ve drunk the Tailwind cool aid like me.

In that case we are going to need to style the rich text coming out of the Bard content editor.

To do that we need to make use of the @apply approach in our Sass/Css. To do this I added a wrapper in my layout file called statamic-wrapper

Like this

<div id="statamic-wrapper" class="container pb-20 mt-10">
    {{ template_content }}
</div>

Then within our Sass we can apply styles like so:

#statamic-wrapper {
    h1 {
        @apply text-xl font-bold;
    }

    h2 {
        @apply text-lg font-bold;
    }

    h3 {
        @apply text-lg;
    }
}	

Step 5. Setting our routes

We can setup our routes in our Collection settings. So for my articles I created:

/blog/{slug}

I got a bit stumped about how to approach created an Index Page (or Archive if you come from WP) for each Collection. This is the page where we loop through and display the collection items.

This does not seem to exist out of the box. The way I did this was to use our Page collection and create a specific page. So I created a page called Blog .

Now this is the clever part (humour me!). I went back to our blueprints section and added a field called Template.

Now we have the option to select a specific View file per page. Once I had that I created a blog view file and looped through the articles using antlers. Set the slug to /blog/ et voila! Not totally intuitive, but really flexible once you know.

Here is the link to the repository to take a look for yourself.

Conclusion

I think that last step really tells you a lot about Statamic. It’s a bit of a faff to go though that rather than it being out of the box, but actually it gives a lot more flexibility ongoing.

It’s not so opinionated - this can be frustrating but the flexibility it gives you is it's biggest asset.

In fact I’d go so far as to say it would be great if it was a bit more opinionated, or at least had the option to setup per the above settings on initial install to get you going.

I’ve crudely added my files to a repository for anyone to download and look at. I’ll look into formalising the code and perhaps making an add-on so it’s a lot quicker to get up and going with Statamic.

The other frustration is the lingo. I think Collections, Blueprints and Bard are all very well but not totally intuitive. It didn't take long to discover what they mean, but it would be good if it was more clearer from the get go.

Finally a big shout out to Ross Wintle who was an absolute gent and gave me some help throughout!