The New Folder Structure

on January 8th, 2019

Statamic 3 is a Composer package

Statamic 3 is built as a Composer package that is installed into a Laravel application, instead of being an app built on top of an included instance of Laravel included in core package (Statamic 2). This opens up the landscape of possible projects Statamic can be suited for, as well as making it much easier to extend and customize.

Need a CMS to manage your application data? Want a blog and an easy way to update site content? Run composer require statamic/cms and you're most of the way there.

In order to accomplish this, Statamic 3 adopts the traditional Laravel directory structure. If you don't already have a Laravel application, Statamic will scaffold one out for you. It's important for us to note that you do not need to know PHP or be a Laravel developer to use Statamic 3. With the exception of some files and folders being in a slightly different location, this is the same Statamic you know and love.

|-- addons/
|-- app/
|-- bootstrap/
|-- config/
|-- content/
|-- database/
|-- public/
|   |-- index.php
|-- resources/
|   |-- js/
|   |-- lang/
|   |-- less/sass/
|   |-- views/
|-- routes/
|-- storage/
|-- tests/
|-- users/
|-- vendor/
|-- artisan
|-- please
|-- composer.json

Major Changes

Time to highlight the most significant differences, and why we made the change.

Major Change #1: Webroot

The most important difference from Statamic 2 is that the core application is above webroot. As you can see in the list above, your index.php file is inside /public, one level deeper. That is your webroot.

This structure means that all your data, configs, templates, source files, and so on will not be accessible directly from the web, and you will no longer need to rely on htaccess or nginx exclude rules to protect them.

Honestly, this is the way it should have always been, but we were following conventions from other popular CMS platforms in order to make switching to Statamic easier.

Major Change #2: Where did the site directory go?

For the most part, the directories inside site have just moved up a level. Above you'll see addons, config (previously settings), database, storage, and users all in the root directory.

Sure, it was nice to able to say "Zip up your site directory and send it over" for debugging, but more often than not the next step would be to ask "What version of Statamic are you running? Where are your assets? Do you have any non-standard changes to your site structure?"

With this arrangement (which better mirrors Laravel conventions), along with Statamic being Composer installable, your repos will be smaller and easier to work with.

Major Change #3: "Themes"

Let's be honest, if you've been using Statamic for any length of time, you have one "theme". It's just your site's templates and design assets.

So we simplified it. Statamic 3 now uses the same conventions as Laravel. All your front-end resources are now inside resources/. Your templates are in resources/views, and as you can see, that directory can contain all the rest of your javascript, less/sass, and so on.

If you use a JavaScript build tool like Webpack/Gulp/Grunt, it'll be right there in your root so you don't need to cd site/themes/theme_name to run it. Just compile your assets into public/ and you're good to go.

Statamic 3 will ship with Laravel Mix preconfigured and ready to go.

Themes are now Presets

Have no fear, the notion of Statamic themes isn't gone forever. It's been upgraded to a more flexible, bespoke-friendly variation through the use of Laravel front-end presets, otherwise known as scaffolding.

There's a whole Github organization full of existing front-end presets you'll be able to take advantage of, and we're working on a number of Statamic-focused presets that take it to the next level and come with fieldsets, templates, and so on. We have a really basic Tailwind preset on Github already you can peek at.

We'll explore this feature more in an upcoming post. There's a lot of really cool stuff we'll be able to do that we couldn't with a v2 "theme". 😁

Jack McDade
Jack McDade, Creator of Statamic
Creator of Statamic

Copyright 2020 Statamic