Concepts overview
Overview of concepts for Built.js themes and plugins.
How Built.js works
What is a theme?
A theme is a Next.js app which has data files. It is used for creating Next.js websites that have a Sanity content management system.
A theme can have any number of modules. A module represents a business use case, and contains all the pages and sections to fulfill the use case. It has module pages, each of which assigns sections to a page. Consequently, a page is "dumb", not directly determining its sections.
A section determines the content. It can have one or more templates which display the content differently, giving the end user of the theme a number of options for the section's user interface. A section can have a number of collections. A collection is a group of items, or entries, of a certain content type. Collections may or may not have an associated [article] page(/docs/concepts/article).
You may wish to have small reusable content types such as that can be used for UI components. These are called elements.
A theme can also have any number of plugins. A plugin is a single module which is external to the theme. You may also need to store global data for your theme. The global content type can used for this purpose. Currently, Built.js themes and sites are limited to one common layout for all pages.
How are themes created?
If you know how to create React components, you can easily create your own theme by following the following steps:
Create the theme's definitions in Built Studio
To create a theme, you can use the Built Studio Designer to define the modules, pages, sections and other items.
Export the theme, set up the Next.js theme project, and create components
When you export (download) your theme from Built Studio, it contains the definitions but no code for the sections yet. The setup process outlined in the README will help you create the Next.js project with the theme configuration. Then, you design the React components for each section.
Publish theme to your Built Studio workspace
When you're ready to use your theme to create sites with, publish it to Built Studio using npx create-built-app publish.
Learn more about the lifecyle of a theme or plugin.
How are plugins created?
A plugin is very similar to a theme, except it only has one module, so the process is essentially the same.