Wonderwall Builder

Wonderwall Builder (WWB) aims to do all the heavy lifting when creating Wonderwalls.

It is built on work using Boiler Room Runner (BRR) and is meant to be used with Boiler Room Builder (BRB), and is opinionated on how Wonderwalls should be built, to ensure consistency from one Wonderwall to the next.

Creating a Wonderwall

1. Add Wonderwall Builder Dependency

yarn add wonderwall-builder

2. Create Your source/client.js and source/server.js

WWB uses BRB and BRR, so these files are where we configure our Wonderwall.

WWB provides us with existing utility functions which will handle most of this configuration for us, and we will just need to pass through some options to specify some of the custom parts of our Wonderwall.

The easiest way to handle these options, is to put them in a central file e.g. source/index.js, and include those in both your source/client.js and source/server.js.

Your setup should look something like this, we will cover these options later in .

source/index.js

import layouts from './layouts'
import { assets, snippets } from './assets'

export default {
    prismicRepo: process.env.PRISMIC_REPO,
    layouts,
    assets,
    snippets
}

source/client.js

import options from './index'
import { createClient } from 'wonderwall-builder'

export createClient(options)

source/server.js

import options from './index'
import { createServer } from 'wonderwall-builder'

export createServer(options)

3. Setup your Configuration

These are the config options available to you in your config object that you pass to createClient and createServer.

prismicRepo (required)

The id of the Prismic repository that contains all of our stories e.g. wonderwall or childrens-hospital

This can be included however you wish, however using .env files are the recommended solution.

layouts (required)

The React components that will handle laying out our pages. There are two required layouts that need to be passed through via the layouts options.

Story

This is mounted for an individual story page. Your Story component will have the story available via the story prop, and can display the story however it wishes, either using generic components via WWB, or completely custom.

Listing

This is mounted for the story listing page. Your Listing component will have the stories available via the stories prop. Again, the stories can be displayed however you wish.

Note that WWB will handle wrapping your components in the containing page, including the header and footer, as well as things such as a styles reset. The idea is that you can create these components and get straight into implementing the design.

assets (optional)

This is an array of assets (JS and CSS) to include in the document. These should include the defaults, which are /main.css and main.js, but can also include other files if needed, such as Google Fonts.

snippets (optional)

Snippets are used for scripts that need to be included. This is used for things like analytic scripts. If you provide just an array of strings to include, WWB will include these above the closing body tag

favicon (optional)

The favicon to be used for the Wonderwall.

Example Config

import Story from './layouts/Story'
import Listing from './layouts/Listing'
import Page from './layouts/Page'

export default {
    prismicRepo: process.env.PRISMIC_REPO,
    layouts: {
        Page,
        Story,
        Listing
    },
    assets: [
        '/main.css',
        '/main.js',
        'https://use.fontawesome.com/a90dc103f0.js',
        'https://fonts.googleapis.com/css?family=Lato:400,700'
    ],
    snippets: [
        '[Google Analytics Snippet]',
        '[Other Snippet]'
    ]
}

4.Configure Your Scripts

We will just utilise BRB scripts to handle our build.

"scripts": {
    "start": "ENV_FILE=.env brb serve",
    "build": "ENV_FILE=.env brb build",
}

Now you can run your app locally.

npm start

And you can do a static build of your Wonderwall.

npm run build

What WWB Handles

The idea of WWB is to handle as much as possible of the reusable parts of building Wonderwalls, while still providing the flexibility to display the Wonderwall as needed, due to the often custom requests for client work.

The following is a list of things that WWB, along with BRB and BRR, will handle for you, so you don't have to include them individual Wonderwall installations.

Build and Static Build

BRB provides us with all the build configuration we need. WWB also handles fetching your stories and generating a static build for your Wonderwall.

Routes

Routing is consistent across installations of the Wonderwall.

/ - index route for story listing

/:story_uid - individual story page

/tags/:tag_uid - listing page for an individual tag

Route Hooks

All of our routes are wrapped to fetch all the data they need. For example, the listing route will fetch us all the stories we need, so that our Listing component we can create can expect an array of stories via the stories prop.

Data

As mentioned above, WWB will fetch all the data we need. This involves actions which fetch the required data from Prismic, and handles them via the relevant reducers to be made available to our components.

Components

WWB has a load of components that you can optionally use to build out your Wonderwall. All of these components can be imported via wonderwall-builder/components.

More documentation on these components to come.

Higher Order Components

There are some HOC's provided to help. connectSettings is one example, which we can wrap one of our components in to give us the ability to read the Wonderwall's settings.

For example, we might be creating a custom button, and we want to know the accent color in this client's settings. We would do something like below.

import React from 'react'
import { connectSettings } from 'wonderwall-builder'

const CustomButton = ({ children, settings }) => (
    <button style={{ backgroundColor: settings.accent }}>{children}</button>
)

export default connectSettings(CustomButton)

CXS and Traits

WWB uses Cxsync as it's CSS in JS solution. Some helpful utils are also provided.

import css from 'cxsync'
import { traits } from 'wonderwall-builder'

const button = css({
    padding: traits.rhythm(1),
    color: '#000'
})

export default ({ children }) => (
    <button className={button}>{children}</button>
)

NOTE: More information to come on configuring your traits. Need to figure out a much better way of passing traits in to WWB, or to just avoid doing it in the first place.

Working on WWB

If you are working on WWB, it is worth running through some the provided scripts.

npm run build

Builds the app into the dist directory for publishing

npm run test:unit

Runs the test suite, which uses Mocha, Chai and Enzyme

npm run test:lint

Runs standard linting on the project

npm test

Runs both the unit testing and the linting