Tutorial

Intro

A Builderoo theme, similar to any website, is composed of pages. Each page is represented by a JSON file located in the pages directory. Every page consists of a layout and one or more section. These layout and section are React functional components, each residing in their own files within the layouts and sections directories respectively.

Learn more about layouts, sections and pages.

At the end of this tutorial, you’ll have a folder structure like this:

Let’s get started.

Create the project

Run the following command on your terminal to create a new theme project:

npx create-theme@latest
# or
yarn create theme
# or
pnpm create theme
# or
bunx create-theme

This will ask you for a project name and create a directory structure with minimal files for you to work on. Open this directory in a code editor to start developing your theme.

Create a layout

Create a folder named layouts in the root directory. Now create a component file MainLayout.jsx in this directory with the following content

import React from "react";
 
export default function MainLayout({children}){
  return (
    <div>
      {/* Header content */}
      <header>Site Header</header>
      <main>
        {children}
        {/* main content, aka Sections, are dynamically passed as the children prop */}
      </main>
      {/* Footer content */}
      <footer>Site Footer</footer>
    </div>
  )
}

Learn more about layouts.

Create a section

Create a folder named sections in the root directory. Now create a component file HeroSection.jsx in this directory with the following content.

import {Link} from "builderoo"
 
export default function HeroSection() {
 
  return (
    <section>
      <img src="/hero-image.png" />
      <div>
        <div>20% discount</div>
        <h3>Summer Collection</h3>
        <div>
          Choose your outfit from the summer collection
        </div>
        <Link href="/collection/summer-collection">
          Browse Now
        </Link>
      </div>
    </section>
  );
}

Create a page

Create another folder named pages in the root directory. Now create a json file index.json in this directory with the following content.

{
  "layout": {
    "component": "MainLayout"
  },
  "sections": [
    {
      "component": "HeroSection"
    }
  ]
}
 

Now run npm run dev and open http://locahost:3000 in the browser.

Improve the section

So far, the contents in the above component are static. Let’s define dynamic props for the contents.

import {Link, Prop, useProps} from "builderoo"
 
export const props = {
  image: Prop.image(),
  subtitle: Prop.text(),
  heading: Prop.text(),
  description: Prop.text(),
  link: Prop.url(),
  linkText: Prop.text()
}
 
export default function HeroSection() {
  const {image, subtitle, heading, description, link, linkText} = useProps()
  return (
    <section>
      <img src={image}/>
      <div>
        <div>{subtitle}</div>
        <h3>{heading}</h3>
        <div>
          {description}
        </div>
        <Link href={link}>
          {linkText}
        </Link>
      </div>
    </section>
  );
}

Now the users can provide values for these props in the theme editor.

Line 3-10 here is called the prop definition of the Section. It must start with export const props =. This prop definition is used to provide appropriate types of values for these props in the theme editor.

In TypeScript you can provide types for the props and enjoy type safety and autocompletion in smart IDEs. Learn more.

To access the props, you can also use the useProps() hook.

Enhance the page

Now we’re ready provide some values for these props in the index.json file for a nice preview:

{
  "layout": {
    "component": "MainLayout"
  },
  "sections": [
    {
      "component": "HeroSection",
      "props": {
        "image": "/hero-image.png",
        "heading": "Summer Collection",
        "subtitle": "20% discount",
        "description": "Choose your outfit from the summer collection",
        "link": "/collection/summer-collection",
        "linkText": "Browse Now"
      }
    }
  ]
}
 

Apart from props you can also define another thing called blocks in the section. blocks are convenient in designing complex sections. Learn more

Creating more pages

To create a page, create the sections you want, and create a corresponding page json file.

Conclusion

In this tutorial, we have learned that we can create a schema for a section and values for the props can be provided from the theme editor. There are some special pages, for example, pages for product, collection etc., The main value (e.g. product/collection value) for these pages come directly without defining a schema. You can learn more about different types of pages in Pages