20 principles for Craft CMS

Rules of thumb when making a website on the wonderful Craft Content Management System. Based on two years of developing Craft-based websites for clients.

This is our opinionated list of principles for Craft CMS. Some are certainly contestable, some are just common sense, and some are the product of trial and error. These principles range from project management, code structuring, to the field and section structure within the Craft control panel.

1. Start the project with setting up developer, staging and production environment. This will make the launch way less stressful.

2. Start early with the information architecture. Work together with people who will be writing content to set up sections and fields. This will allow you to work with real content, and discover needs for features early.

3. Don’t chase waterfalls: try to work with graphic design, content and frontend development simultaneously.

4. If you feel the need for a matrix-block in a matrix-block, reconsider your information architecture. You’re probably doing it wrong.

5. If you make a “content”-matrix block, keep it simple by avoiding more than six block types.

6. Build your templates up from modules. Keep the HTML in those to allow for both flexibility and consistency. Use them to make page templates. Stay DRY and remember to default variables.

Example of a module

7. If you ending up writing a lot of twig to solve the thing, consider making a plugin instead (it’s not as difficult as it may seem).

8. Make sure to discuss, review, show your Craft project to another developer at least once every 40 project hours.

9. Take the time and write good descriptions for your fields. You will not “just do it later”.

10. Use image transforms. Think of your users’ bandwidth.

11. Restrict the rich text editor as much as possible. Don’t allow images in it as it creates more complex code and usually allow for bad layout decisions.

12. Panes are used for hiding stuff that isn’t really that important.

13. Debugging Craft: Have you introduced a PHP-error in the settings? Have you set the necessary .env-variables? Have you installed all the dependencies? Is there some difference between your development, staging and production enviroment? What do the logs say? Have you messed up the caching? Are you trying to access a field that isn’t there? Have you really read the error message? Have you read the documentation? Have you searched Stack Overflow or asked in the Craft Slack?

14. Singles are for unique pages with their own template, whose content isn’t used other places — typically frontpages for listing out channel entries and so on.

15. Channels are for structured content that either makes sense as a stream, or a group of similar content (e.g. news or products). Channels are also good for content that will be reused in several contexts.

16. Structures can be useful if you want to have a flexible hiearchy of content, where the hierarchy is important for managing the content.

17. Categories are mostly used for pure metadata and to connect content across sections.

18. Use primarily unique and channel sections. Avoid structures. We tend to not use structures because we prefer a pretty shallow information architecture and it’s prone to content entropy.

19. Some plugins make any Craft project easier: Admin Bar, CP Field Links, Element API, Kint, Linkit, Sprout Fields / Forms, and Retour. (And a bunch more on Awesome Craft).

20. Whatever you do, consider how your choices will affect the client’s ability to make good choices when managing their content, and how easy it will be for your future self to troubleshoot and further develop your code.

Not so much a principle as good advice: keep up to date by subscribe to the Craft Link List newsletter and listen to the Craft.Podcast.

What are your principles for projects on Craft CMS?