#Build System

All of the Layouts, Pages, Collections, Media, and Assets are bundled together during the Build process.

Understanding how this works will help you diagnose and correct problems with your code. Sometimes, an error will not seem to make much sense, but if you understand how everything goes together, you can figure out what went wrong.

#Steps

The general build steps are as follows:

• Load all of the Site's data (Pages, Collections, Media, etc.)
• Add extra values to all Collection Entry fields (create Day.js objects for dates, parse Markdown fields, reference Entries via Relation Fields, etc.)
• Run Collection Build Scripts
• Run Component Build Scripts
• Determine each Page that needs to be created
  • Determine needed objects for dynamic Page paths
  • Run the Page's Data Scripts
  • Generate the Page's markup
  • Template in all data
  • Replace Components used on the Page
    • Parse Component's Attributes
    • Run Component's Data Script
    • Replace all Component Slots
    • Parse Component's markup
    • Parse Component's style
    • Parse Component's script
    • Add Component's style, script, and tags to the Page
  • Template the Page's body into the Layout
  • Add the Layout's style, script, and tags to the Page
  • Store the final index.html, style.css, and script.js for the Page
• Copy the Site's Media to /media
• Merge in the Site's Assets
• Generate the sitemap.xml file
• Generate the robots.txt file
• Add the Site's favicon.png file
• If there are no errors, replace the existing staging files with the new files

#Errors

Because almost all of the Site's content is written manually, there is likely to be Build errors. This is a normal part of the process and you will probably encounter hundreds of errors in the course of generating a website.

When an error is encountered, go to the Build screen to see which step the build failed on. The error output may or may not be extremely helpful. You can click the breadcrumbs to take you to the markup, style, script, etc. where the error occurred, though this may not always be where you need to fix something.

For example, you could have a Component that uses a media-id attribute to show an image. It fails running mediaList.getById(attr.mediaId).getImageUrl(). There's nothing wrong with this line. The real issue is that the Media ID passed in by the Page using the Component doesn't exist.

This is why you should look at each step that occurred down the line to see which Page it failed on and determine why. You can make things easier for yourself by throwing Errors. For example, in that Component's Data Script, you can write:

let media = mediaList.getById(attr.mediaId)
if (!media) throw new Error(`Media with ID: ${attr.mediaId} not found`)

This will be shown in the Build's error output and help you quickly determine what happened.

#Staging and Production

The Build system automatically updates the staging site if there are no errors. The staging site is a special site only accessible to people working on the website. This gives you a place to add new content, try new things, and test before the changes go into Production.

Each path you navigate to on the staging site will be generated as you visit it. Because of this, you may find that the changes you've made to a Page work for the paths you test in the staging site, but there may be errors you're missing on other paths. To test the entire staging site for errors, you can run an Audit. This will build every Page and provide a report.

#Deployment

When everything with the Site is perfect and you're ready to go live, you can deploy the Site to Production. This will do a special Build that uses the production URLs and optimized versions of scripts and send those files to the CDN for hosting.

To build for production, go to the Build screen and click "Deploy to Production". Note that this will not affect the staging Site in any way and further changes to the Site will only affect staging until you manually deploy to Production again.