The example project contains a site demonstrating the use of Faust features like WordPress template hierarchy and the plugin system. You can use this project for basing your future projects and as a good reference site.

How to Get the Example Working Locally

If you followed the Getting Started guide, you will have to create a new app using the template and connect your WordPress site.

Then you can navigate to the my-app folder and inspect the code.

The File Structure Rationale

The example project follows the typical conventions of the Next.js file based routing. Here is the output of the tree command on this folder:

Project folder structure:

❯ tree -L 2
.
├── README.md
├── components
│   ├── Container
│   ├── ContentWrapper
│   ├── EntryHeader
│   ├── FeaturedImage
│   ├── Footer
│   ├── FormatDate
│   ├── Header
│   ├── Heading
│   ├── Hero
│   ├── Main
│   ├── NavigationMenu
│   ├── Post
│   ├── PostInfo
│   ├── SEO
│   ├── SkipNavigationLink
│   └── index.js
├── constants
│   ├── menus.js
│   └── selectors.js
├── faust.config.js
├── fragments
│   └── GeneralSettings.js
├── next.config.js
├── package.json
├── pages
│   ├── [...wordpressNode].js
│   ├── _app.js
│   ├── api
│   ├── index.js
│   └── preview.js
├── possibleTypes.json
├── styles
│   ├── _base.scss
│   ├── _blocks.scss
│   ├── _breakpoints.scss
│   ├── _css-variables.scss
│   ├── _utilities.scss
│   └── global.scss
└── wp-templates
    ├── category.js
    ├── front-page.js
    ├── index.js
    ├── page.js
    ├── single.js
    └── tag.js
Code language: CSS (css)

Let’s break down what you see here:

components: This folder contains the various components that all pages and templates use. They are highly re-usable and for purely presentational purposes.

constants: This folder contains a few hardcoded constants that are used in queries.

fragments: This folder contains individual GraphQL fragments that are common between queries.

pages: This folder contains the Next.js file based routes that are used to render the associated pages.

styles: This folder contains a list of scss styles that are used to apply the theme to the site.

utilities: This folder contains some useful utilities.

wp-templates: This folder contains a list of WordPress templates that are used to render the site pages based on a system that mimics the WordPress template hierarchy.

Now that you have a good picture of the folder structure, let’s take a look at which files you should be changing if you wish to customize this theme.

Changing Example Files

Instead of telling you what you should change, you can follow the below how-to sections that will help you customize the theme for your needs.

How do I change the styling of the site?

To change the styling of each component you can navigate to the components folder and change the CSS styles in the .module.scss file. If you want to change the global styling of the site or the style of the pages, you can navigate to the styles folder and make your changes there. Each scss module contains documentation strings for your convenience.

How do I change the pages layout?

To change each page’s layout, you will need to review the wp-templates folder and make your changes there. For each type of page that corresponds to the WordPress template hierarchy, there are different layouts and queries. For example, the page.js represents the “page type” and the single.js represents the “single post type”. You can reuse the existing components or create new ones that fit your requirements.

How do I change the GraphQL queries?

Most of the queries are located within each wp-templates component. If you look at the definitions of each component, there are query and variables properties:

// In wp-templates/front-page.js
...
Component.query = gql`
  ${BlogInfoFragment}
  ${NavigationMenu.fragments.entry}
  query GetPageData(
    $headerLocation: MenuLocationEnum
    $footerLocation: MenuLocationEnum
  ) {
    generalSettings {
      ...BlogInfoFragment
    }
    headerMenuItems: menuItems(where: { location: $headerLocation }) {
      nodes {
        ...NavigationMenuItemFragment
      }
    }
    footerMenuItems: menuItems(where: { location: $footerLocation }) {
      nodes {
        ...NavigationMenuItemFragment
      }
    }
  }
`;

Component.variables = () => {
  return {
    headerLocation: MENUS.PRIMARY_LOCATION,
    footerLocation: MENUS.FOOTER_LOCATION,
  };
};
Code language: JavaScript (javascript)

It reuses fragments from each imported Component by using the Colocating Fragments pattern. In that case we have fragments from the BlogInfo and NavigationMenu because the component queries data for the general settings and each of the two navigation menu sections in the page.js. Currently the site uses two navigation menus which have to match the Header and Footer locations as denoted from the MENUS.PRIMARY_LOCATION and MENUS.FOOTER_LOCATION constants. You can do that via the WordPress admin page:

Note: Although the example project showcases a conventional way to structure your WPGraphQL queries, you are not required to follow this pattern.