CI Configuration (< PagesJS 1.0.0) | Yext Hitchhikers Platform

Note

This is documentation for the beta version of PagesJS (<1.0.0), which is no longer actively maintained.

For up-to-date documentation, refer to the Site Configuration reference doc.

Yext CI is an all-purpose continuous integration system that runs a frontend toolchain of your choice. The CI runs as the first step of the Sites deployment process. For more information on the Pages deployment process, see the Deployment Process Overview unit.

A typical ci.json file will look something like this:

{
  "artifactStructure": {
    "assets": [
      {
        "root": "dist",
        "pattern": "assets/**/*"
      }
    ],
    "features": "sites-config/features.json",
    "plugins": [
      {
        "pluginName": "Generator",
        "sourceFiles": [
          {
            "root": "dist/plugin",
            "pattern": "*{.ts,.json}"
          },
          {
            "root": "dist",
            "pattern": "assets/{server,static,renderer}/**/*{.js,.css}"
          }
        ],
        "event": "ON_PAGE_GENERATE",
        "functionName": "Generate"
      }
    ]
  },
  "dependencies": {
    "installDepsCmd": "npm install",
    "requiredFiles": ["package.json", "package-lock.json", ".npmrc"]
  },
  "buildArtifacts": {
    "buildCmd": "npm run build"
  },
  "livePreview": {
    "serveSetupCmd": ":"
  }
}

Let’s walk through each key:

artifactStructure

The artifactStructure object defines how the Yext CI system will produce artifacts for your site.  After your build chain has completed, our system uses these properties to determine which output directories in your repository should make up your site.

assets are files that do not change (CSS, JavaScript bundles, images). Each assets property contains two sub-properties:

• root: used to specify the directory that contains the relevant files
• pattern (optional): defines the regex of files that are in-scope within the root directory

features provides the path to features.json, a document generated by the yext pages generate command which specifies stream and template configurations. Here is an example:

{
  "features": [
    {
      "name": "about-your-dentist",
      "streamId": "about-your-dentist",
      "templateType": "JS",
      "entityPageSet": {
        "plugin": {}
      }
    },
  ],
  "streams": [
    {
      "$id": "about-your-dentist",
      "filter": {
        "entityIds": [
          "about-your-dentist"
        ]
      },
      "fields": [
        "id",
        "uid",
        "meta",
        "name",
        "c_relatedFacility.c_relatedDoctors.name",
        "c_relatedFacility.c_relatedDoctors.headshot",
        "c_relatedFacility.c_relatedDoctors.c_richTextDescription"
      ],
      "localization": {
        "locales": [
          "en"
        ],
        "primary": false
      }
    }
  ]
}

The above features.json contains an array of templates and stream configurations. Note: this is an auto-generated document, so you should not edit it.

plugins allows you to specify arbitrary functions that will be fired at pre-defined events in the build process. Below is an example plugin configuration.

"plugins": [
  {
    "pluginName": "Generator",
    "sourceFiles": [
      {
        "root": "dist/plugin",
        "pattern": "*{.ts,.json}"
      },
      {
        "root": "dist",
        "pattern": "assets/{server,static,renderer}/**/*{.js,.css}"
      }
    ],
    "event": "ON_PAGE_GENERATE",
    "functionName": "Generate"
  }
]

pluginName specifies the name of the plugin.

sourceFiles specifies the location of source files where the plugin is defined. Each source file has root and pattern fields, just like the pattern used in the artifactStructure.

event specifies the exact event when the plugin will be fired. Pages supports three event types:

• ON_URL_CHANGE: This occurs whenever a URL on your production deploy changes. The Pages system tracks historical URLs generated for a feature and entity scope over the lifetime of a site. If the URL for an entity within a feature changes on the production deploy, this event will be fired with the new URL and include information about which entity was used when generating the page. This event also fires in a similar manner when publishing a new deploy to production, comparing all new URLs against the old production deploy. Please note that this event only fires for URLs related to entities within the platform, meaning static assets, static templates, and manually configured redirects do not cause this event to fire. This occurs whenever a URL is changed. For example, this event will fire when a Content value returned from getPath function changes. Note: if you are configuring redirects in a redirects.csv file, updates to that file alone will not trigger an ON_URL_CHANGE event.
• This occurs whenever a URL is changed. For example, this event will fire when a Content value returned from getPath function changes. Note: if you are configuring redirects in a redirects.csv file, updates to that file alone will not trigger an ON_URL_CHANGE event.
• ON_PAGE_GENERATE: This occurs when the page is being generated, i.e., when templates and the Content are combined to output HTML.
• API: API event types are serverless functions. This is a plugin that is invoked whenever a certain path on the site is visited.

functionName defines the entry-point for the plugin. This is the function that must be defined in the source files and will be invoked upon event firing.

dependencies

This field specifies the command used to build install required dependencies and the files which list dependencies.

"dependencies": {
  "installDepsCmd": "npm install", // Command used to install
  "requiredFiles": ["package.json", "package-lock.json", ".npmrc"] // Files that specify requirements
}

Note

dependencies is an optional optimization for the build step. It utilizes image layer caching to prevent rerunning the installDepsCmd in subsequent builds if the specified required files are unchanged.

buildArtifacts

buildCmd specifies the command to build your site. Note that this command is also executed when developing locally if yext pages build is run or a watched file is changed while npm run dev is executing.

livePreview

serveSetupCmd (optional) specifies a command to be executed by the live preview system before executing serveCmd - this would be a good place to install any serve dependencies.

serveCmd specifies a command to execute once your Live Preview container is online. This is where you should start up an application to serve your preview at port :8080. If you don’t, the live preview will fail to initialize.

watchCmd specifies a command to watch files for changes and re-execute your build/serve commands accordingly.